# 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:

```powershell
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

```powershell
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:

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

## Validation

For a public source checkout:

```powershell
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:

```powershell
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`](../PUBLIC_DEPLOYMENT.md), not the development procedure.