# BrainAPI deploy profiles

Choose **heavy** or **light** when bringing up a new deployment.

| | Heavy | Light |
| --- | --- | --- |
| Compose | [`docker-compose.heavy.yaml`](docker-compose.heavy.yaml) | [`docker-compose.light.yaml`](docker-compose.light.yaml) |
| Env template | [`env.heavy.example`](env.heavy.example) | [`env.light.example`](env.light.example) |
| Graph | Neo4j | NetworkX on Postgres |
| Data | MongoDB | PostgreSQL |
| Vectors | Milvus | PostgreSQL + pgvector |
| LLMs | GCP Vertex (small) + Azure (large) | DeepSeek (small + large) |
| Embeddings | Azure | OpenAI (`text-embedding-3-large`) |
| Container limits | Full (current production) | Smaller footprint (`mem_limit` / `cpus`) |
| Suggested VM | ~8–16 GB RAM / 4+ vCPU | ~2 GB RAM / 1 vCPU |

## Quick start

```bash
# 1. Copy a profile template outside the repository and replace every secret.
install -m 600 deploy/env.light.example /etc/brainapi/light.env
# Set BRAINAPI_ENV_FILE to the absolute file path in /etc/brainapi/light.env.

# 2. Validate first, then start and wait for health.
docker compose --env-file /etc/brainapi/light.env \
  -f deploy/docker-compose.light.yaml config -q
docker compose --env-file /etc/brainapi/light.env \
  -f deploy/docker-compose.light.yaml up -d --wait
# or
docker compose --env-file /etc/brainapi/heavy.env \
  -f deploy/docker-compose.heavy.yaml up -d --wait
```

Only nginx publishes host ports (`80` and `443`). The API, embedded Console,
and MCP are reached through `/`, `/console/`, and `/mcp`. The checked-in TLS
server rejects handshakes until an operator mounts a certificate-specific
nginx server file; do not expose port 80 beyond a trusted proxy without HTTPS.

## Light sizing

| Service | Heavy | Light |
| --- | --- | --- |
| nginx | 128m / 0.2 CPU | 64m / 0.1 CPU |
| redis | 2048m / 0.5 CPU (`maxmemory 1500mb`) | 256m / 0.1 CPU (`maxmemory 192mb`) |
| postgres | — (not in heavy compose) | 768m / 0.35 CPU |
| neo4j / milvus / mongo / etcd / minio | present | omitted |
| api / worker / mcp | 2–4g / 1–2 CPU | 768m / 0.5 CPU each |
| celery `--concurrency` | 2 | 1 |
| `CELERY_WORKER_CONCURRENCY` | 4 | 1 |

## Notes

- `BRAINAPI_IMAGE`, `BRAINAPI_ENV_FILE`, Redis credentials, and profile backend
  credentials are required and fail during Compose interpolation when absent.
- Mount cloud credentials with a private operator-owned Compose override; no
  host-specific credential path is present in the production profiles.
- Do not mix profiles under the same Compose project name. Their volume layouts
  and restore order differ.

## Backup and restore

Backups default to `/srv/brainapi/backups` and are created with mode `0700`.
They contain sensitive application data (including stored brain credentials),
so encrypt and access-control the backup directory. The generated manifest
contains only profile/version metadata, service names, restore order, and
checksums; it never contains secrets.

```bash
deploy/brainapi-backup backup --profile light \
  --env-file /etc/brainapi/light.env --project-name brainapi
deploy/brainapi-backup verify --profile light \
  --env-file /etc/brainapi/light.env --archive /srv/brainapi/backups/light-UTCSTAMP
deploy/brainapi-backup restore --profile light \
  --env-file /etc/brainapi/light.env --archive /srv/brainapi/backups/light-UTCSTAMP
```

Backup stops nginx, API, MCP, and workers before capture. Restore refuses a
running stack, a profile/image mismatch, a checksum mismatch, or any non-empty
target volume. Use a documented maintenance window and retain the generated
manifest with the release artifacts. Light backups include the system registry
plus an individual custom-format dump for every `brain_*` PostgreSQL database.

