Development Setup

Welcome to the Corgtex engineering team. Follow this guide to set up your local development environment for the monorepo.

Prerequisites

Node.js >=22.22.0 and <23 (root package.json engines.node)
npm >=10 (root engines.npm; the repo pins packageManager npm@10.9.4)
Docker and Docker Compose, used for local Postgres (docker-compose.yml) and integration-test Postgres (docker-compose.test.yml)
Git

1. Clone and Install

git clone https://github.com/Corgtexdotcom/corgtex.git
cd corgtex
npm install

This is an npm workspaces monorepo (apps/site, apps/web, apps/worker, packages/*). Install from the repository root.

2. Infrastructure (Database)

Local npm development talks to Postgres on localhost:5432. In the default docker-compose.yml that service is named db (image pgvector/pgvector:pg16), not postgres.

docker compose up -d db

Do not start the full default compose file while using npm run dev: it also starts a web container on port 3000 and a second worker. docker-compose.selfhost.yml is the packaged self-host stack (postgres + web + worker), not the contributor npm run dev path. docker-compose.test.yml is only for integration tests (host port 5433). The default compose file also defines a redis service. Local .env.example does not set REDIS_URL; npm dev does not start Redis.

3. Environment Variables

Copy the public template. Point DATABASE_URL at local Postgres (the example already uses localhost).

cp .env.example .env

.env.example includes ADMIN_EMAIL / ADMIN_PASSWORD for the bootstrap admin, SESSION_COOKIE_SECRET, and optional MODEL_PROVIDER / MODEL_API_KEY for hosted models. If you plan to test AI completions locally, set a valid MODEL_API_KEY and matching MODEL_PROVIDER. Never commit .env files.

4. Prisma Setup

Before you start the Next.js server, generate the Prisma Client and apply pending migrations. Use migrate deploy locally; do not use prisma db push or npm run prisma:push.

# Generate the TypeScript client based on the current schema
npm run prisma:generate

# Apply migrations to your local Postgres container
npm run prisma:migrate:deploy

# Run the production bootstrap seed to create the configured workspace/admin baseline
npm run prisma:seed

# Optional: create the E2E UI user from AGENT_E2E_EMAIL / AGENT_E2E_PASSWORD
npm run seed:e2e

# Optional: load the Corgtex dogfood workspace fixture explicitly
npm run seed:dogfood

# Optional: load only the JNJ demo fixture explicitly
npm run seed:jnj-demo

# Optional: load both dogfood and JNJ demo fixtures explicitly
npm run seed:dogfood-demo

The J&J demo seed is refreshable and includes public-safe showcase data for current product surfaces such as goals, agent identities, agent observability, recognitions, audit logs, governance, finance, meetings, and the Organization Brain. Shared demo deployments can set CORGTEX_AUTO_SEED_JNJ_DEMO=true so each deploy refreshes the demo after migrations and the base seed.

5. Run the Application

Root npm run dev starts both processes with concurrently:

npm run dev:web → @corgtex/web (next dev with ../../.env), typically http://localhost:3000
npm run dev:worker → @corgtex/worker (tsx watch with the same .env)

npm run dev

To run one process:

npm run dev:web
npm run dev:worker

Log in with ADMIN_EMAIL and ADMIN_PASSWORD from .env. The marketing app (npm run dev:site, Next.js on port 3008 in apps/site) is not started by npm run dev.

6. Checks while developing

npm run check
npm run test:unit

Integration tests and the database-independent production build are documented in Testing.

​Prerequisites

​1. Clone and Install

​2. Infrastructure (Database)

​3. Environment Variables

​4. Prisma Setup

​5. Run the Application

​6. Checks while developing