Deploy Convex

Deploy and Host Convex on Railway

Self-host Convex with its web dashboard, a persistent SQLite database, and file storage on a Railway volume.

About Hosting

This template includes two services using pinned official Convex images:

The backend has a generated instance secret, a /version readiness check, and a required persistent volume. The dashboard explicitly listens on 0.0.0.0. The dashboard and API use HTTPS domains generated by Railway.

Why Deploy

Run Convex queries, mutations, realtime subscriptions, and HTTP actions in your own Railway project. This SQLite configuration is intended for a single backend replica. Your frontend application is deployed separately.

Common Use Cases

• Build a reactive application with queries and transactional mutations.
• Develop and operate a self-hosted Convex backend with the web dashboard.
• Expose application HTTP actions and webhook handlers through the backend domain.

Dependencies for Convex Hosting

Convex requires the official Convex backend and dashboard container images and a persistent Railway volume mounted at /convex/data. This template includes both services and stores the database in SQLite on that volume. You also need the Railway CLI to generate an administrator key and the Convex CLI in your application project to deploy functions.

Deployment Dependencies

• The official Convex backend and dashboard container images, pinned by digest.
• A Railway volume attached to convex-backend at /convex/data.
• Railway CLI access to generate an administrator key inside the backend.
• The Convex CLI in your application project to deploy functions.

First use

1. Deploy both services and wait for their healthchecks to pass.
2. Open a Railway SSH session into convex-backend, then run ./generate_admin_key.sh from /convex.
3. Keep the resulting administrator key private. Open the convex-dashboard HTTPS domain and use the key to sign in.
4. In your application's private .env.local, set CONVEX_SELF_HOSTED_URL to the backend's HTTPS URL and CONVEX_SELF_HOSTED_ADMIN_KEY to that key. Never expose the administrator key through browser environment variables or commit it to source control.
5. Run npx convex dev from your application project to deploy functions. Configure your frontend's Convex client with the backend HTTPS URL.

HTTP actions

The API listener supports HTTP actions under /http. If your Convex HTTP router registers /sendEmail, call https://YOUR_BACKEND_DOMAIN/http/sendEmail. CONVEX_SITE_ORIGIN is configured to that backend domain plus /http. Do not add /http to the route registered in your application.

Convex also listens on port 3211 for direct HTTP-action traffic, but that port has no public domain in this template. If you add a separate domain targeting 3211, change CONVEX_SITE_ORIGIN to that domain without the /http suffix and use routes at its root.

HTTP-action authorization is your application's responsibility. Keep administrative keys out of public clients. Public application functions must enforce their intended authentication and authorization rules.

Persistence, backups and upgrades

Keep one backend replica and preserve /convex/data, INSTANCE_NAME, and INSTANCE_SECRET across redeployments. The volume holds SQLite data, file storage, and instance credentials. Replacing the volume or changing the instance secret can lose data or invalidate administrator keys.

Use Convex exports and Railway volume backups. Keep a consistent backup of database, files, and secrets outside the running project. Test restoration into a separate instance before relying on it. Review upstream migration notes before changing the pinned images; downgrading can require restoring a compatible backup.

PostgreSQL, MySQL, S3, high availability, and a frontend application are not provisioned by this template. Adding backend replicas is unsupported for this SQLite deployment.

Validation

Local Docker checks passed on September 23, 2026: backend startup, administrator-key generation, function deployment, mutation/query, an HTTP action through /http, dashboard HTTP 200, persistence after restart and container recreation, and authentication with the original administrator key after recreation. Browser dashboard login, Railway networking, resource requirements, and backup restoration remain unverified. Verify dashboard login, an application mutation/query, an HTTP action, restart persistence, and restoration in your own environment before production use.

Sources

• Official self-hosting instructions
• Official Docker Compose configuration
• Railway-specific upstream instructions
• Convex application documentation

Upstream software retains its own license. This community-maintained deployment template does not imply vendor endorsement.