Docker & Compose Deployments
Relevant source files
The following files were used as context for generating this wiki page:
Onyx utilizes Docker and Docker Compose as the primary mechanism for deploying its modular architecture. This approach containerizes the various services required for a fully functional Gen-AI and Enterprise Search platform, including the web frontend, backend API server, model servers, and several background workers. By using Docker Compose, Onyx ensures consistent environments across development, testing, and production stages.
The deployment infrastructure supports multiple operating systems through specialized installation scripts (install.sh for Linux/macOS and install.ps1 for Windows) and offers different deployment "modes" to accommodate varying resource availability and feature requirements.
Sources: AGENTS.md:14-16, deployment/docker_compose/install.sh:1-40, CONTRIBUTING.md:145-152
Deployment Architecture
The Onyx stack consists of core application services and essential external software dependencies. In a standard deployment, these components work together to provide document indexing, vector search, and LLM-powered chat.
Core Service Components
The following diagram illustrates the high-level relationship between the different containers managed by Docker Compose:
The architecture uses Nginx as a gateway to route traffic to the Next.js frontend and the FastAPI backend. Celery workers handle asynchronous tasks such as document fetching and processing, interacting with Vespa for vector storage and PostgreSQL for relational data.
Sources: CONTRIBUTING.md:76-85, AGENTS.md:21-70, deployment/docker_compose/install.sh:425-435
Deployment Modes
Onyx offers two primary deployment modes to balance functionality and resource usage:
| Mode | Included Services | Excluded Services | Use Case |
|---|---|---|---|
| Standard | All (API, Web, Vespa, Redis, Celery, Model Server) | None | Full search, RAG, and production use. |
| Lite | API, Web, Lite Model Server | Vespa, Redis, Background Workers | LLM chat, tools, file uploads, and Projects only. |
Sources: deployment/docker_compose/install.sh:445-470, deployment/docker_compose/install.ps1:78-85
Installation and Setup
Deployment is orchestrated via platform-specific scripts that automate dependency checks, configuration generation, and container lifecycle management.
System Requirements
The installation scripts verify system resources before proceeding. Standard deployments require significantly more memory due to the inclusion of the Vespa vector database.
- Standard Mode: ~10GB RAM and 32GB Disk space.
- Lite Mode: ~4GB RAM and 16GB Disk space.
Sources: deployment/docker_compose/install.sh:5-6, deployment/docker_compose/install.ps1:28-29
Configuration Management (.env)
Onyx uses a .env file generated from env.template to manage environment variables. Key configuration elements include:
- IMAGE_TAG: Controls the version of Onyx images pulled (e.g.,
edge,latest, orcraft-latest). - AUTH_TYPE: Defines the authentication schema (defaults to
basic). - USER_AUTH_SECRET: A secure hex string generated during installation for token signing.
- ENABLE_CRAFT: A boolean flag to enable the Onyx Craft AI coding agent features.
Sources: deployment/docker_compose/install.sh:535-645, deployment/docker_compose/install.ps1:630-675
Service Lifecycle Management
The install.sh and install.ps1 scripts provide several operational flags to manage the deployment state:
| Command Flag | Action |
|---|---|
--shutdown / -Shutdown | Stops and pauses all running Onyx containers without removing them. |
--delete-data / -DeleteData | Destructive action: removes all containers, volumes, and persistent data. |
--lite / -Lite | Deploys using the docker-compose.onyx-lite.yml overlay. |
--include-craft / -IncludeCraft | Configures the environment to support Onyx Craft artifacts and sandboxes. |
Sources: deployment/docker_compose/install.sh:20-65, deployment/docker_compose/install.ps1:400-435
Startup Sequence
The following sequence diagram describes the automated installation and startup process:
The script performs environmental validation before pulling images to ensure the host can support the selected deployment mode.
Sources: deployment/docker_compose/install.sh:250-800, deployment/docker_compose/install.ps1:750-980
Specialized Deployments
Onyx Craft Deployment
Onyx Craft enables AI-powered web app building. Enabling this feature requires specific configuration:
- Image Tag: Must use
craft-latestor a specificcraft-vX.X.Xtag. - Environment:
ENABLE_CRAFTmust be set totrue. - Sandboxes: The system provisions sandboxes (Self-Hosted via filesystem or Cloud via Kubernetes) to run the generated code.
Sources: web/src/app/craft/README.md:45-75, deployment/docker_compose/install.sh:615-625
Development Deployment
For developers contributing to the project, Onyx provides a docker-compose.dev.yml overlay. This is used to run only the external dependencies (PostgreSQL, OpenSearch/Vespa, Redis, MinIO) while the core Onyx services (API, Web, Model Server) are run locally from source.
# Start external dependencies for local development
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d index relational_db cache minio
Sources: CONTRIBUTING.md:120-130, CONTRIBUTING.md:145-152
Summary
Docker Compose is the backbone of the Onyx deployment strategy, providing a flexible and automated way to manage a complex microservices architecture. By supporting both a resource-heavy "Standard" mode and a minimal "Lite" mode, Onyx can be deployed on a wide range of hardware. Lifecycle management is simplified through comprehensive scripts that handle everything from initial setup and secure secret generation to full data decommissioning.
Sources: deployment/docker_compose/install.sh:1-25, AGENTS.md:14-20