Deploying OmniRoute with Docker: A Complete Self-Hosting Guide

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:

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 file defines a development-ready stack containing the core OmniRoute service and optional Redis for WebSocket synchronization and caching. Deploy this configuration using:

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 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:

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:

• 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 and 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 file runs OmniRoute on a single port (20128) suitable for local development, while 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}