docker-compose-dev.yml

Rama main · réplica de lectura del repositorio original.

# The dev server. `make dev-server`.
#
#   docker compose --env-file backend/.env -f docker-compose-dev.yml pull
#   docker compose --env-file backend/.env -f docker-compose-dev.yml up -d
#
# A deployed environment, not a laptop: the images are pulled from GHCR rather
# than built - `edge` by default, which is whatever `main` last published, or
# the `AGENTICOS_VERSION` in `backend/.env` - the source is not bind-mounted,
# uvicorn does not reload, and Postgres and Redis are not published to the
# host. It differs from production in the things a shared
# testing environment wants — verbose logging, a single worker, no resource
# ceilings, and `ENVIRONMENT=dev` so an agent's traces and alerts are separable
# from real ones.
#
# Put a reverse proxy in front of port 8000; `nginx/nginx.conf` is the template.
# The frontend is `docker-compose-dev.frontend.yml`.

services:
  # Runs the migrations and exits; `app` and `worker` wait for it to have
  # completed, so `make dev-server` is a `pull` and an `up`.
  migrate:
    image: ghcr.io/vstorm-co/agenticos-backend:${AGENTICOS_VERSION:-edge}
    command: agenticos db upgrade
    env_file:
      - ./backend/.env
    environment:
      - ENVIRONMENT=dev
      - POSTGRES_HOST=db
      - REDIS_HOST=redis
    networks:
      - backend
    depends_on:
      db:
        condition: service_healthy
    restart: "no"

  app:
    image: ghcr.io/vstorm-co/agenticos-backend:${AGENTICOS_VERSION:-edge}
    # 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:
      # Verbose on purpose: this is where a failure is meant to be diagnosed.
      - DEBUG=true
      - ENVIRONMENT=dev
      - POSTGRES_HOST=db
      - REDIS_HOST=redis
      # The browser profile's egress proxy, on by default so starting the browser
      # starts the pinning path too. Set BROWSER_EGRESS_PROXY= (empty) in the root
      # .env only for a browser outside compose that cannot reach it.
      - BROWSER_EGRESS_PROXY=${BROWSER_EGRESS_PROXY-http://browser-egress:3128}
      # 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 is broken with websockets >=14 (handshake → HTTP 500). Required for
    # the chat WS. No --reload: there is no mounted source to watch.
    #
    # One process, and PID 1 is the server itself - so there is no supervisor
    # here and deliberately none added (#358). A worker that *dies* takes the
    # container with it and `restart: unless-stopped` below acts; a worker whose
    # event loop stops turning used to keep the container `Up` and serving
    # nothing, and now ends its own process from `app/core/watchdog.py` after
    # fifteen silent seconds, which lands it in the first case. `--workers 2` would have
    # bought uvicorn's own supervisor instead, at a second interpreter on a
    # small box, and only for a *stopped* PID 1 - which the kernel makes
    # unreachable anyway, dropping `SIGSTOP` sent to a namespace's init from
    # inside it. `EVENT_LOOP_WEDGED_AFTER` in `backend/.env` changes the
    # threshold, `0` switches it off.
    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --ws websockets-sansio
    ports:
      - "8000:8000"
    networks:
      backend:
        # `nginx/nginx.conf` proxies to `backend:8000`. The alias makes that
        # template resolve without the operator having to rename anything.
        aliases:
          - backend
      # Where `artifact-render` is, when its profile is up. Empty otherwise.
      render: {}
      browser: {}
    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.
    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

  db:
    # 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` — so every document upload 500s
    # before a row is committed.
    image: pgvector/pgvector:pg16
    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: reachable only from this network.
    networks:
      - backend
    # See docker-compose.yml for why `service_healthy` needs a grace to wait
    # through, and what a missing one costs a redeploy (#1831).
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    restart: unless-stopped

  redis:
    image: valkey/valkey:8-alpine
    # `--save ''` and no volume: everything here is rebuildable and carries a
    # TTL, and a persisted snapshot is what a Valkey upgrade refuses to read
    # (#1830).
    command: >-
      valkey-server --requirepass ${REDIS_PASSWORD:?REDIS_PASSWORD is required}
      --save ''
    networks:
      - backend
    healthcheck:
      test: ["CMD", "valkey-cli", "-a", "${REDIS_PASSWORD}", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped

  # The background worker: ingestion, syncs, fired triggers, cleanups and the
  # scheduled sweeps. Without it documents upload and then never become
  # searchable. See docker-compose.yml.
  worker:
    image: ghcr.io/vstorm-co/agenticos-backend:${AGENTICOS_VERSION:-edge}
    volumes:
      - media_data:/app/media
    command: python -m app.worker
    env_file:
      - ./backend/.env
    environment:
      - DEBUG=false
      - ENVIRONMENT=dev
      - POSTGRES_HOST=db
      - REDIS_HOST=redis
      # The browser profile's egress proxy, on by default so starting the browser
      # starts the pinning path too. Set BROWSER_EGRESS_PROXY= (empty) in the root
      # .env only for a browser outside compose that cannot reach it.
      - BROWSER_EGRESS_PROXY=${BROWSER_EGRESS_PROXY-http://browser-egress:3128}
    networks:
      - backend
      - render
      - browser
    depends_on:
      migrate:
        condition: service_completed_successfully
      redis:
        condition: service_healthy
    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
    deploy:
      resources:
        limits:
          memory: ${WORKER_MEMORY_LIMIT:-4g}
    restart: unless-stopped

  # The only service holding the Docker socket. See docker-compose.yml for the
  # reasoning; the differences here are that it is not on by default (mounting
  # the socket on a shared host is a deliberate act) and that the image tag is
  # pinned rather than tracking a minor.
  # The browser the web browser capability drives (#2127). Behind a profile,
  # because only an agent bound to `browser_use` needs one: `docker compose
  # --profile browser up -d browser`. Never published - the API reaches it on the
  # compose network as `http://browser:9222`, which `BROWSER_CDP_ALLOWED_HOSTS`
  # has to name. A full Chromium with a window under a virtual display
  # (`docker/browser`), so a site sees a desktop browser rather than a headless
  # shell it refuses on sight (#2130). `TZ` and `BROWSER_LANG` are where and in
  # which language it says it is.
  browser:
    image: ghcr.io/vstorm-co/agenticos-browser:${AGENTICOS_VERSION:-edge}
    profiles: [browser]
    environment:
      - TZ=${BROWSER_TZ:-UTC}
      - BROWSER_LANG=${BROWSER_LANG:-en-US}
    # Room for pages that use shared memory; the default 64 MB crashes tabs.
    shm_size: 1gb
    networks:
      - browser
    restart: unless-stopped

  # The browser's egress proxy (`docker/browser-egress`): the app and the worker
  # default BROWSER_EGRESS_PROXY to it, so every browse without an organization
  # proxy goes out through it. It resolves each host itself, refuses
  # private, loopback, link-local and metadata addresses, and connects to the
  # address it checked - so neither a redirect nor a name that rebinds between
  # two lookups takes a page inside the deployment's network.
  browser-egress:
    image: ubuntu/squid:6.6-24.04_edge
    profiles: [browser]
    volumes:
      - ./docker/browser-egress/squid.conf:/etc/squid/squid.conf:ro
    networks:
      - browser
    restart: unless-stopped

  sandboxd:
    # 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]
    # 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:
      - backend
    restart: unless-stopped

  # An identity provider to test single sign-on against, off by default.
  #
  # `make dev` does not need one and nobody developing a chat surface should pay
  # for a JVM starting, so it is behind a profile: `docker compose -f
  # docker-compose-dev.yml --profile sso up -d keycloak`. The realm is imported
  # rather than clicked together, so the client, its secret and the two users the
  # SSO spec signs in as are the same on every machine - including the one whose
  # address the provider has *not* verified, which is the refusal worth a test.
  #
  # **The hostname is `keycloak`, not `localhost`, and that is the whole trick.**
  # An issuer is one string that both the browser and the API have to resolve to
  # the same provider: `localhost:8081` is Keycloak from the host and the API
  # container's own loopback from inside the stack, so a containerized backend
  # fails discovery before the browser is ever redirected. Publishing on the same
  # port the container listens on and adding one line to the host's `/etc/hosts`
  # makes one URL work from both sides:
  #
  #   echo "127.0.0.1 keycloak" | sudo tee -a /etc/hosts
  #
  # Then, in `backend/.env`:
  #   OIDC_ISSUER=http://keycloak:8081/realms/agenticos
  #   OIDC_CLIENT_ID=agenticos
  #   OIDC_CLIENT_SECRET=e2e-client-secret
  #   OIDC_REDIRECT_URI=http://localhost:8000/api/v1/oauth/oidc/callback
  # and the frontend with OAUTH_PROVIDERS=google,oidc. Then `E2E_OIDC=1 make
  # test-e2e`; without that variable the SSO spec skips itself.
  artifact-render:
    # The browser `preview_artifact` draws a page in. Opt-in, and the same service
    # as in docker-compose.yml, which says why each line is there: set
    # ARTIFACT_RENDER_CDP_URL=http://artifact-render:9222 (never on
    # BROWSER_CDP_ALLOWED_HOSTS) and pull an image built with the `browser`
    # extra. `render` has no route off the host.
    image: chromedp/headless-shell:155.0.8059.40
    profiles: [artifact-render]
    command:
      - --disable-dev-shm-usage
      - --no-first-run
      - --disable-background-networking
      - --disable-component-update
      - --disable-default-apps
      - --disable-sync
      - --mute-audio
      - --hide-scrollbars
    read_only: true
    tmpfs:
      - /tmp
    cap_drop: [ALL]
    security_opt:
      - no-new-privileges:true
    mem_limit: 1g
    cpus: 1.0
    pids_limit: 256
    networks:
      - render
    restart: unless-stopped

  keycloak:
    image: quay.io/keycloak/keycloak:26.0
    profiles: [sso]
    command: start-dev --import-realm --http-port=8081
    environment:
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
      # The issuer the API discovers is the address the browser is sent to as
      # well, so it has to be a name both can resolve - see above.
      KC_HOSTNAME: http://keycloak:8081
      KC_HOSTNAME_STRICT: "false"
      KC_HTTP_ENABLED: "true"
    ports:
      # The same port on both sides, so one URL is correct from the host and
      # from the compose network.
      - "8081:8081"
    volumes:
      - ./e2e-fixtures/keycloak:/opt/keycloak/data/import:ro
    networks:
      - backend

networks:
  backend:
    # Named so `docker-compose-dev.frontend.yml`, a project of its own, can join
    # it as an external network. Set AGENTICOS_NETWORK in backend/.env when two
    # stacks share a host - both files read it, so they still meet.
    name: ${AGENTICOS_NETWORK:-agenticos_backend}
    driver: bridge
  render:
    # The page renderer's network: the API, the runner and the browser, no way out.
    internal: true
  browser:
    # The browser's own network, which only the API and the worker share with it
    # to reach `browser:9222`. A page it is sent to - or redirected to - cannot
    # reach the database, Redis or MinIO, because nothing else is on it.
    driver: bridge

volumes:
  media_data:
  postgres_data: