How to Run OmniRoute in Docker with Multi-Arch Support (AMD64 + ARM64)

OmniRoute provides a multi-architecture Docker image that automatically runs on both AMD64 and ARM64 hosts without requiring platform-specific flags or separate tags.

The diegosouzapw/OmniRoute repository ships a production-ready container image supporting x86_64 and arm64 architectures through a single manifest. This guide explains how to run OmniRoute in Docker with multi-arch support using the pre-built image, custom Buildx builds, and production Compose deployments.

Pull the Pre-Built Multi-Arch Image

OmniRoute publishes a multi-arch manifest to Docker Hub under diegosouzapw/omniroute:latest. Docker automatically resolves the correct variant for your host CPU when pulling the image.

docker pull diegosouzapw/omniroute:latest

This single command retrieves the appropriate image layer for Intel/AMD (linux/amd64) or Apple Silicon/ARM (linux/arm64) machines. No --platform flags or architecture-specific tags are required.

Run the Container

The container supports two runtime modes selected automatically by the entrypoint script defined in the Dockerfile. Set environment variables via --env-file ./.env (using the provided /.env.example as a template) and persist data with the named volume omniroute-data:/app/data.

CLI-Only Mode (Port 20128)

Run the API-only version for backend routing services:

docker run -d \
  --name omniroute \
  -p 20128:20128 \
  --env-file ./.env \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

Dashboard + API Mode (Ports 20130/20131)

Run the full stack including the web dashboard:

docker run -d \
  --name omniroute \
  -p 20130:20130 \
  -p 20131:20131 \
  --env-file ./.env \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

The runner-web stage in the Dockerfile exposes the dashboard on port 20130 and API on 20131, while runner-cli exposes only the API on 20128.

Build a Local Multi-Arch Image (Optional)

To customize the image with additional dependencies, use Docker Buildx to compile for both architectures simultaneously. The Dockerfile implements a multi-stage build process (base, builder, runner-*) that separates compilation from the final runtime image.

First, create a Buildx builder instance:

docker buildx create --use --name omni-builder

Then build and push the multi-platform image:

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t your-registry/omniroute:custom \
  --push \
  .

The builder stage executes npm ci and npm run build, while the final stage copies only compiled assets and the /docs directory (re-included in recent updates to the Dockerfile) to minimize image size.

Deploy with Docker Compose

For production environments, use the provided docker-compose.prod.yml file. This configuration includes the OmniRoute service and an optional Redis container for rate-limiting and API-key caching.

version: "3.9"

services:
  omniroute:
    image: diegosouzapw/omniroute:latest
    restart: unless-stopped
    ports:
      - "20130:20130"
      - "20131:20131"
    env_file: .env
    volumes:
      - omniroute-data:/app/data

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    ports:
      - "6379:6379"

volumes:
  omniroute-data:

Deploy the stack:

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

Compose automatically selects the correct platform image for each service, enabling identical deployments across AMD64 servers and ARM64 development machines.

Verify the Platform Architecture

Confirm the running container matches your host architecture:

docker exec omniroute uname -m

Expect x86_64 for AMD64 hosts or aarch64 for ARM64 hosts.

Troubleshooting Common Issues

• ENOENT: …/docs/... errors: The /docs directory must exist in the runtime image. Recent updates to the Dockerfile ensure this directory is copied from the build context. If you encounter this error, pull the latest image or verify your local build uses the updated Dockerfile and that .dockerignore does not exclude required documentation files.

• Permission denied on /app/data: Ensure you use a Docker named volume (e.g., omniroute-data:/app/data) rather than a bind-mount with read-only host permissions. The container requires write access to persist SQLite databases and cache files.

• Redis connection failures: If REDIS_URL is undefined, OmniRoute falls back to an in-memory store. To use external Redis, set REDIS_URL in your .env file according to the schema documented in docs/reference/ENVIRONMENT.md.

Summary

• OmniRoute distributes a multi-arch manifest supporting both AMD64 and ARM64 under the single tag diegosouzapw/omniroute:latest.
• The Dockerfile uses multi-stage builds (base, builder, runner-web/runner-cli) to optimize image size and automatically select the runtime mode.
• Exposed ports vary by mode: 20128 for CLI-only, 20130/20131 for Dashboard+API.
• Use Docker Buildx with --platform linux/amd64,linux/arm64 to build custom images for both architectures.
• The docker-compose.prod.yml file provides a production-ready template that works identically on x86_64 servers and Apple Silicon laptops.

Frequently Asked Questions

Does OmniRoute support ARM64/Apple Silicon native execution?

Yes. The official image includes ARM64 variants that run natively on Apple Silicon and ARM-based servers. Docker automatically pulls the correct architecture when you run docker pull diegosouzapw/omniroute:latest, eliminating the need for Rosetta emulation or platform-specific tags.

How do I build custom OmniRoute images for multiple architectures?

Use Docker Buildx to create cross-platform builds. Create a builder with docker buildx create --use, then run docker buildx build --platform linux/amd64,linux/arm64. The repository's Dockerfile is optimized for multi-arch builds with separate stages for compilation and runtime.

What ports should I expose when running OmniRoute in Docker?

Expose port 20128 for the CLI/API-only mode, or ports 20130 and 20131 for the Dashboard+API mode. Port 20130 serves the web dashboard, while 20131 handles API requests. These mappings are defined in the container's runtime stages within the Dockerfile.

Why does my container exit with a /docs directory error?

Earlier builds occasionally excluded the /docs directory due to .dockerignore settings. The current Dockerfile explicitly copies /docs into the final image. Resolve this by pulling the latest diegosouzapw/omniroute:latest image or rebuilding from the current Dockerfile in the repository root.

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