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

> Easily run OmniRoute in Docker on AMD64 and ARM64 with the multi-arch image from diegosouzapw. Get seamless cross-platform deployment without extra flags.

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

---

**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.

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

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

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

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

```

Then build and push the multi-platform image:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.prod.yml) file. This configuration includes the OmniRoute service and an optional Redis container for rate-limiting and API-key caching.

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

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

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.