Complete Guide to Installing Onyx with Docker

Last update: 26/08/2026

  • Minimum technical requirements of 4 vCPUs and 10 GB of RAM to ensure system stability.
  • Flexible deployment via automated scripts or manual configuration of Docker Compose with 9 services.
  • Importance of managing RAM volumes and limits to maintain persistence and performance.
Install Onyx with Docker

Onyx is an open-source artificial intelligence platform designed to connect language models with documents, applications, and knowledge bases. It can be used as a team chat, enterprise search engine, RAG system, and workspace with agents and tools.

The platform can be contracted as a managed service, but it can also be deployed on your own infrastructure. In the latter case, Docker Compose is one of the most accessible methods, since it allows you to run the interface, the API, the databases, the indexing processes and the rest of the components without manually installing all their dependencies.

In this guide we'll see how to install Onyx with Docker, what the differences are between Lite and Standard modes, how to manage containers, and what steps you should take before publishing the instance on the internet.

What is Onyx and what services can it connect?

onyx ai

Onyx is an enterprise chat and search platform that allows users to query information from documents and applications using artificial intelligence models. It can connect with commercial providers and with models hosted on its own infrastructure.

Its main functions include:

  • Chat with models from different providers.
  • Agents and tools capable of performing actions.
  • Connectors to synchronize knowledge sources.
  • Hybrid search using keywords and vectors.
  • RAG responses based on documents.
  • In-depth research and web search.
  • Integration with tools through actions and MCP.
  • File upload and organization by projects.
  • User administration and authentication systems.

Onyx doesn't necessarily include the generative model you'll be using. After installing it, you'll need to configure a provider such as OpenAI, Anthropic, Gemini, Ollama, LiteLLM, or vLLM.

Onyx Lite or Standard: Which version to install

The current installer allows you to choose between two modes. The decision is important because each one deploys a different architecture and set of functions.

Feature Onyx Lite Onyx Standard
Chat with models Yeah Yeah
Agents and tools Yeah Yeah
File Upload Yeah Yeah
Projects Yeah Yeah
Connectors with external sources No Yeah
RAG Indexing and Search No Yeah
OpenSearch No Yeah
Redis No Yeah
Model servers for indexing No Yeah
Background processes Integrated into the API Independent containers
Recommended use Testing, chat, and small teams RAG, connectors and organizations

Onyx Lite It's the best option for testing the platform, using its chat features, or working on a server with limited resources. It stores files, cache, and sessions in PostgreSQL and doesn't run the full search infrastructure.

Onyx Standard It's designed to use connectors, synchronize documentation, and build an enterprise search system. It requires considerably more memory and storage because it adds OpenSearch, Redis, background processes, object storage, and servers used during indexing.

Requirements for installing Onyx with Docker

Onyx can run on Linux, macOS, or Windows using Docker. For a production server, it's usually preferable to use an up-to-date Linux distribution.

The official requirements depend on the selected mode:

Mode minimum CPU minimum RAM minimum disk space Preferred configuration
Onyx Lite 2 vCPU 2 GB 10 GB 4 vCPUs, 4 GB of RAM and 50 GB
Onyx Standard 4 vCPU 10 GB 32 GB plus the space for indexed data 8 vCPUs or more and 16 GB of RAM or more

In Standard mode, the documentation recommends estimating the approximate size of the indexed documents and adding a generous margin. Actual resource consumption depends on the amount of content, embeddings, concurrency, and OpenSearch configuration.

Before you begin, you will need:

  • An account with permissions to manage the server.
  • Docker Engine and the Docker Compose plugin.
  • Internet connection required to download images and models.
  • Use Git if you're going to do a manual installation.
  • Python and uv if you want to install Onyx CLI directly.
  • A domain and access to its DNS settings if you will be publishing the application.

Check Docker and Compose using:

docker --version
docker compose version

On Linux, you also need to verify that your user can run Docker or use sudo when necessary.

How to install Onyx with the recommended installer

The currently recommended method is to use the guided installer included in Onyx CLIThis checks the computer's resources, allows you to choose between Lite and Standard, downloads the images, starts the containers, and waits until all services are available.

Exclusive content - Click Here  How to open and use Local Security Policy in Windows 11

If you already have it installed uv, run:

uv tool install onyx-cli
onyx-cli deploy install

The assistant will ask you:

  • Which mode do you want to install: Lite or Standard?
  • Which version of Onyx do you want to deploy?
  • What configuration should the environment use?

In a new installation, the deployment files are stored within:

~/.config/onyx

This directory contains the configuration used to manage the stack. Do not confuse it with onyx_dataThis is a folder created by previous versions of the installer. Onyx CLI can detect and adopt these older deployments, but it is no longer the default path for a new installation.

How to install Onyx with the official script

You can also use the command published on the official page:

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

This script is a wrapper for the Onyx CLI installer. Therefore, it produces the same type of guided deployment and should no longer be described as a standalone system.

