Skip to Content
DevelopmentLocal development

Local development

Run Greenlight on your machine for hacking on core/, ui/, and docs-site/.

For a first working prompt, start with the Development quickstart. To deploy for production, see Self-Hosting Docker.

Postgres runs in Docker; the API, admin UI, and docs run on the host with hot reload.

npm run setup          # creates .env with generated secrets if missing,
                       # then install + Postgres + migrate
npm run dev            # core :8100, ui :3001, docs :3003
curl http://localhost:8100/healthz

docker compose up -d (default) starts Postgres only. App services use Compose profile full.

ServiceHost portRole
postgres5431 (POSTGRES_PORT)PostgreSQL 16
npm dev:core8100API + webhooks
npm dev:ui3001Admin UI
npm dev:docs3003Product docs

Useful commands:

npm run infra:up          # start Postgres
npm run infra:down        # stop Postgres
npm run infra:reset       # wipe Postgres volume
npm run db:migrate        # UI admin_users migration
npm run docker:logs       # logs when using full profile

If 5431 is already in use, set POSTGRES_PORT in .env and use the same port in DATABASE_URL.

Full Docker stack

All services containerized (no host hot reload):

npm run docker:full
# same as: docker compose --profile full up -d --build
curl http://localhost:8100/healthz
ServiceHost portRole
greenlight8100API + webhooks
greenlight-ui3001Admin UI
greenlight-docs3003Product docs
postgres5432PostgreSQL 16
npm run docker:full:down
docker compose --profile full logs -f greenlight greenlight-ui greenlight-docs

Compose files (local)

FileRole
docker-compose.ymlDefault entry — includes docker-compose.dev.yml
docker-compose.dev.ymlLocal development — Postgres by default; apps under full profile

Migrations

ComponentMechanismWhen
coreschema.sql applied on bootEvery start (prompts, channels, …)
uiDrizzle SQL via Docker entrypointContainer start (admin_users)
ui (hybrid)npm run db:migrateAfter infra:up / as part of npm run dev
OpenAPILicensing