Deploy and Host Onyx Lite on Railway

Onyx is an open source AI chat platform that works with every LLM. It gives a team a shared, self hosted chat workspace with agents, Projects, actions and tools, MCP support, per user file uploads, real accounts and roles, and SSO. This template deploys Onyx in its official Lite configuration, which is the upstream topology for running Onyx without a search index.

About Hosting Onyx Lite

Onyx ships two documented topologies. The full stack runs ten containers, including OpenSearch, Redis, MinIO, a Celery worker and two machine learning model servers, and upstream sizes it at about 12 CPU and 24 GB of memory. The Lite topology, defined in upstream's own docker-compose.onyx-lite.yml, sets DISABLE_VECTOR_DB=true and moves caching, sessions and file storage onto PostgreSQL, which removes six of those containers and brings the footprint down to about 2.5 CPU and 1.7 GiB.

This template is the Lite topology: an nginx front door, the FastAPI backend, the Next.js UI, and PostgreSQL. It pins v4.7.7, generates USER_AUTH_SECRET and ENCRYPTION_KEY_SECRET for you, wires every service over Railway's private network with explicit ports, and renders the nginx config at boot so the proxy re-resolves the private DNS names on every redeploy instead of caching a stale address the way upstream's static config would.

The trade is explicit: connectors and retrieval augmented search are off. Chat, agents, Projects, tools and user file uploads all work. If you need to index Slack, Google Drive, Confluence or GitHub, use the full stack instead and budget accordingly.

Common Use Cases

A shared team ChatGPT that you own, pointed at your own OpenAI, Anthropic, Azure, Bedrock or Gemini keys
One front door for many models, with per user accounts, roles and SSO instead of shared API keys
Custom agents and Projects that colleagues can reuse, with system prompts and tools defined once
Chat over documents you upload in the conversation, without standing up a search cluster
An MCP aware chat client for teams already running MCP servers

Dependencies for Onyx Lite Hosting

PostgreSQL: required, and included. In Lite mode it also holds the cache, the session store and uploaded files.
An LLM provider key: not needed to boot. Onyx starts, migrates and lets you sign up with zero keys, but chat cannot answer until you add a provider in Admin Panel > Configuration > LLM.
No Redis, no OpenSearch, no object store, no model servers: all replaced by PostgreSQL or switched off in Lite mode.

Deployment Dependencies

Implementation Details

Four services. Only the nginx service is public.

# onyx-api
PORT=8080
DISABLE_VECTOR_DB=true
CACHE_BACKEND=postgres
AUTH_BACKEND=postgres
FILE_STORE_BACKEND=postgres
DISABLE_MODEL_SERVER=true
USER_AUTH_SECRET=${{secret(64,"abcdef0123456789")}}
ENCRYPTION_KEY_SECRET=${{secret(32)}}
WEB_DOMAIN=https://${{Onyx.RAILWAY_PUBLIC_DOMAIN}}

# onyx-web
PORT=3000
HOSTNAME=0.0.0.0
INTERNAL_URL=http://${{onyx-api.RAILWAY_PRIVATE_DOMAIN}}:8080

# Onyx (nginx)
PORT=80
ONYX_API_HOST=${{onyx-api.RAILWAY_PRIVATE_DOMAIN}}:8080
ONYX_WEB_HOST=${{onyx-web.RAILWAY_PRIVATE_DOMAIN}}:3000

The API server runs alembic upgrade head before uvicorn binds, and a fresh database has 440 migrations to apply, so the first deploy takes a few minutes and the healthcheck window is set to 15 minutes.

First Steps After Deploy

Open the Onyx service domain and create the first account. It becomes the admin. Only addresses at the domain you gave in VALID_EMAIL_DOMAINS may register, so a passer by cannot claim the instance.
Add an LLM provider in Admin Panel > Configuration > LLM. Any OpenAI compatible base URL works, including a LiteLLM gateway running in the same Railway project.
To close registration entirely once your users have accounts: Admin Panel > Organization > Security, turn password signup off.
Optionally connect SSO in Admin Panel > Organization > SSO Providers (Google, OIDC or SAML).

Authentication cannot be disabled. AUTH_TYPE=disabled was removed in Onyx v4.4, so this deployment is never anonymous.

Why Deploy Onyx Lite 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 Lite on Railway, you get the full Onyx chat platform with generated secrets, a managed PostgreSQL volume, health checks, managed SSL and private networking between the proxy, the API and the UI, on a footprint small enough to actually leave running.