Before directly running any script downloaded from the Internet, you can save it and review its contents:

curl -fsSLo install_onyx.sh https://onyx.app/install_onyx.sh
less install_onyx.sh
bash install_onyx.sh

The installer checks the environment, installs Docker on compatible Linux systems when necessary, and waits until the containers are healthy.

When it finishes, it will display the address from which you can access it. In a local installation without a domain, it is usually:

http://localhost:3000

If Onyx is running on another server on the network, it replaces localhost by the corresponding IP address. Do not expose the port publicly without configuring authentication and HTTPS.

How to manually install Onyx using Docker Compose

How to manually install Onyx using Docker Compose

Manual installation is useful if you want to directly review Compose files or integrate Onyx into your own deployment pipeline. However, it requires you to manage updates and configuration changes yourself.

First, clone the official repository:

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

To start the Standard deployment with the published images:

docker compose up -d

If you want to compile the images from the source code:

docker compose up -d --build --force-recreate

Compiling from code consumes more time and resources. For a standard installation, it's preferable to use the official images that have already been released.

After starting the containers, Onyx needs to complete its preparation process. Check its status with:

docker compose ps

To track the records:

docker compose logs -f

When all services are ready, open:

http://localhost:3000

How to manually deploy Onyx Lite

Onyx Lite is activated via an additional Compose file that disables unnecessary services:

docker compose \
  -f docker-compose.yml \
  -f docker-compose.onyx-lite.yml \
  up -d

This mode only starts essential services:

  • api_server, which also manages background work.
  • web_server, corresponding to the interface.
  • relational_db, based on PostgreSQL.
  • nginx, which acts as a reverse proxy.

Lite does not include connectors, OpenSearch, or RAG search on synchronized sources. You can upload files and use projects, but it does not replace the Standard deployment when you need to index documentation from external applications.

What services does Onyx Standard use?

The exact architecture may change between versions, so it's not advisable to copy an old Compose file or manually fix images of PostgreSQL, Redis, or other components.

In general terms, Onyx Standard includes:

  • An API server with the main logic.
  • A web interface.
  • PostgreSQL as a relational database.
  • Background processes for connectors and indexing.
  • Redis for caching and sessions.
  • OpenSearch for vector and keyword search.
  • Model servers used during indexing and retrieval.
  • Object storage using MinIO or a compatible backend.
  • Nginx as a reverse proxy.

Always use the files included with the version of Onyx you are installing. Changing database versions individually can cause incompatibilities or failed migrations.

How to complete the initial setup

The first person to register on a new installation becomes the administrator. Therefore, you must complete this step before allowing others to access the server.

After logging in:

  1. Create a strong password for the administrator account.
  2. Enter the administration panel.
  3. Configure a language model provider.
  4. Add the corresponding credentials.
  5. Select a default model.
  6. Conduct a test conversation.
  7. If you are using Standard, create a connector and check the indexing.
Exclusive content - Click Here  How to read and understand web page source code?

Onyx can work with commercial services and its own servers such as Ollama, vLLM, or LiteLLM. Onyx's own hosting doesn't automatically mean the model is also local: if you configure OpenAI, Anthropic, or Gemini, the necessary requests will be sent to that provider.

How to manage Onyx using the CLI

One advantage of the current installer is that it provides specific commands to manage the entire deployment lifecycle:

onyx-cli deploy status
onyx-cli deploy logs
onyx-cli deploy stop
onyx-cli deploy upgrade

Its main functions are:

  • statusCheck the status of the services.
  • logs: displays the deployment logs.
  • stop: stops the containers without uninstalling them.
  • upgrade: updates the managed installation.
  • uninstall: eliminates deployment.

Don't run uninstall To resolve a temporary error. Before any deletion, check which data and volumes will be retained and perform a separate backup.

How to update a manual installation

If you manage Docker Compose files directly, review the release notes for the new version before updating. Then, download the changes from the repository and the corresponding images.

From the deployment directory, the usual process includes:

git pull
docker compose pull
docker compose up -d

Do not automatically deploy a new version in production without testing it. Some updates may include database migrations, changes to environment variables, or modifications to services.

For an installation created using Onyx CLI, preferably use:

onyx-cli deploy upgrade

Persistence and backups

Server used to control Onyx containers

Docker Compose uses volumes to preserve the database, indexes, files, and other data after recreating containers. However, A persistent volume is not the same as a backup..

Before updating or modifying the deployment:

  • Make a copy of the saved settings in ~/.config/onyx.
  • Back up PostgreSQL using a tool compatible with the installed version.
  • It preserves backend data from files or object storage.
  • Store the environment variables and secrets needed to recover the service.
  • Periodically check that the backups can be restored.
  • Store at least one copy off the main server.

Some connected sources can be re-indexed, but the database contains users, settings, conversations, and other data that should not be considered recoverable without a backup.

