# Production deployment

This bundle builds the Go services and both Art Design Pro applications from
source. PostgreSQL (with pgvector), two Redis roles, MinIO (object storage, M8)
and a local Ollama container (vectorization, M8) are included; ClickHouse is not
required. Neither MinIO nor Ollama is a startup dependency: the gateway warns
and refuses file uploads until the bucket is reachable, and knowledge-base
documents are still stored (with embedding set to NULL) when Ollama is down,
with retrieval falling back to full-text search.

## Prerequisites

- Docker Engine with Compose v2
- At least 4 CPU cores, 8 GiB RAM and 30 GiB free disk for an initial build
- An external TLS reverse proxy or load balancer
- A backup destination for the PostgreSQL volume

## First deployment

Run all commands from the repository root:

```bash
cp deploy/production.env.example deploy/production.env
chmod 600 deploy/production.env
# Edit deploy/production.env and replace every CHANGE_ME value.

docker compose \
  --env-file deploy/production.env \
  -f deploy/docker-compose.production.yml \
  config --quiet

docker compose \
  --env-file deploy/production.env \
  -f deploy/docker-compose.production.yml \
  up -d --build
```

Create the initial administrator once:

```bash
docker compose \
  --env-file deploy/production.env \
  -f deploy/docker-compose.production.yml \
  --profile tools run --rm bootstrap-admin
```

Then remove `BOOTSTRAP_ADMIN_PASSWORD` from `deploy/production.env` and use the
admin UI to create database-backed gateway API keys.

## Endpoints

- API and OpenAI-compatible gateway: `127.0.0.1:8080`
- Admin UI: `http://127.0.0.1:8081/admin/`
- Portal UI: `http://127.0.0.1:8082/portal/`
- Liveness/readiness: `/healthz` and `/readyz`

Ports bind to loopback by default. Terminate TLS at a reverse proxy and forward
to these endpoints. Change `*_BIND_IP` only when the host firewall and network
policy are already in place.

## Operations

Check status and logs:

```bash
docker compose --env-file deploy/production.env -f deploy/docker-compose.production.yml ps
docker compose --env-file deploy/production.env -f deploy/docker-compose.production.yml logs --tail=200 gateway-api
curl --fail http://127.0.0.1:8080/readyz
```

For upgrades, back up PostgreSQL first, change `GATEWAY_VERSION`, then run the
same `up -d --build` command. The one-shot migrator applies forward migrations
before the API starts. Do not use `docker compose down -v` in production because
it removes persistent data.

The bundled database URLs use `sslmode=disable` only for the private Compose
network. When using an external PostgreSQL or Redis service, require TLS and use
`sslmode=verify-full` / `rediss://` as supported by that service.

### Vectorization and object storage

- The PostgreSQL image is `pgvector/pgvector:pg17` (data-volume compatible with
  `postgres:17-alpine`); migration `000024` creates the `vector` extension and
  adds the HNSW embedding column. `EMBEDDING_DIM` must stay at `1024` to match
  the `vector(1024)` column.
- Ollama runs locally and lazily pulls `bge-m3` (~1.2 GiB) on first embedding
  request. Set `EMBEDDINGS_ENABLED=false` to disable vectorization entirely.
- Back up the `minio-data` and `ollama-models` volumes alongside PostgreSQL.
- If you previously deployed with `postgres:17-alpine`, back up the PostgreSQL
  volume before switching images.