Self-hosting

Create an installation

The fastest path is the CLI. It creates a project that depends on @headless-lms/server, owns its config and plugins, and deploys anywhere Node and Postgres run.

npm create headless-lms

Run the repo locally

To develop against the source, you'll need Node ≥ 22, pnpm 10, and Docker. The following brings up Postgres, MinIO and Hatchet, applies migrations, and starts the api, admin and student apps.

pnpm install
docker compose -f docker/docker-compose.yml up -d   # Postgres, MinIO, Hatchet
cp .env.example .env        # set BETTER_AUTH_SECRET and CREDENTIAL_STORE_KEY
                            # (openssl rand -base64 32 for each)
pnpm db:generate && pnpm db:migrate
pnpm dev                    # api :8000 · admin :8001 · student :8002

.env.example documents every variable and the command that mints a Hatchet token for the local hatchet container.

These commands run across all workspaces:

• pnpm build · pnpm test · pnpm lint · pnpm typecheck
• pnpm gen:sdk regenerates the OpenAPI spec and SDK (the database must be running).

Default ports

• :8000 — API
• :8001 — Admin dashboard
• :8002 — Student portal
• :8005 — Postgres · :8006/:8007 — MinIO (API / console)
• :8008/:8009 — Hatchet (gRPC / dashboard)