How to Set Up a Development Environment for Onyx: Complete Local Developer Guide

To set up a development environment for Onyx, run Postgres, Vespa, Redis, and MinIO in Docker, install Python 3.11 and Node 22 dependencies, then start the model server on port 9000, background Celery workers, the FastAPI backend on port 8080, and the Next.js frontend on port 3000.

Onyx is a full-stack Gen-AI and enterprise search platform maintained by onyx-dot-app/onyx that consists of a Python FastAPI backend, a Next.js frontend, a standalone model server, and background job workers. Developing locally requires orchestrating four distinct runtime processes alongside external data stores. This guide follows the exact implementation details found in contributing_guides/dev_setup.md and AGENTS.md to ensure your local environment matches production architecture.

Prerequisites and Architecture

Before installing dependencies, ensure your system meets the base requirements. Onyx requires Python 3.11 for the backend and Node 22.20.0 for the frontend. You will also need Docker to host external services and uv for Python package management.

The development architecture involves four concurrent processes you must start manually:

1. Web UI – Next.js development server on http://localhost:3000
2. Backend API – FastAPI application in backend/onyx/main.py on port 8080
3. Model Server – Embedding and LLM inference service in backend/model_server/main.py on port 9000
4. Background Workers – Celery workers managed by backend/scripts/dev_run_background_jobs.py that handle connector syncing, indexing, and document pruning

These services depend on Docker containers running Postgres, Vespa, Redis, and MinIO.

Step 1 — Launch External Services with Docker

Start the required infrastructure containers before running any application code. According to deployment/docker_compose/docker-compose.yml and docker-compose.dev.yml, you need the index (Vespa), relational_db (Postgres), cache (Redis), and minio services.

Run the following command from the repository root:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d index relational_db cache minio

This command detaches the containers to run in the background, providing the data persistence and vector search capabilities required by the Onyx backend.

Step 2 — Configure the Python Backend Environment

Onyx uses uv for fast Python dependency management. Create a virtual environment pinned to Python 3.11 and install all backend packages including development extras.

Create and activate the virtual environment:

uv venv .venv --python 3.11
source .venv/bin/activate

On Windows PowerShell, use .venv\Scripts\Activate.ps1 instead.

Install dependencies declared in backend/pyproject.toml:

uv sync --all-extras

Install Playwright binaries required for the Web connector:

uv run playwright install

Initialize the database schema using Alembic migrations stored in backend/alembic/versions/:

cd backend
alembic upgrade head

Step 3 — Configure the Node.js Frontend

The frontend requires Node 22.20.0 as specified in web/package.json. Use nvm to install and switch to the correct version:

nvm install 22 && nvm use 22
node -v

Install frontend dependencies:

cd web
npm i

Step 4 — Start the Four Development Processes

With dependencies installed and Docker services running, start each Onyx component in a separate terminal window. The startup order matters: begin with the model server, then background workers, then the backend API, and finally the frontend.

Terminal 1 — Model Server:

cd backend
uvicorn model_server.main:app --reload --port 9000

Terminal 2 — Background Workers:

cd backend
python ./scripts/dev_run_background_jobs.py

Terminal 3 — Backend API:

cd backend
AUTH_TYPE=basic uvicorn onyx.main:app --reload --port 8080

Setting AUTH_TYPE=basic enables simple authentication for local development as implemented in backend/onyx/main.py.

Terminal 4 — Frontend:

cd web
npm run dev

Once all four processes display ready states, open http://localhost:3000 to access the Onyx onboarding wizard.

Step 5 — Configure Code Quality Tools

Enable pre-commit hooks to enforce formatting and linting rules defined in .pre-commit-config.yaml:

uv run pre-commit install

This ensures your contributions match the repository's style guidelines before submission.

Summary

• Docker services – Run Postgres, Vespa, Redis, and MinIO via docker-compose.yml and docker-compose.dev.yml before starting application code
• Python setup – Use uv with Python 3.11, run uv sync --all-extras, install Playwright, and execute alembic upgrade head from the backend/ directory
• Node setup – Install Node 22.20.0 via nvm and run npm i in the web/ directory
• Runtime processes – Start four separate services: model server on port 9000, background workers via dev_run_background_jobs.py, backend API on port 8080 with AUTH_TYPE=basic, and frontend on port 3000
• Key files – Reference contributing_guides/dev_setup.md, backend/pyproject.toml, backend/onyx/main.py, and AGENTS.md for architecture details

Frequently Asked Questions

What are the background workers used for in Onyx development?

The background workers are Celery processes started via backend/scripts/dev_run_background_jobs.py that handle asynchronous tasks including document indexing, connector synchronization, permission pruning, and embedding generation. Without these running, document uploads and connector crawls will queue indefinitely without processing.

Can I use a different Python version than 3.11?

No. The backend/pyproject.toml explicitly requires Python 3.11, and dependencies are locked to this version. Using Python 3.12 or 3.10 will cause resolution failures during uv sync or runtime incompatibilities with the FastAPI application defined in backend/onyx/main.py.

Is Docker mandatory for local development?

Yes. The application requires Postgres for relational data, Vespa for vector search, Redis for caching, and MinIO for object storage. These services are defined in deployment/docker_compose/docker-compose.yml and are not optional for a functional development environment, as the backend code in onyx/main.py expects these connections on startup.

How do I debug the backend with VS Code?

The repository includes a pre-configured VS Code launch configuration in .vscode/launch.json that spawns the model server, background workers, and backend API with attached debuggers. Alternatively, run uvicorn onyx.main:app --reload with the VS Code Python debugger attached to port 8080, ensuring AUTH_TYPE=basic is set in your environment variables for authentication bypass.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}