## Production validation

The CI-only Compose override supplies a deterministic OpenAI-compatible model
stub; it is not a production deployment file. It lets both profiles exercise
the complete storage and gateway path without external model credentials:

```bash
docker compose -f deploy/docker-compose.light.yaml \
  -f deploy/docker-compose.ci.yaml up -d --wait
python scripts/production_smoke.py exercise --profile light \
  --system-token "$BRAINPAT_TOKEN" --artifact-dir release-artifacts
```

After backup, clean-volume restore, and restart, run the same tool with
`verify-restore`. CI retains the profile smoke, latency, restore, backup
manifest, image audit, and SBOM evidence. The tag workflow downloads the exact
commit's successful light and heavy artifacts and runs the release-readiness
gate before any image can be published. Quality CI exports one `linux/amd64`
candidate archive; the heavy runner loads that same archive, and the tag
workflow publishes it unchanged after verifying its recorded image ID.

## Public documentation sandbox

The anonymous sandbox is an opt-in extension of the light profile. Merge
[`env.public-demo.example`](env.public-demo.example) into the deployment's
private environment, deploy the current API and worker image, and seed only the
dedicated `agentdemo` brain:

```bash
docker compose --env-file /etc/brainapi/light.env -f deploy/docker-compose.light.yaml up -d
docker compose --env-file /etc/brainapi/light.env -f deploy/docker-compose.light.yaml exec brainapi \
  python scripts/seed_public_demo.py --api-url http://localhost:8000
```

The seed command downloads the published V2 documentation, records its SHA-256
marker, skips an already-current corpus, and polls the asynchronous ingestion
task. It requires the private system `BRAINPAT_TOKEN` inside the deployment; do
not expose that token through the gateway. The seed command explicitly creates
the brain; `BRAIN_CREATION_ALLOWED` does not enable implicit API provisioning.

Expose the API origin as `api.brain-api.dev`, with TLS, and put the Cloudflare
gateway in front of root-domain `/api/*`. The application itself deliberately
does not implement client rate limiting; the checked-in gateway owns the
30-request/60-second demo limit.


## Brain registry contract

The persisted registry is authoritative. Retrieval, query, agent, and MCP access
cannot provision an unknown brain, even with `BRAIN_CREATION_ALLOWED=true`.
Explicit unknown API scopes return `404 BRAIN_NOT_FOUND`. A missing scope can
resolve to `default` only when `DEFAULT_BRAIN_FALLBACK=true` and that brain is
already registered. Create brains with `POST /system/brains` or
`POST /system/workspaces`; duplicate brain creation returns
`409 BRAIN_ALREADY_EXISTS`, including concurrent inserts.

Brain IDs accept 1–128 ASCII letters, digits, hyphens, and underscores, starting
with a letter or digit. `system` is reserved (case insensitive). The same rules
apply to create, clear, and delete; workspace slugs retain their narrower syntax.
`/system/brains-list` returns persisted registry identities only. Orphan physical
databases never appear as registered brains or acquire generated PATs.

Clear preserves registered identity and physical storage. Explicit delete also
removes the PostgreSQL database, including a named orphan without a registry
row. These are destructive operations: target only an intended identifier.

Run the deterministic gate and the opt-in real integration gate:

```bash
PYTHONPATH=.:tests python -m pytest -q tests/test_brain_registry_contract.py tests/test_brain_lifecycle.py
BRAINAPI_REGISTRY_TEST_CONTAINER=<disposable-local-container> \
  PYTHONPATH=.:tests python -m pytest -q tests/integration/test_brain_registry_contract.py
```

The integration gate requires a disposable local HF CPU container with the
candidate source and its normal entrypoint environment. It invokes
`bash /app/entrypoint.sh --qualify-registry`, compares actual PostgreSQL catalogs
and application Redis state around unknown GET/search/context requests, tests
concurrent storage inserts, and deletes only its own collision-checked temporary
namespaces. It does not clean production probe artifacts or other existing brains.