# Deploying OmniRoute with Docker: A Complete Self-Hosting Guide

> Self-host OmniRoute easily with Docker. Follow this guide to deploy using the official image and a persistent volume for seamless SQLite state management.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-15

---

**Deploy OmniRoute using the official multi-arch Docker image by mounting a persistent volume to `/data` and setting the `DATA_DIR` environment variable to maintain SQLite state across container restarts.**

Deploying OmniRoute with Docker provides a streamlined method to run this self-hosted AI gateway on any infrastructure, from cloud VMs to Raspberry Pi devices. The repository at `diegosouzapw/OmniRoute` ships production-ready container configurations that bundle the Next.js dashboard and API server into a minimal Node.js image. Whether you need a quick local instance or a production deployment with TLS termination, Docker offers the fastest path to operational AI gateway infrastructure.

## Prerequisites

Before deploying OmniRoute with Docker, ensure you have Docker Engine 20.10 or later installed on your host system. For production deployments using the provided compose files, Docker Compose V2 is required to process the multi-service configurations.

The container image supports both `amd64` and `arm64` architectures, making it compatible with x86_64 cloud instances, ARM-based servers, and Apple Silicon Macs without emulation overhead.

## Understanding the OmniRoute Container Architecture

The OmniRoute container architecture follows a minimal, stateless design philosophy while accommodating persistent data requirements through external volumes.

### Base Image and Build Process

As defined in the repository's `Dockerfile`, the build process uses `node:24.15.0-trixie-slim` as the base image to minimize attack surface and image size. The build copies the compiled Next.js application assets and server code, then sets the container entry point to the bundled CLI command `omniroute serve`. This design ensures the container starts the gateway service immediately upon launch without requiring manual initialization scripts.

### Multi-Architecture Support

The image is built for both `amd64` and `arm64` platforms, enabling deployment across heterogeneous infrastructure. This multi-arch support allows you to run identical configurations on AWS EC2 instances, Oracle Cloud ARM Ampere nodes, or Raspberry Pi 4/5 devices without modifying deployment manifests.

## Basic Docker Deployment

For simple deployments or testing environments, running OmniRoute directly via `docker run` requires minimal configuration.

### Quick Start with Docker Run

Execute the following command to launch OmniRoute with default settings:

```bash
docker run -d \
  --name omniroute \
  -p 20128:20128 \
  -v $HOME/.omniroute:/data \
  -e DATA_DIR=/data \
  diegosouzapw/omniroute

```

This command exposes the HTTP/API port (default **20128**) on your host and persists all SQLite data, cache files, and configuration to `$HOME/.omniroute` on the host filesystem.

### Data Persistence Configuration

OmniRoute stores state—including the SQLite database, request logs, and cached provider responses—within the container's `/data` directory. To prevent data loss during container updates or restarts, you must mount a host directory to this path via the `DATA_DIR` environment variable. If `DATA_DIR` is unset, the application defaults to `~/.omniroute` inside the container, which is non-persistent and will be destroyed on container removal.

## Docker Compose Deployment Strategies

For production workloads or development environments requiring additional services like Redis caching, the repository provides orchestration files that define multi-container stacks.

### Development Environment Setup

The [`docker-compose.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.yml) file defines a development-ready stack containing the core OmniRoute service and optional Redis for WebSocket synchronization and caching. Deploy this configuration using:

```bash
docker compose up -d

```

By default, this exposes both the API and dashboard on `localhost:20128` and connects the OmniRoute container to Redis for session management. The compose file automatically builds the image from the local `Dockerfile` if not present in the local registry.

### Production Deployment with TLS

For production environments, use [`docker-compose.prod.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.prod.yml) alongside the optional Caddy reverse proxy. This variant configures separate ports for dashboard and API traffic:

- **Dashboard**: `PROD_DASHBOARD_PORT=20130`
- **API**: `PROD_API_PORT=20131`

Deploy the production stack with:

```bash
docker compose -f docker-compose.prod.yml up -d

```

The production compose configuration expects a Caddy service to handle TLS termination and forward traffic to the appropriate OmniRoute endpoints. You can customize the Caddy configuration to expose the service behind `OMNIROUTE_BASE_PATH` when deploying under a sub-path.

## Environment Variables and Configuration

OmniRoute's containerized deployment relies on environment variables for runtime configuration rather than baked-in config files. Key variables include:

- **`PORT`**: Sets the HTTP/API port (default: **20128**)
- **`DATA_DIR`**: Points to the mounted volume path (typically `/data`)
- **`OMNIROUTE_BASE_PATH`**: Configures the base URL path when running behind a reverse proxy
- **`LOCAL_HOSTNAMES`**: Defines intra-service DNS names for internal routing

Never copy `.env` files or secrets into the Docker image during build. Instead, pass sensitive configuration via runtime environment variables or Docker secrets, as the `Dockerfile` excludes local environment files from the build context for security.

## Security Best Practices

When deploying OmniRoute with Docker, follow these security guidelines derived from the [`docs/guides/DOCKER_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/DOCKER_GUIDE.md):

- **Expose ports selectively**: Avoid binding the OmniRoute container directly to host ports unless necessary; use Docker networks or reverse proxies for internal communication.
- **Volume permissions**: Ensure the host directory mounted to `/data` has appropriate ownership to prevent permission conflicts with the Node.js process running inside the container.
- **Secret management**: Supply API keys and provider credentials via environment variables at runtime, never via build arguments or committed configuration files.
- **Network isolation**: Configure `LOCAL_HOSTNAMES` to restrict internal DNS resolution to trusted services within the Docker network.

## Summary

- **OmniRoute** packages its Next.js frontend and API gateway into a minimal `node:24.15.0-trixie-slim` container that launches via the `omniroute serve` CLI command.
- **Data persistence** requires mounting a host directory to `/data` and setting the `DATA_DIR` environment variable to protect SQLite state across container lifecycle events.
- **Multi-architecture builds** support both `amd64` and `arm64` platforms, enabling deployment on standard cloud VMs and ARM edge devices.
- **Docker Compose** configurations in [`docker-compose.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.yml) and [`docker-compose.prod.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.prod.yml) provide ready-to-use orchestration for development (port 20128) and production (ports 20130/20131 with TLS) scenarios.
- **Security** mandates runtime injection of secrets, exclusion of `.env` files from images, and careful port exposure management.

## Frequently Asked Questions

### How do I persist OmniRoute data when using Docker?

Mount a host directory to the container's `/data` path and set the `DATA_DIR` environment variable to `/data`. This ensures the SQLite database, configuration files, and cache survive container restarts and image updates. For example, use `-v /opt/omniroute:/data -e DATA_DIR=/data` in your run command.

### Can I run OmniRoute on a Raspberry Pi or ARM-based server?

Yes, the official Docker image supports both `amd64` and `arm64` architectures. The multi-arch build defined in the `Dockerfile` allows you to run identical deployment commands on x86_64 cloud instances, Oracle Cloud ARM nodes, and Raspberry Pi 4/5 devices without platform-specific modifications.

### What is the difference between the development and production Docker Compose files?

The [`docker-compose.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.yml) file runs OmniRoute on a single port (20128) suitable for local development, while [`docker-compose.prod.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.prod.yml) separates the dashboard (port 20130) and API (port 20131) services and includes an optional Caddy reverse proxy configuration for TLS termination. The production variant also expects additional environment variables for production-specific tuning.

### How do I configure OmniRoute to run behind a reverse proxy with a sub-path?

Set the `OMNIROUTE_BASE_PATH` environment variable to your desired path prefix (e.g., `/omniroute`) when starting the container. This ensures the Next.js application generates correct internal URLs and asset paths. When using the provided Caddy configuration in production, this variable ensures proper request routing between the proxy and the OmniRoute service.