Deploy and Host Convex on Railway

Convex is an open-source reactive backend for app developers. It combines a document database, server functions written in TypeScript (queries, mutations and actions), scheduling, file storage and full-text search. Clients subscribe to queries and get updates automatically. This template runs the self-hosted Convex backend and its web dashboard.

About Hosting Convex

Self-hosting Convex means running two containers: the backend, which stores data and runs your functions, and the dashboard, a web UI for browsing data, logs and functions. The backend needs persistent storage for its database and files, a public HTTPS URL for clients and the Convex CLI, and a URL for HTTP actions. Access is controlled by an admin key derived from a secret instance key. This template uses the official images pinned by digest. It keeps the SQLite database and files on a Railway volume, serves HTTP actions under /http on the backend domain, and prints an admin key to the backend logs at every start.

Common Use Cases

Backend and real-time database for React, Next.js, React Native or other web and mobile apps
Running Convex functions, cron jobs and HTTP webhooks on infrastructure you control
Development, staging or data-residency setups that need the same Convex API as Convex Cloud

Dependencies for Convex Hosting

A Railway volume for the backend's SQLite database, file storage and search indexes
The Convex CLI (npx convex, from the convex npm package) in your app project to push functions

Deployment Dependencies

Convex self-hosting guide: https://github.com/convex/convex-backend/blob/main/self-hosted/README.md
Backend image: https://github.com/convex/convex-backend/pkgs/container/convex-backend
Dashboard image: https://github.com/convex/convex-backend/pkgs/container/convex-dashboard
Releases: https://github.com/convex/convex-backend/releases

Implementation Details

Services: convex-backend (API, functions, HTTP actions; volume at /convex/data) and convex-dashboard (web UI). Both run build d1fcbeaf (2026-10-28) of the official images, pinned by digest. Keep both on the same build when you upgrade.

Get the admin key: open the convex-backend service, then Deployments → View logs, and copy the line below CONVEX ADMIN KEY (it starts with convex-self-hosted|). A new valid key is printed at every start, and older keys keep working while INSTANCE_SECRET stays the same. Treat it like a password.

Sign in to the dashboard: open the convex-dashboard URL and paste the admin key. The deployment URL is already filled in.

Connect your app: in your Convex project, set these in .env.local, then run npx convex deploy (or npx convex dev):

CONVEX_SELF_HOSTED_URL=https://YOUR-BACKEND.up.railway.app
CONVEX_SELF_HOSTED_ADMIN_KEY=ADMIN-KEY-FROM-THE-LOGS

In your frontend, use the same backend URL as the Convex client URL.

HTTP actions are served at https://YOUR-BACKEND.up.railway.app/http/YOUR-ROUTE. For example, a route /hello is called at /http/hello.

Variables: INSTANCE_SECRET is generated once and signs every admin key. Changing it invalidates all existing keys. CONVEX_CLOUD_ORIGIN and CONVEX_SITE_ORIGIN follow the backend's Railway domain. If you add a custom domain, update both and redeploy both services. Upstream defaults from the official Docker Compose file (for example DISABLE_METRICS_ENDPOINT=true and 16 concurrent queries, mutations and actions) are set in the start command, and you can override any of them with a service variable. To turn off the anonymous usage beacon, set DISABLE_BEACON=true.

Postgres instead of SQLite: set POSTGRES_URL (the connection string without a database name) and DO_NOT_REQUIRE_SSL=1 on the backend, and create a database named convex_self_hosted, as described in upstream's Postgres guide. Files stay on the volume. Export your data with npx convex export before you switch.

Why Deploy Convex 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 Convex 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.