OmniRoute/docs/DOCKER_GUIDE.md

🐳 Docker Guide — OmniRoute

Complete Docker deployment reference. For a quick start, see the README Docker section.

Table of Contents

• Quick Run
• With Environment File
• Docker Compose
• Docker Compose with Caddy (HTTPS)
• Cloudflare Quick Tunnel
• Image Tags
• Important Notes

---

Quick Run

docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --stop-timeout 40 \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

With Environment File

# Copy and edit .env first
cp .env.example .env

docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --stop-timeout 40 \
  --env-file .env \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

Docker Compose

# Base profile (no CLI tools)
docker compose --profile base up -d

# CLI profile (Claude Code, Codex, OpenClaw built-in)
docker compose --profile cli up -d

Docker Compose with Caddy (HTTPS Auto-TLS)

OmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.

services:
  omniroute:
    image: diegosouzapw/omniroute:latest
    container_name: omniroute
    restart: unless-stopped
    volumes:
      - omniroute-data:/app/data
    environment:
      - PORT=20128
      - NEXT_PUBLIC_BASE_URL=https://your-domain.com

  caddy:
    image: caddy:latest
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128

volumes:
  omniroute-data:

Cloudflare Quick Tunnel

Dashboard support for Docker deployments includes a one-click Cloudflare Quick Tunnel on Dashboard → Endpoints. The first enable downloads cloudflared only when needed, starts a temporary tunnel to your current /v1 endpoint, and shows the generated https://*.trycloudflare.com/v1 URL directly below your normal public URL.

Endpoint tunnel panels (Cloudflare, Tailscale, ngrok) can be shown or hidden from Settings → Appearance without changing active tunnel state.

Tunnel Notes

• Quick Tunnel URLs are temporary and change after every restart.
• Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.
• Managed install currently supports Linux, macOS, and Windows on x64 / arm64.
• Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set CLOUDFLARED_PROTOCOL=quic or auto if you want a different transport.
• Docker images bundle system CA roots and pass them to managed cloudflared, which avoids TLS trust failures when the tunnel bootstraps inside the container.
• Set CLOUDFLARED_BIN=/absolute/path/to/cloudflared if you want OmniRoute to use an existing binary instead of downloading one.

Image Tags

Image	Tag	Size	Description
diegosouzapw/omniroute	latest	~250MB	Latest stable release
diegosouzapw/omniroute	3.7.8	~250MB	Current version

Multi-platform: AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi).

Important Notes

• SQLite WAL Mode: docker stop should be allowed to finish so OmniRoute can checkpoint the latest changes back into storage.sqlite. The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep --stop-timeout 40.
• DISABLE_SQLITE_AUTO_BACKUP: Set to true if backups are managed externally.
• Data Persistence: Always mount a volume to /app/data to persist your database, keys, and configurations across container restarts.
• Port Configuration: Override PORT environment variable to change the default 20128 port.

See Also

• VM Deployment Guide — VM + nginx + Cloudflare setup
• Fly.io Deployment Guide — Deploy to Fly.io
• Environment Config — Complete .env reference