Development setup

Prerequisites

Git;
Go 1.26.6;
Node.js 24 or newer and pnpm 10.33 or newer;
Python 3 with the packages in requirements-dev.txt;
PowerShell 7;
Docker Engine and Docker Compose;
Chromium for Playwright end-to-end tests.

Bootstrap

From a clean checkout:

Copy-Item .env.example .env
pwsh -NoProfile -File scripts/bootstrap.ps1

The example environment uses mock authentication and local-only credentials. Never reuse production credentials, backups, dashboards, telemetry, or host inventories.

Run the development stack

docker compose -f deploy/compose.yaml -f deploy/compose.dev.yaml up --build

The development override publishes the web, API, and PostgreSQL ports for local testing. Treat those ports as development-only and use a host firewall when working on an untrusted network.

Stop only this stack with:

docker compose -f deploy/compose.yaml -f deploy/compose.dev.yaml down --volumes

Validation

For a public source checkout:

pwsh -NoProfile -File scripts/public-verify.ps1

The optional real source-to-browser smoke uses an isolated Compose project and tears it down after the run:

pwsh -NoProfile -File scripts/integration-smoke.ps1

PostgreSQL integration tests use explicit process-local test DSNs. Never point them at a database that contains data you need to keep.

Production separation

production uses OIDC and rejects mock authentication;
the base/production profiles do not publish PostgreSQL or the API;
runtime secrets remain outside Git;
fixtures are synthetic;
the agent remains read-only and receives no Docker socket;
production changes follow ../PUBLIC_DEPLOYMENT.md, not the development procedure.

1.8 KiB Raw Permalink Blame History