How to set up a domain and HTTPS

If Onyx will be accessible from the internet, configure a domain whose DNS record points to the server's public IP address. Then set the variable:

WEB_DOMAIN=onyx.ejemplo.com

The repository includes a script to obtain a Let's Encrypt certificate in Docker deployments:

./init-letsencrypt.sh

Before running it, check the environment files and verify that the domain resolves correctly to the server. Ports 80 and 443 must also be available.

Do not directly publish a production instance using an address like http://IP:3000Without HTTPS, credentials and data may be exposed during transit.

How to protect Onyx before publishing it

Authentication via email and password is enabled by default. The first registered account receives administrative privileges.

For an installation used by a team:

  • Register the administrator account immediately.
  • Use a unique and strong password.
  • Restrict access using the firewall.
  • Enable HTTPS before allowing external connections.
  • Configure OAuth, OIDC, or SAML when appropriate.
  • Limit the allowed email domains.
  • Deactivate the open log when it is no longer needed.
  • Protect the keys of model and connector suppliers.
  • Update Onyx, Docker, and the operating system.
  • Review the permissions for MCP agents, actions, and tools.

Current versions allow you to configure some security settings from the administration panel. In enterprise environments, some advanced features such as RBAC, permission synchronization, or additional secret encryption may require the Enterprise edition.

How to monitor storage consumption

In Standard mode, OpenSearch stores the indexes used for searching. If the disk reaches a critical usage threshold—95% by default—OpenSearch may mark the indexes as read-only and stop writing.

Check the available space periodically:

df -h
docker system df

You can also check the size of the volumes and delete Docker images that are no longer in use:

docker image prune

This command removes lingering images, but you should always review what will be removed. Do not use aggressive Docker cleanup commands on a production server without first checking the affected containers, images, and volumes.

Exclusive content - Click Here  How to connect Continue with Ollama to program with local AI

Can Onyx be installed from Plesk?

Server used to manage an Onyx deployment

Plesk allows you to create and manage individual containers, but Onyx is a stack composed of various services, networks, dependencies, and volumes. Rebuilding it container by container from the Plesk interface is error-prone and makes updates difficult.

If your server uses Plesk, it is preferable to:

  1. Access the server using SSH.
  2. Verify that Docker and Docker Compose are available.
  3. Install Onyx using Onyx CLI or the official Compose files.
  4. Use Plesk only for domain, DNS or proxy if you know how to properly integrate both systems.

Before using this combination, check that the server provider allows Docker management and that the ports, networks, and resources do not conflict with other services managed by Plesk.

Common mistakes when installing Onyx with Docker

Common mistakes when installing Onyx with Docker

The containers are not yet available

Check the status and records:

onyx-cli deploy status
onyx-cli deploy logs

For a manual installation, use:

docker compose ps
docker compose logs --tail=200

The most common causes are insufficient memory, lack of space, Docker permissions, or a dependent service that has not finished starting.

Port 3000 is already occupied

Check which process is using the port or modify the mapping in the Compose configuration. Don't just change a container's port without checking the proxy and the variables that depend on it.

Onyx Lite does not show connectors

This is not a mistake. Lite disables connectors, OpenSearch, and RAG search to reduce resource usage. Use Standard if you want to sync external sources.

OpenSearch stops accepting writes

Check the available space. If the disk has reached the critical threshold, first free up or expand storage. Then, review the OpenSearch documentation before removing the read-only lock.

The interface opens, but the chat is unresponsive.

Verify that you have configured a valid provider and model from the admin panel. Also check your balance, API key, and connectivity with the provider.

The server runs out of memory

Double-check that you've selected the correct mode. For a small server, use Lite. Standard requires at least 10 GB of RAM and may need considerably more as the number of indexed documents increases.

An update leaves services incompatible

Review the release notes, migrations, and environment files. If you used the guided installer, manage the upgrade using the Onyx CLI instead of mixing it with manual commands.

Installing Onyx with Docker allows you to deploy an AI environment connected to an organization's documents and applications. For testing chat and agents, Onyx Lite offers a simple, low-power architecture. To index external sources and use RAG search, you must choose the Standard deployment and allocate sufficient resources.

The easiest way to maintain the installation is to use the Onyx CLI, which manages the installation, logs, status, and updates. In production, you should also configure authentication, HTTPS, backups, and storage monitoring.

Alberto Navarro

Alberto Navarro

I'm a technology enthusiast who's turned my geeky interests into a profession. I've spent over 10 years using cutting-edge technology and tinkering with all sorts of programs out of pure curiosity. Now I specialize in computer technology and video games. For more than 5 years, I've been writing for various technology and video game websites, creating articles that aim to provide you with the information you need in language that everyone can understand.

If you have any questions, my knowledge ranges from everything related to the Windows operating system as well as Android for mobile phones. And my commitment is to you, I am always willing to spend a few minutes and help you resolve any questions you may have in this internet world.