Skip to main content
Requirements: Docker Engine and Docker Compose 2.24.0+ must be installed. For standard mode, 10 GB of Docker memory and 32 GB of free disk space are recommended. A lite mode is available for lower-resource machines (4 GB RAM, 16 GB disk).

​
One-line install

The fastest way to deploy Onyx is with the install script. It handles Docker setup, downloads configuration files, and starts all services: 
curl -fsSL https://onyx.app/install_onyx.sh | bash
The script is interactive. It will:
  • Verify Docker and Docker Compose are installed (and install them on Linux if needed)
  • Check system resources
  • Ask which deployment mode you want (lite or standard)
  • Download docker-compose.yml and env.template from the Onyx GitHub repository
  • Generate a secure USER_AUTH_SECRET
  • Pull Docker images and start all containers
  • Wait for the service to become healthy and print the access URL

​
Install script options

# Standard install
curl -fsSL https://onyx.app/install_onyx.sh | bash

# Minimal deployment (no Vespa, Redis, or model servers)
curl -fsSL https://onyx.app/install_onyx.sh | bash -s -- --lite

# Enable Onyx Craft (AI-powered web app building)
curl -fsSL https://onyx.app/install_onyx.sh | bash -s -- --include-craft

# Non-interactive (CI/automation)
curl -fsSL https://onyx.app/install_onyx.sh | bash -s -- --no-prompt

# Stop running containers
curl -fsSL https://onyx.app/install_onyx.sh | bash -s -- --shutdown

# Remove all containers, volumes, and data
curl -fsSL https://onyx.app/install_onyx.sh | bash -s -- --delete-data

​
Manual Docker Compose setup

If you prefer to manage the deployment yourself, follow these steps.
1

Clone the repository and navigate to the deploy directory

git clone https://github.com/onyx-dot-app/onyx.git
cd onyx/deployment/docker_compose
2

Create your .env file from the template

Copy the environment template and open it for editing:
cp env.template .env
The most important variables to configure:
# env.template — copy to .env before editing

# Onyx image version (edge = latest nightly, or pin to e.g. v0.21.1)
IMAGE_TAG=latest

# Authentication (basic = username/password)
AUTH_TYPE=basic

# Generate this with: openssl rand -hex 32
USER_AUTH_SECRET=""

# Postgres credentials
POSTGRES_USER=postgres
POSTGRES_PASSWORD=password

# File storage backend: "s3" (uses MinIO) or "postgres"
COMPOSE_PROFILES=s3-filestore
FILE_STORE_BACKEND=s3

# Enterprise Edition (requires license)
ENABLE_PAID_ENTERPRISE_EDITION_FEATURES=false
Always set a strong, unique USER_AUTH_SECRET and POSTGRES_PASSWORD before running in production. Run openssl rand -hex 32 to generate a secure secret.
3

Start all services

docker compose up -d
This starts the following services defined in docker-compose.yml:
ServiceImageRole
api_serveronyxdotapp/onyx-backendFastAPI backend, port 8080 (internal)
backgroundonyxdotapp/onyx-backendCelery workers (supervisord)
web_serveronyxdotapp/onyx-web-serverNext.js frontend
nginxnginx:1.25.5-alpineReverse proxy, ports 80 and 3000
relational_dbpostgres:15.2-alpinePostgreSQL database
indexvespaengine/vespa:8.609.39Vespa vector database
opensearchopensearchproject/opensearch:3.4.0Full-text search index
cacheredis:7.4-alpineRedis for task queues and caching
inference_model_serveronyxdotapp/onyx-model-serverEmbedding and inference model server
indexing_model_serveronyxdotapp/onyx-model-serverDedicated model server for indexing
miniominio/minioS3-compatible object storage (file uploads)
code-interpreteronyxdotapp/code-interpreterSandboxed code execution
The api_server runs database migrations automatically on startup (alembic upgrade head) before serving traffic.
4

Wait for services to become healthy

Services have health checks configured. Monitor startup with:
docker compose ps
docker compose logs -f api_server
The api_server health check polls http://localhost:8080/health every 30 seconds. Full startup — including Vespa schema deployment and model loading — typically takes 2–5 minutes.
5

Open Onyx in your browser

Once all containers are healthy, open:
http://localhost
or
http://localhost:3000
Both map to port 80 on the nginx container. Port 3000 is a convenience alias.
In development mode (using docker-compose.dev.yml), the API server is also exposed directly at http://localhost:8080.
6

Create your admin account

On first visit, Onyx will direct you to create an account:
  1. Navigate to http://localhost/auth/signup
  2. Register with your email and a password
  3. The first user to register automatically receives admin privileges
After signing in, the Admin panel is available at http://localhost/admin. From there you can:
  • Configure LLM providers (OpenAI, Anthropic, Ollama, etc.)
  • Add connectors to your knowledge sources
  • Manage users and roles
  • Create custom Agents

​
Deployment modes

A minimal deployment without Vespa, Redis, or model servers. Suitable for low-resource environments or quick evaluation.Lite mode disables: connectors, RAG search, and embedding-based retrieval.Lite mode still supports: LLM chat, tools, user file uploads, Projects, Agent knowledge, code interpreter, and image generation.Minimum resources: 4 GB Docker memory, 16 GB free disk.
# Start with the install script
curl -fsSL https://onyx.app/install_onyx.sh | bash -s -- --lite

# Or with Docker Compose directly
docker compose -f docker-compose.yml -f docker-compose.onyx-lite.yml up -d
Enables AI-powered web app building within Onyx. Requires the craft-latest image tag and sets ENABLE_CRAFT=true. Craft is incompatible with lite mode.
curl -fsSL https://onyx.app/install_onyx.sh | bash -s -- --include-craft

​
Environment variable reference

The .env file (copied from env.template) controls all runtime configuration. Key sections: 
# Auth method: basic, google_oauth, oidc, saml, disabled
AUTH_TYPE=basic

# Required for basic auth — sign tokens for password reset and verification
# Generate: openssl rand -hex 32
USER_AUTH_SECRET=""

# Restrict signups to specific email domains (comma-separated)
# VALID_EMAIL_DOMAINS=yourcompany.com
For the full list of available variables, see the annotated env.template in the repository.

​
Next steps

Docker deployment guide

Production hardening, SSL/TLS setup, and Nginx configuration.

Architecture

Learn how the services, workers, and data flow fit together.

LLM providers

Connect Onyx to OpenAI, Anthropic, Ollama, and others.

Connectors

Index documents from Slack, Confluence, GitHub, and 40+ sources.

Build docs developers (and LLMs) love

Get started for freeTalk to us