# Does OmniRoute Support Docker? Complete Setup Guide with Examples

> Yes OmniRoute supports Docker! Discover how to set up OmniRoute with Docker Compose, multi-stage builds, and container detection in this comprehensive guide.

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

---

**Yes, OmniRoute fully supports Docker with multi-stage builds, Docker-Compose configurations, and runtime container detection.**

OmniRoute treats Docker as a first-class deployment target. The `diegosouzapw/OmniRoute` repository ships everything needed to build, configure, and run the application in containers — from production-ready images to environment-specific Compose files and runtime detection logic.

## Docker Support Overview

OmniRoute's Docker implementation spans three layers:

- **Build layer**: Multi-stage `Dockerfile` with separate base, builder, and runner stages
- **Orchestration layer**: Docker-Compose files for development and production
- **Runtime layer**: Automatic container detection that adapts feature behavior

This architecture keeps images lean while preserving full functionality for both the API backend and the Next.js dashboard.

## Building the OmniRoute Docker Image

The repository's `Dockerfile` (at the repository root) defines a multi-stage build process using `node:26-trixie-slim` as the base image. Lines 2–28 handle dependency installation, while lines 125–232 produce the optimized runtime images.

Build the image locally:

```bash
docker build -t omniroute:latest .

```

The build produces separate outputs for the web UI and CLI components, minimizing final image size by excluding build-time dependencies.

## Running OmniRoute in Docker

Launch a container with the standard port mappings and persistent storage:

```bash
docker run -d \
  -p 20131:20131 \
  -p 20130:20130 \
  -e DATA_DIR=/data \
  -v omniroute-data:/data \
  --name omniroute \
  omniroute:latest

```

Port `20131` exposes the API endpoint; port `20130` serves the web dashboard. The `DATA_DIR` environment variable ensures data persists across container restarts.

## Docker-Compose Configuration

OmniRoute provides two Compose files for different environments.

### Production Deployment

The [`docker-compose.prod.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.prod.yml) file configures production-ready services:

```yaml
services:
  omniroute:
    image: omniroute:latest
    ports:
      - "${PROD_API_PORT:-20131}:20131"
      - "${PROD_DASHBOARD_PORT:-20130}:20130"
    environment:
      - DATA_DIR=/data
    volumes:
      - omniroute-data:/data
volumes:
  omniroute-data:

```

Deploy with:

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

```

### Development Setup

The standard [`docker-compose.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.yml) includes additional tooling like hot-reload volumes and the optional VNC-Chromium container for browser-automation providers. See [`docker/vnc-browser/README.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docker/vnc-browser/README.md) for configuration details.

## Environment Variables for Docker

The [`docs/reference/ENVIRONMENT.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/ENVIRONMENT.md) file documents Docker-specific variables:

| Variable | Purpose | Default |
|----------|---------|---------|
| `DATA_DIR` | Persistent data mount point | `/data` |
| `PROD_API_PORT` | API service port binding | `20131` |
| `PROD_DASHBOARD_PORT` | Dashboard port binding | `20130` |

These variables are consumed by the container entrypoint and the Next.js runtime configuration.

## Runtime Docker Detection

OmniRoute detects container execution through [`src/lib/zed-oauth/dockerDetect.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/zed-oauth/dockerDetect.ts). The `isRunningInDocker()` function checks for `/.dockerenv` presence and Docker entries in `/proc/1/cgroup`:

```typescript
import { isRunningInDocker } from "./src/lib/zed-oauth/dockerDetect.ts";

if (isRunningInDocker()) {
  console.log("Running inside Docker – enabling Docker‑specific features.");
}

```

This detection enables conditional behavior for:

- **Zed IDE token import**: Adjusted OAuth flow when running containerized
- **MITM stub activation**: Modified certificate handling in Docker networks

Unit tests in [`tests/unit/zed-docker-detect.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/zed-docker-detect.test.ts) verify detection accuracy across Linux cgroup versions.

## Advanced: Self-Hosted Model Runner

OmniRoute integrates with Docker-based AI model runners. Deploy a compatible endpoint:

```bash
docker run -d -p 12434:12434 \
  -e OMNIROUTE_BASE_PATH=/omniroute \
  omniroute-model-runner:latest

```

Then configure the UI to use `http://localhost:12434/v1` as an OpenAI-compatible provider endpoint, documented in [`docs/reference/PROVIDER_REFERENCE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/PROVIDER_REFERENCE.md).

## Key Docker Files Reference

| File Path | Purpose |
|-----------|---------|
| `Dockerfile` | Multi-stage build definition (base → builder → runner) |
| [`docker-compose.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.yml) | Development orchestration with VNC browser |
| [`docker-compose.prod.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.prod.yml) | Production orchestration with env-based ports |
| [`docs/guides/DOCKER_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/DOCKER_GUIDE.md) | Official deployment walkthrough |
| [`src/lib/zed-oauth/dockerDetect.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/zed-oauth/dockerDetect.ts) | Runtime container detection |
| [`docs/reference/ENVIRONMENT.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/ENVIRONMENT.md) | Environment variable reference |
| [`docker/vnc-browser/README.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docker/vnc-browser/README.md) | Browser automation container setup |

## Summary

- **OmniRoute supports Docker** through official multi-stage images, Compose files, and runtime detection
- **Build** with `docker build -t omniroute .` using the root `Dockerfile`
- **Deploy** via [`docker-compose.prod.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.prod.yml) with configurable ports and persistent volumes
- **Configure** using Docker-specific environment variables in [`ENVIRONMENT.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/ENVIRONMENT.md)
- **Detect** container execution at runtime with `isRunningInDocker()` for feature adaptation

## Frequently Asked Questions

### What base image does OmniRoute use?

OmniRoute builds on `node:26-trixie-slim` as specified in the `Dockerfile`. This Debian-based image provides Node.js 26 while keeping the final runtime image minimal through multi-stage builds that discard build dependencies.

### Can I run OmniRoute without Docker-Compose?

Yes. Use `docker run` with the port mappings and volume mounts shown in the examples above. Docker-Compose is recommended for production to handle environment variables and service dependencies more cleanly.

### How does OmniRoute detect it's running in Docker?

The `isRunningInDocker()` function in [`src/lib/zed-oauth/dockerDetect.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/zed-oauth/dockerDetect.ts) checks for `/.dockerenv` file existence and inspects `/proc/1/cgroup` for `docker` or `containerd` entries. This detection activates Docker-specific code paths for authentication and networking features.