Skip to main content
This guide shows you how to deploy Convex using Docker Compose, the easiest way to get started with self-hosting.

​
Prerequisites

  • Docker and Docker Compose installed
  • Latest version of the Convex npm package (convex@latest)

​
Quick start

1

Download docker-compose.yml

Download the official docker-compose.yml file:
curl -O https://raw.githubusercontent.com/get-convex/convex-backend/main/self-hosted/docker/docker-compose.yml
2

Start the services

Start the backend and dashboard:
docker compose up
This will:
  • Start the Convex backend on http://127.0.0.1:3210
  • Expose HTTP actions on http://127.0.0.1:3211
  • Start the dashboard on http://localhost:6791
  • Create a Docker volume for persistent data storage
3

Generate an admin key

Once the backend is running, generate an admin key for the dashboard and CLI:
docker compose exec backend ./generate_admin_key.sh
Keep this admin key secure. It provides full administrative access to your Convex deployment.
4

Configure your Convex project

In your Convex project directory, create a .env.local file with your deployment URL and admin key:
.env.local
CONVEX_SELF_HOSTED_URL='http://127.0.0.1:3210'
CONVEX_SELF_HOSTED_ADMIN_KEY='<your admin key>'
Do not commit .env.local to source control. Add it to your .gitignore file.
5

Install the latest Convex package

Update to the latest version of Convex:
npm install convex@latest
6

Deploy your code

Push code, run queries, import data, and more:
npx convex dev
npx convex --help  # see all available commands

​
Docker Compose configuration

The docker-compose.yml file includes two services:

​
Backend service

services:
  backend:
    image: ghcr.io/get-convex/convex-backend:latest
    stop_grace_period: 10s
    stop_signal: SIGINT
    ports:
      - "${PORT:-3210}:3210"
      - "${SITE_PROXY_PORT:-3211}:3211"
    volumes:
      - data:/convex/data
    environment:
      - CONVEX_CLOUD_ORIGIN=${CONVEX_CLOUD_ORIGIN:-http://127.0.0.1:${PORT:-3210}}
      - CONVEX_SITE_ORIGIN=${CONVEX_SITE_ORIGIN:-http://127.0.0.1:${SITE_PROXY_PORT:-3211}}
      - RUST_LOG=${RUST_LOG:-info}

​
Dashboard service

  dashboard:
    image: ghcr.io/get-convex/convex-dashboard:latest
    stop_grace_period: 10s
    stop_signal: SIGINT
    ports:
      - "${DASHBOARD_PORT:-6791}:6791"
    environment:
      - NEXT_PUBLIC_DEPLOYMENT_URL=${NEXT_PUBLIC_DEPLOYMENT_URL:-http://127.0.0.1:${PORT:-3210}}
    depends_on:
      backend:
        condition: service_healthy

​
Customizing ports

You can customize the default ports by creating a .env file next to docker-compose.yml:
.env
PORT=3210
SITE_PROXY_PORT=3211
DASHBOARD_PORT=6791

​
Persistent storage

By default, data is stored in a Docker-managed volume named data. This volume persists even when containers are stopped or removed.
When deploying to cloud hosting platforms (AWS, GCP, Azure, etc.), ensure you configure persistent storage (e.g., AWS EBS volumes) to prevent data loss.

​
Pinning to a specific version

For production deployments, pin to a specific version instead of using latest: 
services:
  backend:
    image: ghcr.io/get-convex/convex-backend:${REV}
  dashboard:
    image: ghcr.io/get-convex/convex-dashboard:${REV}
Then set the version in your .env file:
.env
REV=v0.1.0

​
Health checks

The backend includes a built-in health check endpoint: 
healthcheck:
  test: curl -f http://localhost:3210/version
  interval: 5s
  start_period: 10s
The dashboard depends on the backend being healthy before starting.

​
Accessing the dashboard

Visit http://localhost:6791 in your browser. You’ll need to authenticate using the admin key generated in step 3.

​
Hosting on your own infrastructure

To run Convex on your own servers with custom domains:
1

Download docker-compose.yml to your server

curl -O https://raw.githubusercontent.com/get-convex/convex-backend/main/self-hosted/docker/docker-compose.yml
2

Set up routing

Configure your reverse proxy (nginx, Caddy, etc.) to forward requests:
  • https://api.my-domain.com → http://localhost:3210
  • https://my-domain.com → http://localhost:3211
  • https://dashboard.my-domain.com → http://localhost:6791
3

Configure environment variables

Create a .env file with your domain configuration:
.env
# URL of the Convex API as accessed by the client/frontend
CONVEX_CLOUD_ORIGIN='https://api.my-domain.com'
# URL of Convex HTTP actions as accessed by the client/frontend
CONVEX_SITE_ORIGIN='https://my-domain.com'
# URL of the Convex API as accessed by the dashboard (browser)
NEXT_PUBLIC_DEPLOYMENT_URL='https://api.my-domain.com'
4

Start the services

docker compose up -d
5

Generate and use admin key

docker compose exec backend ./generate_admin_key.sh
In your Convex project’s .env.local:
.env.local
CONVEX_SELF_HOSTED_URL='https://api.my-domain.com'
CONVEX_SELF_HOSTED_ADMIN_KEY='<your admin key>'

​
Next steps

Configuration

Configure environment variables and runtime options

Database setup

Connect to PostgreSQL or MySQL for production

Storage

Configure S3-compatible storage

Upgrading

Learn how to upgrade your self-hosted deployment

Build docs developers (and LLMs) love

Get started for freeTalk to us