Docker deployment guide

Deploy Convex using Docker Compose for local development and production workloads

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