dograh/docs/deployment/docker.mdx

---
title: "Docker"
description: "Deploy Dograh AI using Docker for local development and remote server environments"
---

Dograh AI can be deployed using Docker in two main configurations. Choose the option that best fits your needs:

- **Option 1**: For local development and testing on your own machine
- **Option 2**: For remote server deployment with HTTPS (using IP address). If you also have a custom domain, you can first deploy Dograh stack on your server using steps in this document and then proceed to the [Custom Domain](deployment/custom-domain) section.

## Option 1: Local Docker Deployment

Watch the video tutorial below for a step-by-step walkthrough of setting up Dograh AI locally with Docker.

<iframe
  className="w-full aspect-video rounded-xl"
  src="https://www.tella.tv/video/dograh-local-setup-with-docker-5wsf/embed?b=1&title=1&a=1&loop=0&t=0&muted=0&wt=1"
  title="Dograh Local Setup with Docker"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
></iframe>

For local development and testing, you can run Dograh AI directly on your machine using Docker with a single command.

### Quick Start

Run this single command to download and start Dograh AI:

```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/dograh-hq/dograh/main/docker-compose.yaml && REGISTRY=ghcr.io/dograh-hq ENABLE_TELEMETRY=true docker compose up --pull always
```

This command:
- Downloads the latest docker-compose.yaml
- Starts all required services including PostgreSQL, Redis, MinIO, API, and UI
- Pulls the latest images automatically

### Access the Application

Once running (first startup takes 2-3 minutes), open:
```
http://localhost:3010
```

<Note>
You can disable telemetry by setting `ENABLE_TELEMETRY=false` in the command above.
</Note>

### Troubleshooting WebRTC Connectivity

The Quick Start above relies on direct peer-to-peer WebRTC between your browser and the API container. On most single-machine setups this works without any extra configuration. If you hit any of the following, you likely need a TURN server in the path:

- The call connects but no audio flows in either direction
- The browser console reports `iceConnectionState: failed`
- You are testing from a browser on your smartphone or another device on your LAN against the laptop running Docker
- A VPN, corporate firewall, or strict NAT sits between the browser and Docker

For these cases, use the alternate local setup script which configures a coturn TURN server alongside the rest of the stack:

<CodeGroup>
```bash macOS/Linux
curl -o setup_local.sh https://raw.githubusercontent.com/dograh-hq/dograh/main/scripts/setup_local.sh && chmod +x setup_local.sh && ./setup_local.sh
```
```powershell Windows
Invoke-WebRequest -OutFile setup_local.ps1 https://raw.githubusercontent.com/dograh-hq/dograh/main/scripts/setup_local.ps1
.\setup_local.ps1
```
</CodeGroup>

The script will prompt you for:
- Whether to enable coturn (answer `y`)
- The host browsers should use to reach TURN (press Enter for `127.0.0.1`; use your LAN IP if testing from another device on the same network)
- A shared secret for the TURN server (press Enter to generate a random one)

It creates `docker-compose.yaml`, a `.env` file with TURN credentials, and the small helper bundle that `dograh-init` uses to render coturn config at startup. Start the stack with the `local-turn` profile so coturn comes up alongside the other services:

```bash
docker compose --profile local-turn up --pull always
```

The application is still available at `http://localhost:3010`.

<Note>
To verify that media is actually traversing TURN (and not silently falling back to a direct path), set `FORCE_TURN_RELAY=true` in `.env` and restart the API. The browser will then only use relay ICE candidates — if TURN is misconfigured or unreachable, the call fails cleanly with `ICE failed` in the console instead of appearing to work. Set it back to `false` once you have verified connectivity.
</Note>

## Option 2: Remote Server Deployment

Watch the video tutorial below for a step-by-step walkthrough of deploying Dograh AI to a remote server.

<iframe
  className="w-full aspect-video rounded-xl"
  src="https://www.tella.tv/video/deploying-dogra-to-a-remote-server-80ai/embed?b=1&title=1&a=1&loop=0&t=0&muted=0&wt=1"
  title="Deploying Dograh to a Remote Server"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
></iframe>

Deploy Dograh AI on a remote server to make it accessible from anywhere using your server's IP address. This setup includes HTTPS support via nginx reverse proxy with self-signed certificates. **We need to serve the application over HTTPS, since modern browsers only allow microphone permissions for websites being served over HTTPS**.

<Warning>We highly recommend you set up the platform on a fresh server, so that there are less chances of confliciting dependencies, and ports from other applications.</Warning>

### Prerequisites

- A server with Docker and Docker Compose installed. It should have minimum of 8 GB RAM and 4 vCPUs.
- Public IP address for your server. You can also access the server using a local IP address in your VPC as long as its reachable from your browser.
- TCP Ports 80, 443, 3478, 5349 and UDP Ports 3478, 5349 and 49152:49200 reachable from Internet (Port 80 and 443 to access the UI and rest of the ports for WebRTC Signaling)

<Note>IMPORTANT: Please double check the ports on your firewall. Please refer to your server hosting provider's documentaion on how you can open these ports in the firewall of the server.</Note>

### Quick Setup

Run the automated setup script that will configure everything for you:

```bash
curl -o setup_remote.sh https://raw.githubusercontent.com/dograh-hq/dograh/main/scripts/setup_remote.sh && chmod +x setup_remote.sh && ./setup_remote.sh
```

