> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/get-convex/convex-backend/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Download docker-compose.yml">
    Download the official `docker-compose.yml` file:

    ```bash theme={null}
    curl -O https://raw.githubusercontent.com/get-convex/convex-backend/main/self-hosted/docker/docker-compose.yml
    ```
  </Step>

  <Step title="Start the services">
    Start the backend and dashboard:

    ```bash theme={null}
    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
  </Step>

  <Step title="Generate an admin key">
    Once the backend is running, generate an admin key for the dashboard and CLI:

    ```bash theme={null}
    docker compose exec backend ./generate_admin_key.sh
    ```

    <Warning>
      Keep this admin key secure. It provides full administrative access to your Convex deployment.
    </Warning>
  </Step>

  <Step title="Configure your Convex project">
    In your Convex project directory, create a `.env.local` file with your deployment URL and admin key:

    ```bash .env.local theme={null}
    CONVEX_SELF_HOSTED_URL='http://127.0.0.1:3210'
    CONVEX_SELF_HOSTED_ADMIN_KEY='<your admin key>'
    ```

    <Warning>
      Do not commit `.env.local` to source control. Add it to your `.gitignore` file.
    </Warning>
  </Step>

  <Step title="Install the latest Convex package">
    Update to the latest version of Convex:

    ```bash theme={null}
    npm install convex@latest
    ```
  </Step>

  <Step title="Deploy your code">
    Push code, run queries, import data, and more:

    ```bash theme={null}
    npx convex dev
    npx convex --help  # see all available commands
    ```
  </Step>
</Steps>

## Docker Compose configuration

The `docker-compose.yml` file includes two services:

### Backend service

```yaml theme={null}
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

```yaml theme={null}
  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`:

```bash .env theme={null}
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.

<Warning>
  When deploying to cloud hosting platforms (AWS, GCP, Azure, etc.), ensure you configure persistent storage (e.g., AWS EBS volumes) to prevent data loss.
</Warning>

## Pinning to a specific version

For production deployments, pin to a specific version instead of using `latest`:

```yaml theme={null}
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:

```bash .env theme={null}
REV=v0.1.0
```

## Health checks

The backend includes a built-in health check endpoint:

```yaml theme={null}
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:

<Steps>
  <Step title="Download docker-compose.yml to your server">
    ```bash theme={null}
    curl -O https://raw.githubusercontent.com/get-convex/convex-backend/main/self-hosted/docker/docker-compose.yml
    ```
  </Step>

  <Step title="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`
  </Step>

  <Step title="Configure environment variables">
    Create a `.env` file with your domain configuration:

    ```bash .env theme={null}
    # 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'
    ```
  </Step>

  <Step title="Start the services">
    ```bash theme={null}
    docker compose up -d
    ```
  </Step>

  <Step title="Generate and use admin key">
    ```bash theme={null}
    docker compose exec backend ./generate_admin_key.sh
    ```

    In your Convex project's `.env.local`:

    ```bash .env.local theme={null}
    CONVEX_SELF_HOSTED_URL='https://api.my-domain.com'
    CONVEX_SELF_HOSTED_ADMIN_KEY='<your admin key>'
    ```
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="sliders" href="/self-hosting/configuration">
    Configure environment variables and runtime options
  </Card>

  <Card title="Database setup" icon="database" href="/self-hosting/database-setup">
    Connect to PostgreSQL or MySQL for production
  </Card>

  <Card title="Storage" icon="cloud" href="/self-hosting/storage">
    Configure S3-compatible storage
  </Card>

  <Card title="Upgrading" icon="arrow-up" href="/self-hosting/upgrading">
    Learn how to upgrade your self-hosted deployment
  </Card>
</CardGroup>