How to Install Onyx dot app Onyx: Complete Self-Hosting Guide

Run curl -fsSL https://onyx.app/install_onyx.sh | bash to deploy the entire Onyx stack via Docker Compose with automatic environment configuration and health checks.

Onyx is a self-hostable, full-stack AI platform that provides chat, RAG, agents, web search, and connectors in a single deployable unit. The recommended installation method uses the guided Docker Compose installer located at deployment/docker_compose/install.sh in the onyx-dot-app/onyx repository. This guide covers the complete installation process from prerequisites to post-install verification, including architecture details and advanced deployment options.

Prerequisites

Before running the installer, ensure your system meets the baseline requirements for container orchestration and secure secret generation.

Required Software

• Docker Engine (≥ 20.10): Runs all containerized services. Verify with docker --version. The install.sh script can auto-install Docker on Linux (lines 63‑84) if missing.
• Docker Compose (plugin or binary ≥ 2.24): Parses the orchestration files. Check with docker compose version.
• curl or wget: Downloads the installer and configuration templates.
• openssl: Generates the USER_AUTH_SECRET for authentication (lines 112‑116 of install.sh).

Optional Port Detection Tools

The installer probes for available TCP ports using nc, lsof, or curl (lines 78‑86). If none are present, the script warns you but continues. On macOS, the script automatically starts Docker Desktop if the daemon is not running (lines 89‑107).

Installation Methods

You can deploy Onyx using the automated one-liner or clone the repository for manual control.

One-Command Quick Start

The fastest way to install Onyx dot app Onyx is the hosted install script:

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

This command downloads and executes the latest install.sh, which handles Docker detection, environment file creation, and service startup.

Manual Installation from Source

For custom configurations or specific versions, clone the repository and run the installer directly:

git clone https://github.com/onyx-dot-app/onyx.git
cd onyx/main/deployment/docker_compose
chmod +x install.sh

# Standard interactive installation

./install.sh

# Or with specific flags

./install.sh --include-craft

This approach lets you modify env.template or docker-compose.yml before deployment.

What the Installer Configures

The install.sh script performs several automated configuration steps defined in lines 11‑158.

1. Environment Detection: Validates Docker and Compose availability (lines 11‑30).
2. File Download: Pulls docker-compose.yml, optional lite overlays, and env.template from the main branch or a pinned IMAGE_TAG (lines 115‑134).
3. Environment Generation: Creates a .env file containing:
   • IMAGE_TAG (e.g., edge or specific release)
   • AUTH_TYPE=basic (default)
   • Secure USER_AUTH_SECRET generated via OpenSSL
4. Port Selection: Detects an open TCP port (defaults to 3000) for the web UI using nc, curl, or lsof (lines 89‑110).
5. Container Deployment: Executes docker compose pull and docker compose up -d, forcing re-pull for floating tags (lines 141‑158).
6. Health Verification: Calls the check_onyx_health function (lines 216‑258) to poll the HTTP endpoint for up to 10 minutes until the stack is ready.

Post-Install Verification

After the installer completes, verify the deployment using these commands:

# Navigate to the deployment directory

cd onyx_data/deployment

# Check container status (should show all services as "running")

docker compose ps

# Follow logs for debugging

docker compose logs -f

# Test the HTTP endpoint

curl -s -o /dev/null -w "%{http_code}" http://localhost:3000

# Expected output: 200

If any container enters a restart loop, the installer prints diagnostics and exits with an error code (lines 181‑196). Check backend/log/ for detailed error messages.

First Access: Open http://localhost:<PORT> (usually 3000) in your browser. The first user created via /auth/signup becomes the administrator (lines 84‑87 of the installer script).

Advanced Deployment Options

The install.sh script supports several flags for specialized deployments:

Option	Effect	Constraints
--lite	Excludes Vespa, Redis, model servers, and Celery workers. Suitable for machines with ≥ 4 GB RAM and 16 GB disk.	Cannot use with --include-craft.
--include-craft	Enables the AI-powered web-app builder (ENABLE_CRAFT=true).	Requires full deployment; incompatible with --lite (validation at lines 77‑81).
--no-prompt	Runs non-interactively using default values. Ideal for CI/CD pipelines.	Requires pre-configured .env or acceptance of defaults.
--dry-run	Displays the deployment plan without executing changes (lines 98‑108).	Safe for testing configuration logic.
--shutdown	Gracefully stops all containers without deleting data.	Useful for maintenance windows.
--delete-data	Completely removes the deployment and associated volumes.	Destructive operation; requires confirmation.

Upgrade Path: To update Onyx, rerun ./install.sh, select "update", and provide a new IMAGE_TAG. The script updates the .env file and pulls the new images (lines 54‑84).

Summary

• Use the one-liner curl -fsSL https://onyx.app/install_onyx.sh | bash for the fastest installation of Onyx dot app Onyx.
• Requirements: Docker ≥ 20.10, Docker Compose ≥ 2.24, and openssl for secret generation.
• Architecture: The deployment includes a Next.js frontend, FastAPI backend, Celery background workers, PostgreSQL, Redis, and Vespa vector search.
• Lite mode (--lite) reduces resource usage by omitting search indexing and background workers.
• Health checks: The check_onyx_health function validates the deployment for up to 10 minutes before confirming success.
• First admin: The initial user signing up at /auth/signup receives administrative privileges.

Frequently Asked Questions

What is the difference between standard and Lite mode in Onyx?

Standard mode deploys the full stack including Vespa for vector search, Redis for caching, PostgreSQL for metadata, and multiple Celery worker queues for document processing. Lite mode (--lite) removes Vespa, Redis, model servers, and all background workers, leaving only chat, tools, file upload, and Projects functional. This reduces RAM requirements to approximately 4 GB and disk usage to 16 GB, making it suitable for local development or resource-constrained environments.

Can I use the Craft feature with Lite mode?

No. According to the source code validation at lines 77‑81 of install.sh, the --include-craft flag is incompatible with --lite. Craft requires the full infrastructure including background workers and the complete API server stack. Attempting to enable both flags results in an error message and script termination.

How does the installer handle Docker if it is not installed?

On Linux systems, the install.sh script attempts to auto-install Docker Engine and Docker Compose if they are missing (lines 63‑84). On macOS, the script checks for Docker Desktop and attempts to start it if the daemon is not running (lines 89‑107). If auto-installation fails or you are on an unsupported platform, the script exits with instructions to manually install Docker before retrying.

What happens if the health check fails during installation?

The installer runs the check_onyx_health function (lines 216‑258) which polls http://localhost:<PORT> for up to 10 minutes. If the endpoint does not return HTTP 200 within this window, the script prints container logs for the API server and web frontend, then exits with an error code. You can manually inspect logs using docker compose logs in the onyx_data/deployment directory to diagnose startup failures, port conflicts, or missing environment variables.

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