The script will prompt you for:
- Your server's public IP address
- A password for the TURN server (optional, press Enter for default)
- Deployment mode — press Enter for **prebuilt** (pulls official images, the recommended default) or pick **build** to compile images from source. Use **build** when you maintain a fork or want to deploy local customizations — see [Building from source](#building-from-source) below.
- Number of FastAPI workers (uvicorn processes nginx will load-balance) — press Enter for the default of `4`, or pick a value that suits your server's CPU count. See [Scaling](/deployment/scaling) for sizing guidance and how to change this on a running stack.

It will automatically:
- Get the source — `docker-compose.yaml` only (prebuilt mode), or clone the full repo (build mode)
- Download the validated remote deployment helper bundle
- Generate SSL certificates
- Create an environment file with TURN server configuration
- Validate the runtime config that `dograh-init` will render from `.env`
- Write a `docker-compose.override.yaml` with build directives (build mode only)

### Start the Application

<Note>
Please ensure that Docker Compose is installed on your machine before proceeding further. You can check whether its installed by running `docker compose version` command. If its not installed, please install it by following your server provider documentation.
</Note>

After the setup script completes, start Dograh. The script prints the exact command to run at the end — it differs slightly between modes:

<CodeGroup>
```bash Prebuilt mode
cd dograh
./remote_up.sh
```
```bash Build mode
cd dograh
./remote_up.sh --build
```
</CodeGroup>

First boot in build mode takes several minutes — Docker has to build both the API and UI images before the stack comes up. 

### Access Your Application

Your application will be available at
```
https://YOUR_SERVER_IP
```

<Note>
Since we are using a self-signed certificate, your browser will show a security warning. You can safely accept it to proceed.
</Note>

You should be able to create and test a voice agent now. 

### Configuration Notes

- The remote deployment includes an nginx reverse proxy for HTTPS termination
- File downloads (transcripts, recordings) are automatically routed through nginx
- WebSocket connections for real-time features are properly proxied
- The setup uses self-signed certificates - browsers will show a security warning that you can safely accept for testing
- The TURN server (coturn) is configured for WebRTC NAT traversal
- For production deployments with proper SSL and domain names, see the [Custom Domain](custom-domain) documentation

### Files Created

The setup script creates the following files in the `dograh/` directory:

| File | Purpose |
|------|---------|
| `docker-compose.yaml` | Main Docker Compose configuration |
| `docker-compose.override.yaml` | Build directives for `api` and `ui` (**build mode only**) |
| `remote_up.sh` | Validated startup wrapper for the remote stack |
| `scripts/run_dograh_init.sh` | One-shot init renderer/validator used by Docker Compose |
| `scripts/lib/setup_common.sh` | Shared deployment helper library |
| `deploy/templates/` | nginx and coturn runtime config templates |
| `generate_certificate.sh` | Script to regenerate SSL certificates |
| `certs/local.crt` | Self-signed SSL certificate |
| `certs/local.key` | SSL private key |
| `.env` | Single source of truth for deployment settings (TURN secret, JWT secret, FastAPI worker count, public host/base URL) |

### Building from source

If you maintain a fork or want to ship local code changes without waiting for an official image release, pick **build** when the setup script prompts for deployment mode.

In this mode the script:

1. Clones the repo into `dograh/` (default: `dograh-hq/dograh@main`; the script will ask for an `owner/name` and `branch` so a fork can point at its own).
2. If you run the script from inside an existing dograh checkout, offers to use that checkout instead of cloning.
3. Generates a `docker-compose.override.yaml` next to `docker-compose.yaml` that swaps the `image:` directives for local `build:` directives. Docker Compose auto-loads the override file — you don't need to pass any `-f` flags.

#### Updating after a code change

Whenever the codebase changes — a `git pull`, a local edit, or a submodule bump — rebuild the `api` and `ui` images and recreate the running containers so they pick up the new code.

**TL;DR (rebuilds both services and restarts in one shot):**

```bash
cd dograh
sudo docker compose --profile remote up -d --build
```

`--build` rebuilds any service whose `build:` context has changed (both `api` and `ui` are wired through the `docker-compose.override.yaml` written by `setup_remote.sh`), and `up -d` recreates the affected containers so they run off the new image.

**Step-by-step** — use this when you're pulling fresh code from a remote, or want to be explicit:

```bash
cd dograh

# 1. Pull the latest source.
git pull
git submodule update --init --recursive   # picks up pipecat submodule bumps

# 2. Rebuild both images.
sudo docker compose --profile remote build api ui

# 3. Recreate the running containers so they use the new images.
sudo docker compose --profile remote up -d
```

<Warning>If you update `pipecat` submodule, you must do `git submodule update --init --recursive`, or the Docker build step will not pick up `pipecat` changes</Warning>

**Rebuild a single service** — faster when you only changed one side:

```bash
sudo docker compose --profile remote build api      # or: build ui
sudo docker compose --profile remote up -d api      # or: up -d ui
```

**Force a clean rebuild** — needed when a base image changed, a `pip install` was added, or you suspect a stale layer:

```bash
sudo docker compose --profile remote build --no-cache api ui
sudo docker compose --profile remote up -d
```

**Verify the containers were actually recreated** — check the `CREATED` column shows a recent timestamp, not minutes/hours ago:

```bash
sudo docker compose --profile remote ps
```

To revert to pulling official images, delete `docker-compose.override.yaml` and start the stack with `--pull always` as in the [prebuilt flow](#start-the-application).

<Note>
Build mode is for **fork maintainers and self-hosters who want to deploy customized images** — not for active development on the code itself. For day-to-day contributor work (fast reload, IDE/LSP integration), use the [contributor setup](/contribution/setup) instead.
</Note>

### Next Steps
Now that you are able to create and test a voice agent, you can setup a custom domain and setup SSL using letsencrypt. Checkout [Custom Domain](custom-domain) for instructions on how to do that.