Local development

​

Quickstart (full stack in Docker)

git clone https://github.com/B3dmar/3ngram && cd 3ngram
cp .env.example .env                       # defaults work as-is for local Docker

# 1. Initialize the database: migrate -> provision roles -> set app_user password
docker compose --profile init up migrations   # runs to completion, then exits

# 2. Bring up the data plane + server
docker compose up -d postgres redis server

# 3. Seed the dev user + golden set AND mint a demo API key (printed once)
set -a; source .env; set +a                # see step 2 of the manual setup below
pnpm install --frozen-lockfile
pnpm seed                                  # prints: 3ng_<prefix>_<secret>

# 4. Call the API with the printed key
curl -H "X-API-Key: 3ng_<prefix>_<secret>" \
  "http://localhost:3000/api/v1/briefing?kind=all"
# -> 200

• The migrations service and the server service both build from apps/server/Dockerfile (the migrations build target adds psql); server exposes 3000:3000 with a Node-fetch /health probe.
• pnpm seed runs on the host (not in a container) because it loads the committed eval fixtures; it connects to Postgres on the published port 54320. The demo API key (name self-host demo) is minted once and is idempotent — re-running prints “already present” rather than re-issuing.
• APP_USER_PASSWORD defaults to app-user-dev (compose) — override it in .env for anything beyond a throwaway local stack. Because the host-run pnpm seed reads the literal DATABASE_URL (it does not derive the password from APP_USER_PASSWORD the way compose does for the server service), change the password in both APP_USER_PASSWORD and the password segment of DATABASE_URL — overriding one alone desyncs the two and pnpm seed fails with an auth error.
• A worker container is not in compose yet (no apps/worker/Dockerfile); BullMQ jobs need a separate deployable before they are part of the self-host stack.

​

Prerequisites

• Docker (compose v2), Node ≥ 22, pnpm 11.9.0 (corepack enable uses the version pinned by the repository; on Node ≥ 25, which dropped corepack, run npm install -g pnpm@11.9.0 instead)
• psql client

​

1. Start the services

docker compose up -d postgres redis

​

2. Configure the environment

set -a; source .env; set +a

​

3. Migrate

pnpm install --frozen-lockfile
pnpm db:migrate          # drizzle-kit migrate, runs on the unpooled (owner) URL

​

4. Provision roles

psql "$DATABASE_URL_UNPOOLED" -f scripts/provision-roles.sql
psql "$DATABASE_URL_UNPOOLED" -c "ALTER ROLE app_user PASSWORD '<password>'"

​

5. Seed (optional)

pnpm seed

psql "$DATABASE_URL_UNPOOLED" -c "SELECT memory_type, count(*) FROM memories GROUP BY 1 ORDER BY 2 DESC"

​

6. Run the test suites against it

pnpm test                 # unit (no DB)
pnpm test:integration     # the mandatory suites, serial (fileParallelism=false)

​

Resetting

docker compose down -v    # drops the pgdata volume — full reset

​

Deployment boundaries and gaps

• worker container — the server container exists; the worker needs a separate deployable before it is part of the self-host stack.
• hosted dashboard — the dashboard UI is proprietary and maintained in a separate private repository; the Apache server includes the REST/auth routes clients need, but this repository does not ship that UI.
• embedding provider — seeded memories have cached vectors, but every search query and new write still needs an embedding. Set both LLM_GATEWAY_URL and LLM_GATEWAY_API_KEY; without them, search returns 503 embedding_unavailable while non-search reads and writes remain available.