This guide uses Docker Compose to run Onyx with all required services.
For Docker installation, see Docker.
| Resource | Minimum | Preferred |
|---|---|---|
| CPU | 4 vCPU | 8+ vCPU |
| RAM | 10 GB | 16+ GB |
| Disk | 32 GB + ~2.5x indexed data | 500 GB |
Note: Vespa does not allow writes once disk usage hits 75%.
The quickest way to deploy Onyx is using the official installation script.
curl -fsSL https://raw.githubusercontent.com/onyx-dot-app/onyx/main/deployment/docker_compose/install.sh > install.sh && chmod +x install.sh && ./install.sh
The script will:
onyx_data directory with all deployment filesOpen your browser and navigate to http://localhost:3000 (or your server’s IP).
For more control over the deployment, create your own Docker Compose file.
mkdir -p /opt/onyx/data/nginx
mkdir -p /opt/onyx/data/certbot/conf
mkdir -p /opt/onyx/data/certbot/www
cd /opt/onyx
Create docker-compose.yml:
services:
api_server:
image: onyxdotapp/onyx-backend:latest
restart: unless-stopped
depends_on:
- relational_db
- index
- cache
environment:
- POSTGRES_HOST=relational_db
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=your-strong-password
- VESPA_HOST=index
- REDIS_HOST=cache
- AUTH_TYPE=basic
- DOMAIN=onyx.example.com
background:
image: onyxdotapp/onyx-backend:latest
restart: unless-stopped
depends_on:
- relational_db
- index
- cache
environment:
- POSTGRES_HOST=relational_db
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=your-strong-password
- VESPA_HOST=index
- REDIS_HOST=cache
web_server:
image: onyxdotapp/onyx-web-server:latest
restart: unless-stopped
depends_on:
- api_server
environment:
- DOMAIN=onyx.example.com
inference_model_server:
image: onyxdotapp/onyx-model-server:latest
restart: unless-stopped
volumes:
- model_cache_huggingface:/root/.cache/huggingface
indexing_model_server:
image: onyxdotapp/onyx-model-server:latest
restart: unless-stopped
volumes:
- indexing_huggingface_model_cache:/root/.cache/huggingface
relational_db:
image: postgres:15.2-alpine
restart: unless-stopped
environment:
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=your-strong-password
- POSTGRES_DB=onyx
volumes:
- db_volume:/var/lib/postgresql/data
index:
image: vespaengine/vespa:8.609.39
restart: unless-stopped
volumes:
- vespa_volume:/opt/vespa/var
cache:
image: redis:7.4-alpine
restart: unless-stopped
volumes:
- redis_data:/data
nginx:
image: nginx:1.25.5-alpine
restart: unless-stopped
ports:
- "3000:80"
depends_on:
- web_server
volumes:
- ./data/nginx:/etc/nginx/conf.d
- ./data/certbot/conf:/etc/letsencrypt
- ./data/certbot/www:/var/www/certbot
volumes:
db_volume:
vespa_volume:
redis_data:
model_cache_huggingface:
indexing_huggingface_model_cache:
docker compose up -d
docker compose ps
All 9 services should show as “running”.
| Service | Image | Purpose |
|---|---|---|
api_server |
onyxdotapp/onyx-backend:latest | Main backend API (FastAPI) |
background |
onyxdotapp/onyx-backend:latest | Background task processor (Celery) |
web_server |
onyxdotapp/onyx-web-server:latest | Frontend (Next.js) |
inference_model_server |
onyxdotapp/onyx-model-server:latest | LLM inference |
indexing_model_server |
onyxdotapp/onyx-model-server:latest | Document embedding generation |
relational_db |
postgres:15.2-alpine | PostgreSQL database |
index |
vespaengine/vespa:8.609.39 | Vespa vector search engine |
cache |
redis:7.4-alpine | Redis cache |
nginx |
nginx:1.25.5-alpine | Reverse proxy |
Prefer automation? See Onyx Ansible Setup.
Any questions?
Feel free to contact us. Find all contact information on our contact page.