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

> Install Onyx dot app easily with this complete self-hosting guide. Run a single command to deploy the entire stack using Docker Compose for automatic setup and health checks.

- Repository: [Onyx/onyx](https://github.com/onyx-dot-app/onyx)
- Tags: how-to-guide
- Published: 2026-03-28

---

**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`](https://github.com/onyx-dot-app/onyx/blob/main/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`](https://github.com/onyx-dot-app/onyx/blob/main/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`](https://github.com/onyx-dot-app/onyx/blob/main/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:

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

```

This command downloads and executes the latest [`install.sh`](https://github.com/onyx-dot-app/onyx/blob/main/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:

```bash
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`](https://github.com/onyx-dot-app/onyx/blob/main/docker-compose.yml) before deployment.


## What the Installer Configures

The [`install.sh`](https://github.com/onyx-dot-app/onyx/blob/main/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`](https://github.com/onyx-dot-app/onyx/blob/main/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:

```bash

# 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`](https://github.com/onyx-dot-app/onyx/blob/main/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`](https://github.com/onyx-dot-app/onyx/blob/main/./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`](https://github.com/onyx-dot-app/onyx/blob/main/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`](https://github.com/onyx-dot-app/onyx/blob/main/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.