# Docker Container

> Source: `src/content/docs/self-hosting/docker-container.mdx`
> Canonical URL: https://rivet.dev/docs/self-hosting/docker-container
> Description: Run Rivet Engine in a single Docker container.

---
## Quick Start

### Start the engine

```bash
docker run -d \
  --name rivet-engine \
  -p 6420:6420 \
  -v rivet-data:/data \
  -e RIVET__FILE_SYSTEM__PATH="/data" \
  rivetdev/engine:latest
```

### Verify the engine is running

```bash
curl http://localhost:6420/health
```

## Connecting Your Project

Once the engine is running, connect your app to it.

### Create your server

Follow the [quickstart](/docs/actors/quickstart/backend) to create a working server with actors.

### Start your app with RIVET_ENDPOINT

Set `RIVET_ENDPOINT` to tell your app to connect to the engine as a runner instead of running standalone:

```bash @nocheck
RIVET_ENDPOINT="http://default:admin@host.docker.internal:6420" npm start
```

If running your app outside of Docker, use `localhost` instead of `host.docker.internal`:

```bash @nocheck
RIVET_ENDPOINT="http://default:admin@localhost:6420" npm start
```

See [Endpoints](/docs/general/endpoints) for all options.

### Register your runner with the engine

### Dashboard

1. Open the Rivet Engine dashboard at `http://localhost:6420`.
2. Enter your admin token when prompted.
3. In the namespace sidebar, click **Settings**.
4. Click **Add Provider**, then choose **Custom**.
5. Click **Next**.
6. Go to **Confirm Connection**, enter your app endpoint, then click **Add**.

### CLI (curl)

Register your runner programmatically via the engine API:

```bash @nocheck
curl -X PUT "http://localhost:6420/runner-configs/default?namespace=default" \
  -H "Content-Type: application/json" \
  -d '{
    "datacenters": {
      "default": {
        "normal": {}
      }
    }
  }'
```

## Configuration

### Environment Variables

Configure Rivet using environment variables:

```bash
docker run -d \
  --name rivet-engine \
  -p 6420:6420 \
  -v rivet-data:/data \
  -e RIVET__FILE_SYSTEM__PATH="/data" \
  -e RIVET__POSTGRES__URL="postgresql://postgres:password@localhost:5432/db" \
  rivetdev/engine:latest
```

### Config File

Mount a JSON configuration file:

```bash
docker run -d \
  --name rivet-engine \
  -p 6420:6420 \
  -v rivet-data:/data \
  -v $(pwd)/rivet-config.json:/etc/rivet/config.json:ro \
  rivetdev/engine:latest
```

Create `rivet-config.json` in your working directory. See the [Configuration](/docs/self-hosting/configuration) docs for all available options and the full [JSON Schema](/docs/engine-config-schema.json).

```json
{
  "postgres": {
    "url": "postgresql://postgres:password@localhost:5432/db"
  }
}
```

### Postgres Setup

PostgreSQL is the recommended backend for multi-node self-hosted deployments today, but it remains experimental. For a production-ready single-node Rivet deployment, use the file system backend (RocksDB-based). Enterprise teams can contact [enterprise support](https://rivet.dev/sales) about FoundationDB for the most scalable production-ready deployment.

```bash
# Create network
docker network create rivet-net

# Run PostgreSQL
docker run -d \
  --name postgres \
  --network rivet-net \
  -e POSTGRES_DB=rivet \
  -e POSTGRES_USER=rivet \
  -e POSTGRES_PASSWORD=rivet_password \
  -v postgres-data:/var/lib/postgresql/data \
  postgres:15

# Run Rivet Engine
docker run -d \
  --name rivet-engine \
  --network rivet-net \
  -p 6420:6420 \
  -e RIVET__POSTGRES__URL="postgresql://rivet:rivet_password@postgres:5432/rivet" \
  rivetdev/engine
```

## Next Steps

- Review the [Production Checklist](/docs/self-hosting/production-checklist) before going live
- Use [Docker Compose](/docs/self-hosting/docker-compose) for multi-container setups
- See [Configuration](/docs/self-hosting/configuration) for all options

_Source doc path: /docs/self-hosting/docker-container_