docker-compose-prod.yml
Rama main · réplica de lectura del repositorio original.
# Production. `make prod`.
#
# docker compose --env-file backend/.env -f docker-compose-prod.yml pull
# docker compose --env-file backend/.env -f docker-compose-prod.yml up -d
#
# The images are pulled, not built: `ghcr.io/vstorm-co/agenticos-backend` at
# the `AGENTICOS_VERSION` in `backend/.env` - a release, `latest` when unset,
# or the `sha-<short>` a commit published, which is what `scripts/deploy.sh`
# pins. Pin a release rather than tracking `latest` on a host you care about,
# and pin it from that release's checkout (`git checkout v<version>`): the
# sandboxd image below is pinned in this file, at the version that release's
# backend speaks, so this file and the backend tag must come from one commit.
#
# Prerequisites:
# 1. `backend/.env` with real secrets. The same file serves every environment;
# there is no `.env.prod`. Work through the production checklist in
# `docs/configuration.md` first — VAULT_MASTER_KEY especially.
# 2. A reverse proxy in front of this stack. `nginx/nginx.conf` is the
# template; it proxies to `backend:8000` and `frontend:3000`, and both
# names are provided as network aliases below.
#
# The frontend is `docker-compose-prod.frontend.yml`.
#
# Two networks, deliberately:
#
# `data` — internal, no route off the host. Postgres and Redis live here and
# have no business reaching the internet.
# `edge` — an ordinary bridge. The app needs it: every agent run calls a
# model provider, and an MCP connection calls a vendor's server.
#
# This used to be one network marked `internal: true`, which blocks egress. The
# database was correctly unreachable and so was api.anthropic.com, so no agent
# could have answered anything.
# Every service's log, capped. Docker's `json-file` driver keeps a container's
# output until the container is removed, and nothing else on the host rotates it:
# prod held 570 MB of logs and growing when this was added (#2228). Five files of
# 20 MB is about a day of a busy API and every line `docker compose logs` needs.
x-logging: &logging
driver: json-file
options:
max-size: 20m
max-file: "5"
services:
# Runs the migrations and exits; `app` and `worker` wait for it to have
# completed. This is what `make prod` and `scripts/deploy.sh` used to do with
# an `exec` after `up`, and what a bare `docker compose up -d` on this file
# did not do at all. `docker compose logs migrate` is where a failed migration
# says why the API never started.
migrate:
logging: *logging
image: ghcr.io/vstorm-co/agenticos-backend:${AGENTICOS_VERSION:-latest}
command: agenticos db upgrade
env_file:
- ./backend/.env
environment:
- ENVIRONMENT=production
- POSTGRES_HOST=db
- REDIS_HOST=redis
networks:
- data
depends_on:
db:
condition: service_healthy
restart: "no"
app:
logging: *logging
image: ghcr.io/vstorm-co/agenticos-backend:${AGENTICOS_VERSION:-latest}
# Longer than background.drain()'s 30s timeout, or Docker's 10s default
# SIGKILLs the container mid-drain and an upload stays `processing` (#11).
stop_grace_period: 40s
volumes:
- media_data:/app/media
env_file:
- ./backend/.env
environment:
- DEBUG=false
- ENVIRONMENT=production
- POSTGRES_HOST=db
- REDIS_HOST=redis
# Empty unless the sandbox profile is up. Note what is absent from
# this service: the Docker socket.
# --ws websockets-sansio: uvicorn's `auto` picks the legacy websockets impl,
# which fails the handshake against websockets >=14. The chat WS needs it in
# production exactly as much as it does locally.
#
# --workers puts uvicorn's own `Multiprocess` supervisor at PID 1, and it is
# deliberately left there (#358): it replaces a worker that died, and pings
# the live ones over a pipe. What the ping cannot see is a worker whose
# event loop is blocked, because a thread (`Process.always_pong`) answers it
# regardless - so the worker judges its own loop (`app/core/watchdog.py`)
# and kills itself, which this supervisor replaces twice a second.
# Subclassing it instead would have meant owning four upstream call sites
# in the one process whose job is to survive whatever killed the worker.
#
# That leaves the ping one job: a process that is stopped outright. Its
# default window of 5 seconds is shorter than a starved host takes to
# answer, and on prod it killed live workers and their half-started
# replacements 17 times in 20 minutes (#2223) - each one an import of the
# whole application, added to the CPU pressure that got it killed. A
# minute costs nothing the watchdog does not already cover.
#
# How many workers is a deployment's decision, not a constant: each one is a
# *spawned* process that imports the application on its own - 460 MiB
# measured, with no copy-on-write to share - so four of them are 1.9 GB
# before a request arrives. Four suits a busy deployment; a team of ten is
# better served by two, which still leaves one serving while the watchdog
# replaces a wedged sibling. The memory limit below is sized for the
# default; lower both together.
command: >-
uvicorn app.main:app --host 0.0.0.0 --port 8000
--workers ${UVICORN_WORKERS:-4}
--timeout-worker-healthcheck ${UVICORN_WORKER_HEALTHCHECK_TIMEOUT:-60}
--ws websockets-sansio
networks:
data:
visuals:
browser:
edge:
aliases:
- backend
ports:
# Loopback by default, for the reason the frontend's compose file gives:
# the reverse proxy is the way in, and an auth rate limit keyed on a
# forwarded address is only a limit while nothing can reach past it.
- "${BIND_HOST:-127.0.0.1}:8000:8000"
depends_on:
migrate:
condition: service_completed_successfully
redis:
condition: service_healthy
# Moved out of backend/Dockerfile, which the worker shares and could
# never answer; see docker-compose.yml for the whole reasoning, including why
# `raise_for_status` and a 30s start_period are not what the image had. Four
# workers import the application four times, so the grace matters more here.
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/api/v1/health', timeout=5)"]
interval: 30s
timeout: 10s
retries: 3
start_period: 30s
restart: unless-stopped
deploy:
resources:
limits:
cpus: "3"
# Four workers at the 460 MiB each one measures, plus the supervisor
# and room for a request holding a large transcript. It was 1G, which
# is under what the default `--workers 4` needs to *start* - so the
# shipped limit OOM-killed the container the first time all four were
# warm. Lower it with `UVICORN_WORKERS`: about 600M per worker.
memory: 2560M
reservations:
cpus: "0.5"
memory: 512M
db:
logging: *logging
# pgvector, not stock postgres: the RAG store runs
# `CREATE EXTENSION IF NOT EXISTS vector` when a collection is first
# written to, and on postgres:16-alpine that fails with
# `extension "vector" is not available`.
image: pgvector/pgvector:pg16
# Postgres ships defaults sized for a machine from 2005 - `shared_buffers`
# is 128 MB whatever the host has. These are the standard ratios against the
# 2G limit below, so the two move together: a quarter of it resident, and
# `effective_cache_size` describing what the host's page cache is likely to
# be holding on top. `random_page_cost` and `effective_io_concurrency` say
# the storage is an SSD, which every deployment of this now is.
#
# `max_connections` is sized to what the pools can open, not left at 100.
# Each API worker holds two pools of `DB_POOL_SIZE + DB_MAX_OVERFLOW` (15) -
# the session's and the vector store's - so the default four workers can open
# 120, and the background worker another 30 plus its listener and its ingest
# children. Past 100, Postgres refuses the connection outright with "too many
# clients", before any pool timeout or 503 can shed the load in order. Raise
# it with `UVICORN_WORKERS` or the pool settings.
#
# `pg_stat_statements` records what each statement costs, which is the only
# place a slow query shows up without reading logs (#2228). It has to be
# loaded at server start; the migration that creates the extension is
# `0143_pg_stat_statements`, and `doctor` says whether it is recording.
command: >-
postgres
-c max_connections=200
-c shared_preload_libraries=pg_stat_statements
-c shared_buffers=512MB
-c effective_cache_size=1536MB
-c maintenance_work_mem=128MB
-c work_mem=8MB
-c wal_buffers=16MB
-c random_page_cost=1.1
-c effective_io_concurrency=200
-c max_parallel_workers_per_gather=2
# Parallel query workers pass tuples through POSIX shared memory, which is
# `/dev/shm` - and Docker gives a container 64 MB of it. A parallel scan over
# a collection's vectors then fails with "could not resize shared memory
# segment", which reads as a corrupt index rather than as a container
# setting.
shm_size: 512mb
environment:
- POSTGRES_USER=${POSTGRES_USER:-postgres}
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
- POSTGRES_DB=${POSTGRES_DB:-agenticos}
volumes:
- postgres_data:/var/lib/postgresql/data
# No published port, and no egress: `data` is internal.
networks:
- data
# See docker-compose.yml for why `service_healthy` needs a grace to wait
# through. This is the file the deploy runs, and the one where a missing
# grace failed the redeploy that fixed the outage before it (#1831).
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres}"]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s
restart: unless-stopped
deploy:
resources:
limits:
cpus: "2"
memory: 2G
redis:
logging: *logging
image: valkey/valkey:8-alpine
# A cache with no ceiling is a cache that grows until the container is
# killed, and this one holds rate-limit buckets, channel dedupe claims and
# membership answers - all of which are rebuildable, none of which is worth
# an OOM. `allkeys-lru` because everything here has a TTL anyway; the policy
# only decides what goes first if one is ever forgotten.
#
# `--save ''` and no volume: nothing in here is worth keeping across a
# restart, and keeping it is what took production down in #1830 - Valkey 8
# forks Redis 7.2 and refuses the RDB format version 12 that redis:7-alpine
# left behind, so the container crash-looped and every service that waits on
# it stayed in `Created`. A cache that cannot be reloaded is a cache that
# cannot be corrupted.
command: >-
valkey-server --requirepass ${REDIS_PASSWORD:?REDIS_PASSWORD is required}
--maxmemory 384mb --maxmemory-policy allkeys-lru --save ''
networks:
- data
healthcheck:
test: ["CMD", "valkey-cli", "-a", "${REDIS_PASSWORD}", "ping"]
interval: 10s
timeout: 5s
retries: 5
start_period: 10s
restart: unless-stopped
deploy:
resources:
limits:
cpus: "0.5"
memory: 512M
# The background worker: ingestion, syncs, fired triggers, cleanups and the
# scheduled sweeps, claimed from the queue in Postgres (#2219). It replaced a
# Prefect server and runner whose process-per-run model is what starved this
# host on 2026-10-18 - one long-lived process now, importing the application
# once.
worker:
logging: *logging
image: ghcr.io/vstorm-co/agenticos-backend:${AGENTICOS_VERSION:-latest}
volumes:
- media_data:/app/media
command: python -m app.worker
env_file:
- ./backend/.env
environment:
- DEBUG=false
- ENVIRONMENT=production
- POSTGRES_HOST=db
- REDIS_HOST=redis
# One ingest child by default here: with its limit below, that is the
# worker (~450 MiB) plus one parse of up to WORKER_INGEST_MEMORY_MB, inside
# the container's own ceiling - so the watchdog stops a runaway parse, and
# says so, before the kernel kills anything. Raise both together.
- WORKER_INGEST_CHILDREN=${WORKER_INGEST_CHILDREN:-1}
# Egress too: ingestion calls an embedding provider.
networks:
- data
- edge
- visuals
- browser
depends_on:
migrate:
condition: service_completed_successfully
redis:
condition: service_healthy
# Touched after every heartbeat that reached the database. See
# docker-compose.yml.
healthcheck:
test: ["CMD", "python", "-c", "import os, sys, time; sys.exit(time.time() - os.stat(os.environ.get('WORKER_HEALTH_FILE', '/tmp/agenticos-worker-alive')).st_mtime > 90)"]
interval: 15s
timeout: 5s
retries: 3
start_period: 90s
stop_grace_period: 45s
restart: unless-stopped
deploy:
resources:
limits:
cpus: "2"
memory: ${WORKER_MEMORY_LIMIT:-2560M}
# The only service holding the Docker socket. See docker-compose.yml for the
# reasoning; the difference here is that it is not on by default (mounting
# the socket on a shared host is a deliberate act).
sandboxd:
logging: *logging
# Exactly the `pydantic-ai-backend` version in backend/uv.lock: the backend's
# client and this service ship together, and a client newer than the service
# calls routes it does not have (#2484). Bump both at once;
# backend/tests/test_sandboxd_compat.py fails when they differ.
image: ghcr.io/vstorm-co/sandboxd:0.2.39
profiles: [sandbox]
# Without an init the server is PID 1, and Python reaps only the children it
# waits on: anything orphaned under it stays a zombie for the container's
# lifetime, and production once showed more than 600. docker-init reaps
# them, as it already does in every sandbox this service starts.
init: true
# The token comes from the same file every other secret in this stack comes
# from, rather than through compose interpolation. Interpolation reads the
# project root, not `backend/.env`, so a token generated where the
# application reads it would have been invisible here - and every other
# variable in this file carries a default precisely so the stack starts with
# no env file at all. The service exits naming the variable when it is
# missing, which `docker compose logs sandboxd` shows.
env_file:
- ./backend/.env
environment:
SANDBOXD_HOST: 0.0.0.0
SANDBOXD_PORT: "8080"
# Mounted at the same path on both sides, which is the only arrangement
# that works: this service creates the directory and then asks the daemon
# to bind-mount it, and the daemon resolves the path on the host. A named
# volume, or any path that exists only in this container, is refused with
# "mounts denied".
#
# The directory has to be writable by uid 10001 - `mkdir -p` then
# `chown 10001:10001`, since `install -o` refuses a uid no account owns
# once, on the host - and it is where a conversation's files live, so it
# belongs on storage somebody backs up.
SANDBOXD_WORKSPACE_ROOT: ${SANDBOX_WORKSPACE_ROOT:-/var/lib/agenticos/sandbox-workspaces}
# Which environments an agent may ask for. **Generated - do not edit here.**
# `make sandbox-runtimes` writes it from
# backend/app/core/catalog/sandbox_runtimes.json, which is where a runtime
# is added or a package changed, and which the connection dialog offers as
# well - so the two cannot disagree about what this deployment ships.
# `backend/tests/test_sandbox_runtime_catalog.py` fails when this line has
# drifted from that file.
#
# Written into a tracked file rather than read from one at start-up because
# `docker compose up` has to work without generating anything first;
# otherwise a deployment silently gets the library's own default allowlist.
#
# Not a form in the product, and that is upstream's decision rather than an
# omission: `PUT /policy` changes ceilings and lifetimes at run time and
# deliberately refuses `runtimes` membership, because naming an image is a
# decision about isolation and this token belongs to an application rather
# than to whoever runs the host. Changing the list is a restart, and
# `prewarm` rebuilds what it names as the service starts rather than inside
# somebody's first request - which is minutes on a cold cache, and the
# reason this deployment ships two runtimes rather than eight.
SANDBOXD_RUNTIMES: '{"workbench":{"description":"Python, Node and LibreOffice - documents, data, charts and code","runtime":{"name":"workbench","base_image":"python:3.12-slim","description":"Python, Node and LibreOffice - documents, data, charts and code","setup_commands":["apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates ripgrep fd-find jq less procps xz-utils poppler-utils libreoffice-writer libreoffice-calc libreoffice-impress unzip zip tzdata fonts-dejavu-core && ln -s /usr/bin/fdfind /usr/local/bin/fd && rm -rf /var/lib/apt/lists/*","arch=\"$$(dpkg --print-architecture)\"; case \"$$arch\" in amd64) node_arch=x64 ;; arm64) node_arch=arm64 ;; *) echo \"no Node build for $$arch\" >&2; exit 1 ;; esac; curl -fsSL \"https://nodejs.org/dist/v24.19.0/node-v24.19.0-linux-$${node_arch}.tar.xz\" | tar -xJ -C /usr/local --strip-components=1 --exclude CHANGELOG.md --exclude README.md --exclude LICENSE && npm install -g tsx @anthropic-ai/claude-code@2.1.288 @openai/codex@0.160.0 && npm cache clean --force","curl -fsSL https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=/usr/local/bin INSTALLER_NO_MODIFY_PATH=1 sh"],"packages":["liteparse","pypdf","python-docx","openpyxl","python-pptx","pillow","pandas","duckdb","matplotlib","httpx","requests","beautifulsoup4","lxml","markdownify","pyyaml","tabulate","reportlab"],"env_vars":{"PYTHONUNBUFFERED":"1","PYTHONDONTWRITEBYTECODE":"1","PYTHONUTF8":"1","MPLBACKEND":"Agg","PIP_DISABLE_PIP_VERSION_CHECK":"1"}},"mem_limit":"2g","network_mode":"bridge"},"desktop":{"description":"A Linux desktop (XFCE and Firefox) for computer use, with Python and a shell","runtime":{"name":"desktop","base_image":"python:3.12-slim","description":"A Linux desktop (XFCE and Firefox) for computer use, with Python and a shell","setup_commands":["apt-get update && apt-get install -y --no-install-recommends xvfb x11-utils xfce4 xfce4-terminal dbus-x11 xdotool scrot firefox-esr fonts-dejavu-core fonts-noto-color-emoji git curl ca-certificates jq procps unzip && rm -rf /var/lib/apt/lists/*"],"packages":[],"env_vars":{"PYTHONUNBUFFERED":"1","PYTHONUTF8":"1","PIP_DISABLE_PIP_VERSION_CHECK":"1"}},"mem_limit":"2g","network_mode":"bridge"}}'
# An escape starts from whoever the container runs as, and the default is
# root. The image is built around this uid - a home directory and a
# virtualenv it owns, without which an agent's `pip install` fails - so it
# only applies to a runtime this deployment builds, which both of ours are.
# It also makes every file an agent writes owned by this uid on the host,
# rather than by root.
#
# **The service's own uid, and it has to be.** Opening a session `chown`s
# the workspace to this user, and a sandboxd running unprivileged can only
# do that for itself - so a different number here fails at the first
# session rather than at start-up.
SANDBOXD_SANDBOX_UID: "10001"
SANDBOXD_PERSIST_CONTAINERS: "true"
# What a session installed inside its container - the build, the wheels,
# `node_modules` - reclaimed a day after it stopped. Without it a persisted
# container is kept for ever and the host fills up with the ones nobody
# reattached to. The workspace is untouched: the files are the work, the
# container is rebuildable.
SANDBOXD_CONTAINER_TTL: "86400"
SANDBOXD_MAX_SESSIONS_PER_TENANT: "10"
SANDBOXD_NETWORK_MODE: none
SANDBOXD_UI_ENABLED: "0"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ${SANDBOX_WORKSPACE_ROOT:-/var/lib/agenticos/sandbox-workspaces}:${SANDBOX_WORKSPACE_ROOT:-/var/lib/agenticos/sandbox-workspaces}
group_add:
- "${DOCKER_GID:-0}"
networks:
# `data` only. `edge` is where the reverse proxy reaches the application,
# and a service whose token can start containers on this host has no
# business on a network anything outside can route to.
- data
restart: unless-stopped
# Interactive browsing uses a separate browser with proxy-only public egress.
browser:
logging: *logging
environment:
- TZ=${BROWSER_TZ:-UTC}
- BROWSER_LANG=${BROWSER_LANG:-en-US}
image: ghcr.io/vstorm-co/agenticos-browser:${AGENTICOS_VERSION:-latest}
profiles: [browser]
healthcheck:
test: ["CMD", "bash", "-ec", "exec 3<>/dev/tcp/127.0.0.1/9222; printf 'GET /json/version HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: close\r\n\r\n' >&3; timeout 5 cat <&3 | grep -q webSocketDebuggerUrl"]
interval: 10s
timeout: 6s
retries: 3
start_period: 30s
depends_on:
browser-egress:
condition: service_healthy
shm_size: 512mb
networks:
- browser
restart: unless-stopped
deploy:
resources:
limits:
cpus: "1"
memory: 1G
browser-egress:
logging: *logging
image: ubuntu/squid:6.6-24.04_edge
profiles: [browser]
healthcheck:
test: ["CMD", "bash", "-ec", "exec 3<>/dev/tcp/127.0.0.1/3128; printf 'GET http://127.0.0.1/ HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: close\r\n\r\n' >&3; timeout 5 cat <&3 | head -n 1 | grep -q '403'"]
interval: 10s
timeout: 6s
retries: 3
start_period: 15s
volumes:
- ./docker/browser-egress/squid.conf:/etc/squid/squid.conf:ro
networks:
- browser
- browser-egress
restart: unless-stopped
deploy:
resources:
limits:
cpus: "0.5"
memory: 256M
# Enabled by scripts/deploy.sh when VISUAL_RENDER_CDP_URL names this service.
# Isolated from the internet, the proxy and data services. The renderer serves
# the drawing and its libraries through CDP; Chromium needs no outbound route.
visual-render:
logging: *logging
image: ghcr.io/vstorm-co/agenticos-browser:${AGENTICOS_VERSION:-latest}
profiles: [visuals]
healthcheck:
test: ["CMD", "bash", "-ec", "exec 3<>/dev/tcp/127.0.0.1/9222; printf 'GET /json/version HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: close\r\n\r\n' >&3; timeout 5 cat <&3 | grep -q webSocketDebuggerUrl"]
interval: 10s
timeout: 6s
retries: 3
start_period: 30s
shm_size: 512mb
networks:
- visuals
restart: unless-stopped
deploy:
resources:
limits:
cpus: "1"
memory: 1G
networks:
browser:
driver: bridge
internal: true
browser-egress:
driver: bridge
visuals:
driver: bridge
internal: true
# Named so `docker-compose-prod.frontend.yml`, a project of its own, can join
# `edge` as an external network. Two stacks on one host set
# AGENTICOS_DATA_NETWORK and AGENTICOS_EDGE_NETWORK apart in backend/.env -
# both files read it - or every `db`, `redis` and `app` alias resolves across
# them.
data:
name: ${AGENTICOS_DATA_NETWORK:-agenticos_data}
driver: bridge
internal: true
edge:
name: ${AGENTICOS_EDGE_NETWORK:-agenticos_edge}
driver: bridge
volumes:
media_data:
postgres_data: