Deploy & environment

Local development

# From monorepo root — multi-process helper
./start-services.sh

# Or individually
cd locus-backend && dotnet run          # :5000 / :5069
cd locus-workers && python server.py    # :8000
cd locus-web && bun run dev             # :3000
cd locus-ops && bun run dev             # :3001

Copy each service’s .env.example → .env / .env.local. Seed is off by default (Seed:RunOnStartup=false).

Environment map

Service	Critical vars
locus-web	LOCUS_API_BASE_URL, SESSION_SIGNING_KEY, R2_*, REDIS_URL (prod), DOCUMENT_ENCRYPTION_KEY_HEX (prod), LOCUS_WORKER_URL, COPILOT_LLM_*
locus-ops	LOCUS_API_BASE_URL, SESSION_SIGNING_KEY, R2_* or LEGAL_VAULT_LOCAL_DIR
locus-backend	Connection string, Auth:*, LEGAL_VAULT_*, Redis, worker URL — see locus-backend/.env.example / appsettings placeholders
locus-workers	Bind host/port; Tesseract in image

Emergency-only (never prod): LOCUS_ALLOW_INMEMORY_QUEUE, LOCUS_ALLOW_PLAINTEXT_DOCUMENTS.

Coolify / Docker

1. One app per Dockerfile (locus-web, locus-backend, locus-workers) + managed Postgres/Redis.
2. Inject secrets at runtime; mark “Not available during build”.
3. Point LOCUS_API_BASE_URL / REDIS_URL / LOCUS_WORKER_URL at internal hostnames.
4. Runtime-only change → Restart; build-time (NEXT_PUBLIC_*) → Redeploy.
5. Ports: local bun run dev uses 3000 (web) / 3001 (ops); the web Docker image may default to 3002 — map Coolify public ports accordingly.

CI & test matrix

Suite	Command / location
Unified	bash run-all-tests.sh
Web	cd locus-web && bun test && bun run build
Backend	cd locus-backend && dotnet build
Workers	cd locus-workers && python -m unittest
Migrations / DR	bash scripts/backup-and-migrations-verify.sh
GitHub Actions	.github/workflows/ci.yml (web, python, backend, secrets, release-and-dr)

Tracker: root IMPLEMENTATION_TRACKER.md (Demo vs Production slices).

Production checklist (abbrev.)

• [ ] SESSION_SIGNING_KEY set on web + ops
• [ ] R2 credentials + bucket; encryption key in prod
• [ ] Redis required; no LOCUS_ALLOW_*
• [ ] Seed off; no committed DB passwords
• [ ] CORS / public URLs correct
• [ ] Watchtower interval intentional (default 0)
• [ ] Official vault PDFs attached in ops (not only CI fixtures)

OCR / citation ops

Human override when OCR confidence is low or Actif≠Passif: OCR override SOP.

Docs site (docs-site/)

Static VitePress site. Not wired into Coolify yet — deploy as a separate static app.

cd docs-site
bun install
bun run dev       # local :5173
bun run build     # → docs-site/.vitepress/dist
bun run preview   # serve the dist locally

Host	How
Coolify (recommended, matches the stack)	New Static resource → Base Directory docs-site → Build bun install && bun run build → Publish directory .vitepress/dist → domain e.g. docs.your-domain
Cloudflare Pages	Connect repo → root docs-site → build bun run build → output .vitepress/dist
GitHub Pages	Workflow: build, upload .vitepress/dist; set base: '/repo-name/' in .vitepress/config.ts if not on a custom domain

No SoR / Redis / secrets required. Optional: put the site behind Coolify auth or Cloudflare Access if docs should stay internal.