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

# Docker

> Deploy Ringlyra AI using Docker for local development and remote server environments

Ringlyra 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 Ringlyra 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 Ringlyra AI locally with Docker.

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

For local development and testing, you can run Ringlyra AI directly on your machine using Docker with a small startup script.

### Quick Start

Download the compose file and starter script, then confirm the prompt to start Ringlyra AI:

<CodeGroup>
  ```bash macOS/Linux theme={null}
  curl -o docker-compose.yaml https://raw.githubusercontent.com/ringlyra-hq/ringlyra/main/docker-compose.yaml && curl -o start_docker.sh https://raw.githubusercontent.com/ringlyra-hq/ringlyra/main/scripts/start_docker.sh && chmod +x start_docker.sh && ./start_docker.sh
  ```

  ```powershell Windows theme={null}
  Invoke-WebRequest -OutFile docker-compose.yaml https://raw.githubusercontent.com/ringlyra-hq/ringlyra/main/docker-compose.yaml
  Invoke-WebRequest -OutFile start_docker.ps1 https://raw.githubusercontent.com/ringlyra-hq/ringlyra/main/scripts/start_docker.ps1
  .\start_docker.ps1
  ```
</CodeGroup>

This setup:

* Downloads the latest docker-compose.yaml
* Creates `OSS_JWT_SECRET` in `.env` if one does not already exist
* Prompts before running Docker Compose
* 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` before running `./start_docker.sh` or `.\start_docker.ps1`.
</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 theme={null}
  curl -o setup_local.sh https://raw.githubusercontent.com/ringlyra-hq/ringlyra/main/scripts/setup_local.sh && chmod +x setup_local.sh && ./setup_local.sh
  ```

  ```powershell Windows theme={null}
  Invoke-WebRequest -OutFile setup_local.ps1 https://raw.githubusercontent.com/ringlyra-hq/ringlyra/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 JWT and TURN credentials, and the small helper bundle that `ringlyra-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 theme={null}
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 Ringlyra 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 Ringlyra to a Remote Server" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

Deploy Ringlyra 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 theme={null}
curl -o setup_remote.sh https://raw.githubusercontent.com/ringlyra-hq/ringlyra/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 `ringlyra-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 Ringlyra. The script prints the exact command to run at the end — it differs slightly between modes:

<CodeGroup>
  ```bash Prebuilt mode theme={null}
  cd ringlyra
  ./remote_up.sh
  ```

  ```bash Build mode theme={null}
  cd ringlyra
  ./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 `ringlyra/` 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_ringlyra_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 `ringlyra/` (default: `ringlyra-hq/ringlyra@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 ringlyra 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 theme={null}
cd ringlyra
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 theme={null}
cd ringlyra

# 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 theme={null}
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 theme={null}
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 theme={null}
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.