# Docker Compose Setup
Relevant source files
The following files were used as context for generating this wiki page:
* [docker-compose.yml](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/deployment-infrastructure/docker-compose.yml)
* [frontend/.dockerignore](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/deployment-infrastructure/frontend/.dockerignore/README.md)
* [frontend/Dockerfile](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/deployment-infrastructure/frontend/Dockerfile/README.md)
* [orchestrator/Dockerfile](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/deployment-infrastructure/orchestrator/Dockerfile/README.md)
* [orchestrator/api/cloud\_documents.py](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/deployment-infrastructure/orchestrator/api/cloud_documents.py)
* [orchestrator/core/redis/client.py](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/deployment-infrastructure/orchestrator/core/redis/client.py)
* [orchestrator/requirements.txt](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/deployment-infrastructure/orchestrator/requirements.txt)
This page documents the Docker Compose orchestration for Automatos AI, covering service definitions, dependencies, health checks, volumes, networks, and deployment profiles. The setup mirrors a 19-service production topology used in Railway deployments, organized into modular functional groups.
## Purpose and Scope
The Docker Compose configuration orchestrates all services required to run Automatos AI in a containerized environment. It defines:
* **Core Services**: PostgreSQL, Redis, FastAPI backend, Next.js frontend [docker-compose.yml:18-170](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
* **Data Infrastructure**: Dedicated pgvector and Redis instances [docker-compose.yml:22-73](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
* **Worker Services**: `workspace-worker` for isolated task execution and `agent-opt-worker` for prompt optimization [docker-compose.yml:178-217](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
* **Support Services**: Gotenberg for document generation (PRD-63) [docker-compose.yml:109](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
Sources: [docker-compose.yml:1-217](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md), [orchestrator/Dockerfile:1-141](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md), [frontend/Dockerfile:1-115](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md)
***
## Modular Architecture
The system uses a unified `docker-compose.yml` with profiles to manage service groups, allowing for both minimal local development and full-scale worker deployments.
### Service Grouping
| Group | Service Name | Role |
| ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Database** | `postgres` | Primary storage with `pgvector` [docker-compose.yml:22-43](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md) |
| **Cache** | `redis` | Pub/Sub hub and session store [docker-compose.yml:48-73](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md) |
| **API** | `backend` | FastAPI orchestrator [docker-compose.yml:78-138](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md) |
| **UI** | `frontend` | Next.js dashboard [docker-compose.yml:146-170](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md) |
| **Workers** | `workspace-worker` | Isolated agent task execution [docker-compose.yml:178-202](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md) |
| **Optimization** | `agent-opt-worker` | FutureAGI prompt scoring/optimization [docker-compose.yml:204-217](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md) |
**System Data Flow & Networking**
```mermaid
graph TB
subgraph "Public Entrypoints"
LB_API["localhost:8000"]
LB_UI["localhost:3000"]
end
subgraph "Core Group"
API["automatos_backend
(FastAPI)"]
UI["automatos_frontend
(Next.js)"]
end
subgraph "Worker Group (Profile: workers)"
WS_WORKER["workspace_worker
(ARQ/Redis)"]
OPT_WORKER["agent_opt_worker
(FutureAGI)"]
end
subgraph "Data Group"
PG["postgres
(pgvector)"]
RD["redis
(Cache/PubSub)"]
end
LB_API --> API
LB_UI --> UI
API --> PG
API --> RD
WS_WORKER --> RD
WS_WORKER --> PG
OPT_WORKER --> API
```
Sources: [docker-compose.yml:18-217](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md), [orchestrator/core/redis/client.py:141-197](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md)
***
## Core Infrastructure Implementation
### Backend (FastAPI)
The backend service is built using a multi-stage `Dockerfile` targeting `python:3.11-slim` [orchestrator/Dockerfile:13](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md). It includes system dependencies for OCR (`tesseract-ocr`), document processing (`ghostscript`), and PDF generation (`libpango`) [orchestrator/Dockerfile:18-32](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
* **Entrypoint**: Runs `alembic upgrade heads` before starting `uvicorn` to ensure schema synchronization [orchestrator/Dockerfile:140](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
* **Hot Reload**: In development mode, the `./orchestrator` directory is mounted to `/app` [docker-compose.yml:126](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
### Frontend (Next.js)
The frontend uses a multi-stage build that outputs a standalone Node.js server for production efficiency [frontend/Dockerfile:83-114](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
* **Environment Injection**: `NEXT_PUBLIC_API_URL` and Clerk keys are baked into the client bundle during the build stage [frontend/Dockerfile:58-71](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
* **Security**: Runs as a non-root `nextjs` user [frontend/Dockerfile:93-101](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
### Redis Pub/Sub & Task Queue
Redis is the central nervous system for real-time updates. The `RedisClient` class manages connection pools and async pub/sub for WebSocket streaming [orchestrator/core/redis/client.py:14-64](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
* **Workflow Events**: The `publish_workflow_event` method routes execution updates to channels like `workflow:{id}:execution:{id}` [orchestrator/core/redis/client.py:110-119](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
* **Security**: The `redis` service renames dangerous commands like `FLUSHALL` and `FLUSHDB` to prevent accidental data loss [docker-compose.yml:59-61](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
Sources: [orchestrator/Dockerfile:1-141](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md), [frontend/Dockerfile:1-115](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md), [orchestrator/core/redis/client.py:1-197](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md), [docker-compose.yml:48-73](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md)
***
## Code Entity to Service Mapping
This diagram maps specific Python modules and frontend components to their containerized environments.
```mermaid
graph LR
subgraph "Codebase Modules"
main["orchestrator/main.py"]
redis_client["core/redis/client.py"]
cloud_api["api/cloud_documents.py"]
fe_app["frontend/app/"]
end
subgraph "Docker Containers"
svc_api["[backend]
automatos_backend"]
svc_redis["[redis]
automatos_redis"]
svc_ui["[frontend]
automatos_frontend"]
end
main -.->|"FastAPI App"| svc_api
redis_client -.->|"Pub/Sub"| svc_redis
cloud_api -.->|"Boto3/S3"| svc_api
fe_app -.->|"Next.js"| svc_ui
```
Sources: [orchestrator/main.py:1-50](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md), [orchestrator/core/redis/client.py:14-31](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md), [orchestrator/api/cloud\_documents.py:25](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md), [frontend/Dockerfile:114](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md)
***
## Data Persistence & Volumes
The setup uses named volumes to ensure state is preserved across container lifecycles.
| Volume Name | Service | Mount Path | Purpose |
| ---------------- | ------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `postgres_data` | `postgres` | `/var/lib/postgresql/data` | Persistent SQL & Vector data [docker-compose.yml:34](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md) |
| `redis_data` | `redis` | `/data` | Cache and session persistence [docker-compose.yml:65](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md) |
| `workspace_data` | `backend`, `worker` | `/workspaces` | Shared agent filesystems (RO for API, RW for Worker) [docker-compose.yml:130](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md) |
| `backend_logs` | `backend` | `/app/logs` | Centralized application logs [docker-compose.yml:128](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md) |
Sources: [docker-compose.yml:34](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md), [docker-compose.yml:65](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md), [docker-compose.yml:128-130](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md)
***
## Environment Configuration
A `.env` file is mandatory for initialization. Key required variables include:
* **Database**: `POSTGRES_PASSWORD` [docker-compose.yml:29](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
* **Redis**: `REDIS_PASSWORD` [docker-compose.yml:56](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
* **Security**: `API_KEY` for backend authentication [docker-compose.yml:116](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
* **Auth**: `CLERK_SECRET_KEY` and `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` [docker-compose.yml:119-121](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
* **LLM Keys**: Optional at startup; can be configured via the UI [docker-compose.yml:105-106](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
### Launching the Stack
* **Standard Development**: `docker-compose up --build` [docker-compose.yml:6](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
* **With Workers**: `docker-compose --profile workers up --build` [docker-compose.yml:184](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
* **Production Mode**: Build using the `production` target in Dockerfiles to exclude dev dependencies like `pytest`, `black`, and `isort` [orchestrator/Dockerfile:110-114](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md).
Sources: [docker-compose.yml:1-16](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md), [orchestrator/Dockerfile:95-141](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md), [frontend/Dockerfile:85-115](/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md)
***
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.automatos.app/automatos-ai-docs/design-docs/deployment-infrastructure/docker-compose-setup.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.