---
title: "Deploy Onyx"
description: "Open-source AI chat and enterprise search over your team's documents"
category: "AI/ML"
url: https://railway.com/deploy/onyx-1
---

# Deploy Onyx

Open-source AI chat and enterprise search over your team's documents

**[Deploy Onyx on Railway](https://railway.com/template/onyx-1)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/onyx-1/manifest.json

- **Creator:** Agaz Self-Host
- **Category:** AI/ML

## Template content

### background https://cdn.jsdelivr.net/gh/onyx-dot-app/onyx@v5.1.3/web/public/logo.png

- **Source:** https://github.com/aalfath/onyx-railway-template

### nginx https://cdn.jsdelivr.net/gh/onyx-dot-app/onyx@v5.1.3/web/public/logo.png

- **Source:** https://github.com/aalfath/onyx-railway-template
- **Health check:** /healthz
- **Public domain:** Yes

### inference-model-server https://cdn.jsdelivr.net/gh/onyx-dot-app/onyx@v5.1.3/web/public/logo.png

- **Source:** https://github.com/aalfath/onyx-railway-template
- **Health check:** /api/health

### opensearch https://cdn.jsdelivr.net/gh/onyx-dot-app/onyx@v5.1.3/web/public/logo.png

- **Source:** https://github.com/aalfath/onyx-railway-template

### Redis https://cdn.sanity.io/images/sy1jschh/production/0ce0bfdcfbdbf69662b1116671f97c2dd788b655-157x157.svg

- **Image:** redis:8.2
- **Start command:** `/bin/sh -c "rm -rf $RAILWAY_VOLUME_MOUNT_PATH/lost+found/ && exec docker-entrypoint.sh redis-server --requirepass $REDIS_PASSWORD --save 60 1 --dir $RAILWAY_VOLUME_MOUNT_PATH"`

### object-store https://cdn.jsdelivr.net/gh/onyx-dot-app/onyx@v5.1.3/web/public/logo.png

- **Source:** https://github.com/aalfath/onyx-railway-template
- **Health check:** /healthz

### indexing-model-server https://cdn.jsdelivr.net/gh/onyx-dot-app/onyx@v5.1.3/web/public/logo.png

- **Source:** https://github.com/aalfath/onyx-railway-template
- **Health check:** /api/health

### web-server https://cdn.jsdelivr.net/gh/onyx-dot-app/onyx@v5.1.3/web/public/logo.png

- **Source:** https://github.com/aalfath/onyx-railway-template
- **Health check:** /

### api-server https://cdn.jsdelivr.net/gh/onyx-dot-app/onyx@v5.1.3/web/public/logo.png

- **Source:** https://github.com/aalfath/onyx-railway-template
- **Health check:** /health

### Postgres https://devicons.railway.app/i/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

### mcp-server https://cdn.jsdelivr.net/gh/onyx-dot-app/onyx@v5.1.3/web/public/logo.png

- **Source:** https://github.com/aalfath/onyx-railway-template
- **Health check:** /health

## Documentation

# Deploy and Host Onyx on Railway

Onyx is an open-source AI platform for teams: a chat assistant and enterprise search that answers from your own documents. It connects to 40+ sources such as Slack, Google Drive, Confluence, GitHub and Notion, indexes them with permissions, and works with any LLM you bring: OpenAI, Anthropic, Gemini, Azure or a self-hosted model.

## About Hosting Onyx

Onyx is not a single container. Its upstream Docker Compose stack runs a FastAPI API server, a Next.js web app, Celery background workers, an MCP server, two model servers for embeddings, OpenSearch for the document index, an S3-compatible object store, PostgreSQL, Redis and an nginx router. This template deploys Onyx v5.1.3 as eleven Railway services wired over the private network. Secrets are generated at deploy time, every stateful service has its own volume and nginx is the only public service. The first deploy takes about five minutes while the images build, the database migrates and the embedding model loads.

## Common Use Cases

* A private ChatGPT-style assistant for your team, using your own LLM API keys
* Search and question answering across company wikis, drives, tickets and chat history
* Custom agents and an MCP endpoint that give AI tools grounded access to internal knowledge

## Dependencies for Onyx Hosting

* An API key for at least one LLM provider (OpenAI, Anthropic, Google, Azure or an OpenAI-compatible server), added in the admin panel after the first login
* Enough memory for the stack: OpenSearch takes a 2 GB heap and each model server about 1.5 GB

### Deployment Dependencies

* [Onyx on GitHub](https://github.com/onyx-dot-app/onyx) and its [v5.1.3 release](https://github.com/onyx-dot-app/onyx/releases/tag/v5.1.3)
* [Onyx documentation](https://docs.onyx.app) and [Docker Compose deployment guide](https://docs.onyx.app/deployment/local/docker)
* [OpenSearch](https://opensearch.org/), [SeaweedFS](https://github.com/seaweedfs/seaweedfs), [nginx](https://nginx.org/)
* This template's source: [aalfath/onyx-railway-template](https://github.com/aalfath/onyx-railway-template)

### Implementation Details

Services (all but Postgres and Redis build from this template's GitHub repo, each pinned to an official image by version and digest):

| Service | What it does | Volume |
|---|---|---|
| `nginx` | Public entry point: `/api` to the API server, `/mcp` to the MCP server, everything else to the web app | none |
| `web-server` | Onyx web app (Next.js) | none |
| `api-server` | Onyx API; runs the database migrations before it starts | none |
| `background` | Celery workers and scheduler: connectors, indexing, pruning, file processing | none |
| `mcp-server` | MCP endpoint at `https://YOUR-DOMAIN/mcp` for Claude, Cursor and other MCP clients | none |
| `inference-model-server` | Embeds search queries | model cache |
| `indexing-model-server` | Embeds documents while they are indexed | model cache |
| `opensearch` | Document index (keyword and vector search), OpenSearch 3.6 | index data |
| `object-store` | SeaweedFS S3 store for uploaded files | file data |
| `Postgres` | Railway PostgreSQL: users, settings, chat history, connector state | database |
| `Redis` | Railway Redis: Celery queue and cache | Railway default |

The services start in dependency order on their own: the API server waits for Postgres, Redis, OpenSearch and both model servers, runs `alembic upgrade head`, and the workers wait for the API's health check.

**After deploy**

1. Open the `nginx` service's public URL and create your account. **The first account becomes the admin**, so do this right away.
2. In the admin panel, add an LLM provider and its API key.
3. Lock sign-ups: turn on invite-only (Admin panel, Users) or set `VALID_EMAIL_DOMAINS` (for example `example.com`) on `api-server`, otherwise anyone with the URL can register.
4. Add connectors, or upload files in a chat, and start asking questions.

**Optional settings** (add them as variables on `api-server` and `background`): SMTP for invites and password resets (`SMTP_SERVER`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, `EMAIL_FROM`), `VALID_EMAIL_DOMAINS`, and `REQUIRE_EMAIL_VERIFICATION=true`. For a custom domain, add it to `nginx` and change `WEB_DOMAIN` on `api-server`, `background`, `mcp-server` and `web-server` to `https://YOUR-DOMAIN`. Single sign-on (Google, OIDC, SAML) is set up in the admin panel.

**Left out on purpose:** upstream's code-interpreter service (the Python tool) mounts the Docker socket, which Railway does not offer, so it is not deployed. The legacy MinIO store and its copy job only matter for upgrades from Onyx v4 installs.

**Updates:** this template builds from [aalfath/onyx-railway-template](https://github.com/aalfath/onyx-railway-template). When we move it to a new Onyx release, Railway shows an "update available" notice in your project, and you choose when to apply it. Read [CHANGELOG.md](https://github.com/aalfath/onyx-railway-template/blob/main/CHANGELOG.md) first. Database migrations run on their own when the API server starts.

## Why Deploy Onyx on Railway?


Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Onyx on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.



## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [Weaviate](https://railway.com/deploy/weaviate-1) — Vector database with hybrid search and an API key-protected API
- [Möbius Personal AI OS](https://railway.com/deploy/mobius-v01-personal-ai-os) — Self-hosted AI agent that builds and runs apps for you, with memory.

Open this page in a browser: https://railway.com/deploy/onyx-1
