Deploy Onyx

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

Deploy Onyx

Just deployed

inference-model-server

aalfath/onyx-railway-template

Just deployed

/app/.cache/huggingface

Just deployed

/usr/share/opensearch/data

Just deployed

/data

Just deployed

/data

indexing-model-server

aalfath/onyx-railway-template

Just deployed

/app/.cache/huggingface

Just deployed

Just deployed

/var/lib/postgresql/data

Just deployed

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

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):

ServiceWhat it doesVolume
nginxPublic entry point: /api to the API server, /mcp to the MCP server, everything else to the web appnone
web-serverOnyx web app (Next.js)none
api-serverOnyx API; runs the database migrations before it startsnone
backgroundCelery workers and scheduler: connectors, indexing, pruning, file processingnone
mcp-serverMCP endpoint at https://YOUR-DOMAIN/mcp for Claude, Cursor and other MCP clientsnone
inference-model-serverEmbeds search queriesmodel cache
indexing-model-serverEmbeds documents while they are indexedmodel cache
opensearchDocument index (keyword and vector search), OpenSearch 3.6index data
object-storeSeaweedFS S3 store for uploaded filesfile data
PostgresRailway PostgreSQL: users, settings, chat history, connector statedatabase
RedisRailway Redis: Celery queue and cacheRailway 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. 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 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.


Template Content

More templates in this category

View Template
Chat Chat
Chat Chat, your own unified chat and search to AI platform.

okisdev
117
View Template
Weaviate
Vector database with hybrid search and an API key-protected API

GitHub Locker
1
View Template
Möbius Personal AI OS
Self-hosted AI agent that builds and runs apps for you, with memory.

bento
1