2.1.14 Frontend Onyx

Onyx

Handle: onyx
URL: http://localhost:34601

Onyx (formerly Danswer) is an open-source AI platform that combines a Chat UI with powerful RAG capabilities. It's a self-hostable alternative to enterprise knowledge management and AI assistant platforms.

Key Features:

• 40+ connectors: Slack, Google Drive, Notion, Confluence, GitHub, and more
• Chat UI: Full-featured chat interface with conversation history
• RAG: Retrieval-augmented generation with Vespa search engine
• MCP support: Model Context Protocol for tool integration
• Multi-user: Authentication and user management
• OpenAI-compatible: Works with any OpenAI API-compatible backend

Starting

# Pull the images
harbor pull onyx

# Start Onyx with Ollama
harbor up ollama onyx --open

• First startup takes several minutes while Vespa initializes its search indices
• Onyx comes pre-configured to use Harbor's Ollama as the LLM backend
• Monitor Vespa initialization with harbor logs onyx-index

Configuration

Environment Variables

Following options can be set via harbor config:

# Main UI port (nginx reverse proxy)
HARBOR_ONYX_HOST_PORT              34601

# Persistent data directory
HARBOR_ONYX_WORKSPACE              ./services/onyx/data

# Image versions
HARBOR_ONYX_VERSION                latest
HARBOR_ONYX_VESPA_VERSION          8.277.17
HARBOR_ONYX_MINIO_VERSION          latest

# Authentication (disabled, basic, google_oauth, oidc)
# Note: recent Onyx images ignore AUTH_TYPE — password auth is always on
# and the first registered user becomes admin
HARBOR_ONYX_AUTH_TYPE              disabled

# Database configuration
HARBOR_ONYX_DB_USER                postgres
HARBOR_ONYX_DB_PASSWORD            harbor_onyx_db_password
HARBOR_ONYX_DB_NAME                onyx

# MinIO storage
HARBOR_ONYX_MINIO_USER             minioadmin
HARBOR_ONYX_MINIO_PASSWORD         harbor_onyx_minio_password

# Secret used by Onyx to sign auth tokens (password reset,
# email verification, OAuth state). Onyx refuses to start when empty —
# override with your own value (openssl rand -hex 32) for real deployments
HARBOR_ONYX_USER_AUTH_SECRET       harbor_onyx_user_auth_secret_...

# LLM configuration (seeded on first start)
HARBOR_ONYX_DEFAULT_MODEL          qwen3.5:4b
HARBOR_ONYX_FAST_MODEL             qwen3.5:4b

Volumes

Onyx persists data in the following directories:

• services/onyx/data/db/ - PostgreSQL database
• services/onyx/data/vespa/ - Vespa search indices
• services/onyx/data/minio/ - MinIO object storage

An onyx-init sidecar chowns the workspace subdirectories (except db/) to your host user before the main containers start — Vespa runs as a non-root user and fails on a root-owned volume otherwise.

Note: Harbor runs Onyx with Vespa as the document index (ENABLE_OPENSEARCH_INDEXING_FOR_ONYX=false). Recent Onyx images default to an OpenSearch sidecar that Harbor does not ship; without this flag the background worker exits waiting for OpenSearch.

Integration with Harbor

Onyx comes pre-configured to use Harbor's Ollama as the default LLM backend:

# Start both services - ready to chat immediately
harbor up ollama onyx

To change the default model:

# Set a different default model
harbor config set onyx.default_model llama3.1:8b

# Pull the model in Ollama
harbor ollama pull llama3.1:8b

# Restart with fresh database to apply seed config
harbor down onyx && rm -rf services/onyx/data/db && harbor up onyx

Note: Seed configuration is only applied on fresh database initialization. After initial setup, configure models via the Onyx Admin UI under Configuration → LLM.

Troubleshooting

Check Logs

# All services
harbor logs onyx

# Specific service
harbor logs onyx-api
harbor logs onyx-background
harbor logs onyx-index

Database Issues

If migrations fail or database is corrupted:

# Stop services
harbor down onyx

# Remove database (WARNING: destroys all data)
rm -rf services/onyx/data/db

# Restart
harbor up onyx

Memory Issues

Vespa search engine requires significant memory. Recommended minimum 8GB RAM for the host system. If containers crash due to OOM, check available memory.

Links

• Official Documentation
• GitHub Repository
• Connector List