Installation

This guide covers every step of installing EOS Hub, from cloning the repository to running the application in development and production.

System Requirements

Requirement	Minimum	Recommended
Node.js	20.x	22.x (LTS)
PostgreSQL	15	16+
RAM	2 GB	4 GB+
Disk	1 GB	2 GB+

Step 1: Clone the Repository

git clone https://github.com/your-org/eos-hub.git
cd eos-hub

Step 2: Install Dependencies

Using npm:

npm install

Or with pnpm (recommended for faster installs):

pnpm install

Step 3: Environment Variables

Copy the example environment file:

cp .env.example .env

See the Configuration page for a full reference of all environment variables. The minimum required variables are:

DATABASE_URL="postgresql://user:password@localhost:5432/eos_hub"
NEXTAUTH_SECRET="your-random-secret"
NEXTAUTH_URL="http://localhost:3000"

Step 4: Database Setup

Create the Database

If you have not already created the PostgreSQL database:

createdb eos_hub

Or via psql:

CREATE DATABASE eos_hub;

Run Migrations

Apply all database migrations:

npx prisma migrate dev

This creates all tables, indexes, and relations defined in the Prisma schema.

Generate Prisma Client

The Prisma client is generated automatically during migrate dev, but you can regenerate it manually:

npx prisma generate

Seed the Database

Populate the database with sample data for development:

npx prisma db seed

INFO

The seed script creates a complete demo environment including an organization, teams, users with various roles, sample Rocks, Scorecard measurables, Issues, and a V/TO.

Prisma Studio

To visually browse and edit database records:

npx prisma studio

This opens a browser-based database GUI at http://localhost:5555.

Step 5: Run the Application

Development Mode

npm run dev

The application starts at http://localhost:3000 with hot module replacement enabled.

Production Build

npm run build
npm run start

WARNING

Always run npx prisma migrate deploy (not migrate dev) in production environments. The dev variant will reset the database if it detects drift.

Verifying the Installation

After starting the development server:

1. Open http://localhost:3000 -- you should see the login page.
2. Sign in with admin@example.com / password.
3. Navigate to the Dashboard -- you should see KPI cards and charts with sample data.
4. Open the Scorecard -- verify that measurables and weekly data are visible.

If any step fails, check the terminal output for errors. Common issues are covered below.

Troubleshooting

Database Connection Refused

Error: P1001: Can't reach database server at `localhost:5432`

Ensure PostgreSQL is running and the DATABASE_URL in .env is correct.

Migration Fails

Error: P3005: The database schema is not empty

If you are starting fresh, reset the database:

npx prisma migrate reset

WARNING

This drops all data. Only use this in development.

Port Already in Use

Error: listen EADDRINUSE :::3000

Either stop the other process on port 3000 or start EOS Hub on a different port:

PORT=3001 npm run dev

Node.js Version Mismatch

If you see syntax errors or unexpected behavior, verify your Node.js version:

node --version

Use nvm to switch versions if needed:

nvm install 22
nvm use 22

Next Steps

• Configuration -- Full environment variable reference
• Getting Started -- Quick walkthrough of the app