# How to Deploy OmniRoute: Complete Deployment Guide for Docker, Fly.io, and Edge Platforms

> Deploy OmniRoute easily using Docker, Fly.io, or edge platforms. Follow our complete guide to configure environment variables and run platform-specific commands for a seamless deployment.

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

---

**Deploy OmniRoute using Docker containers, Fly.io VMs, or serverless edge platforms by configuring environment variables, building from the provided Dockerfile, and running platform-specific deploy commands.**

OmniRoute is a **Next.js 16** application that serves as a unified AI routing proxy. This guide explains how to deploy OmniRoute across multiple hosting environments—from local Docker containers to global edge platforms—based on the official source code in `diegosouzapw/OmniRoute`.

---

## Deployment Architecture Overview

OmniRoute's deployment model centers on **stateless containers** with optional persistent storage for SQLite. The application exposes its API through Next.js server routes under `src/app/api/v1/`, while provider-specific logic runs through the **open-sse** workspace. This architecture makes OmniRoute suitable for containerized deployments where the data directory mounts as a persistent volume.

Key deployment components include:

- **`Dockerfile`** – builds reproducible production images
- **[`docker-compose.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.yml)** – orchestrates multi-service setups
- **[`fly.toml`](https://github.com/diegosouzapw/OmniRoute/blob/main/fly.toml)** – configures Fly.io VM deployments
- **[`wrangler.toml`](https://github.com/diegosouzapw/OmniRoute/blob/main/wrangler.toml)** – enables Cloudflare Workers edge deployment

---

## Method 1: Docker Deployment

Docker is the general-purpose container format used for most OmniRoute deployments. The process is documented in [`docs/ops/DEPLOYMENT_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/DEPLOYMENT_GUIDE.md).

### Build and Run Locally

```bash

# Build the production image

docker build -t omniroute:latest .

# Run with environment configuration

docker run -p 3000:3000 --env-file .env omniroute:latest

```

*Source: Docker build/run commands at [DEPLOYMENT_GUIDE.md#L45-L48](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/DEPLOYMENT_GUIDE.md#L45)*

### Production Docker Setup

For production environments, wrap the container with a process manager like `pm2` or `systemd` to ensure the container stays alive.

### Docker Compose Configuration

Use the provided [`docker-compose.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.yml) for multi-service orchestration:

```yaml
services:
  omniroute:
    image: omniroute:latest
    ports:
      - "3000:3000"
    env_file: .env
    volumes:
      - omniroute-data:/data
volumes:
  omniroute-data:

```

*Source: Compose example at [DEPLOYMENT_GUIDE.md#L112-L114](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/DEPLOYMENT_GUIDE.md#L112)*

---

## Method 2: Fly.io Deployment

Fly.io provides edge-hosted VMs ideal for low-latency AI proxy deployments. The [`fly.toml`](https://github.com/diegosouzapw/OmniRoute/blob/main/fly.toml) configuration file controls app settings, with `app = 'omniroute'` determining which Fly application receives deployments.

### Deploy Steps

```bash

# Install Fly CLI

brew install flyctl

# or

curl -L https://fly.io/install.sh | sh

# Launch new app (creates fly.toml if absent)

flyctl launch --name my-omniroute

# Deploy current codebase

flyctl deploy

```

*Source: Fly.io workflow at [FLY_IO_DEPLOYMENT_GUIDE.md#L9-L13](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md#L9) and app configuration at [FLY_IO_DEPLOYMENT_GUIDE.md#L56](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md#L56)*

### Docker-to-Fly Workflow

For custom images, push to Fly's registry first:

```bash
docker build -t omniroute:latest .
docker tag omniroute:latest registry.fly.io/my-omniroute:latest
docker push registry.fly.io/my-omniroute:latest
flyctl deploy --image registry.fly.io/my-omniroute:latest

```

---

## Method 3: Cloudflare Workers (Wrangler)

Deploy OmniRoute's Bifrost sidecar to Cloudflare's edge network for serverless execution.

```bash
npx wrangler deploy

```

*Source: Wrangler deploy command at [VM_DEPLOYMENT_GUIDE.md#L410](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/VM_DEPLOYMENT_GUIDE.md#L410)*

The [`wrangler.toml`](https://github.com/diegosouzapw/OmniRoute/blob/main/wrangler.toml) file configures worker routes, environment variables, and KV namespaces for edge caching.

---

## Method 4: Vercel Deployment

OmniRoute builds natively on Vercel with zero configuration for standard Next.js apps.

```bash

# Install Vercel CLI

npm i -g vercel

# Link and deploy

vercel --prod

```

Vercel automatically detects [`next.config.js`](https://github.com/diegosouzapw/OmniRoute/blob/main/next.config.js) and runs `npm run build`, serving output from the `.next/` directory.

*Source: Vercel environment configuration referenced at [ENVIRONMENT.md#L1038](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/ENVIRONMENT.md#L1038)*

---

## Essential Environment Variables

Configure these variables before deployment:

| Variable | Purpose | Example |
|----------|---------|---------|
| `NEXT_PUBLIC_BASE_URL` | Public hostname for OAuth callbacks and generated links | `https://omniroute.example.com` |
| `OMNIROUTE_BASE_PATH` | Sub-path hosting (optional) | `/omniroute` |
| `CORS_ALLOWED_ORIGINS` | Browser API access control | `https://app.example.com,https://admin.example.com` |
| `OMNIROUTE_LOCAL_ENDPOINTS_ENABLED` | Toggle internal `/api/local/*` routes | `0` (production), `1` (development) |
| `OMNIROUTE_NO_SUDO` | Root-less container compatibility | `1` |
| `BIFROST_ENABLED` | High-throughput sidecar activation | `1` |

*Source: Complete environment reference at [ENVIRONMENT.md#L46-L299](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/ENVIRONMENT.md#L46)*

---

## Complete Deployment Example: Docker + Fly.io

```bash

# Build production image

docker build -t omniroute:latest .

# Create Fly.io application

flyctl launch --name my-omniroute --copy-config

# Push to Fly registry

docker tag omniroute:latest registry.fly.io/my-omniroute:latest
docker push registry.fly.io/my-omniroute:latest

# Deploy with custom image

flyctl deploy --image registry.fly.io/my-omniroute:latest

# Configure secrets

flyctl secrets set \
  NEXT_PUBLIC_BASE_URL=https://omniroute.example.com \
  OMNIROUTE_BASE_PATH=/omniroute \
  CORS_ALLOWED_ORIGINS=https://myclient.com \
  BIFROST_ENABLED=1

```

Verify deployment by requesting the models endpoint:

```bash
curl https://omniroute.example.com/api/v1/models

```

---

## Key Deployment Files

| File | Location | Purpose |
|------|----------|---------|
| `Dockerfile` | [Repository root](https://github.com/diegosouzapw/OmniRoute/blob/main/Dockerfile) | Production container image definition |
| `Dockerfile.dev` | [Repository root](https://github.com/diegosouzapw/OmniRoute/blob/main/Dockerfile.dev) | Development container with hot reload |
| [`docker-compose.yml`](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.yml) | [Repository root](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.yml) | Multi-service orchestration template |
| [`fly.toml`](https://github.com/diegosouzapw/OmniRoute/blob/main/fly.toml) | [Repository root](https://github.com/diegosouzapw/OmniRoute/blob/main/fly.toml) | Fly.io VM configuration |
| [`wrangler.toml`](https://github.com/diegosouzapw/OmniRoute/blob/main/wrangler.toml) | [Repository root](https://github.com/diegosouzapw/OmniRoute/blob/main/wrangler.toml) | Cloudflare Workers deployment config |
| [`docs/ops/DEPLOYMENT_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/DEPLOYMENT_GUIDE.md) | [docs/ops/](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/DEPLOYMENT_GUIDE.md) | Primary Docker deployment documentation |
| [`docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) | [docs/ops/](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) | Fly.io-specific deployment steps |
| [`docs/ops/VM_DEPLOYMENT_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/VM_DEPLOYMENT_GUIDE.md) | [docs/ops/](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/VM_DEPLOYMENT_GUIDE.md) | VM and Wrangler deployment instructions |
| [`docs/reference/ENVIRONMENT.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/ENVIRONMENT.md) | [docs/reference/](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/ENVIRONMENT.md) | Complete environment variable reference |
| [`src/app/api/v1/relay/chat/completions/bifrost/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/relay/chat/completions/bifrost/route.ts) | [src/app/api/v1/relay/chat/completions/bifrost/](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/relay/chat/completions/bifrost/route.ts) | Bifrost high-throughput entry point |
| [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts) | [src/lib/db/](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts) | SQLite database initialization and `DATA_DIR` handling |

---

## Summary

- **Docker** provides the most flexible deployment path—build once, run anywhere with `docker build` and `docker run`
- **Fly.io** offers managed edge VMs with `flyctl deploy` and configuration through [`fly.toml`](https://github.com/diegosouzapw/OmniRoute/blob/main/fly.toml)
- **Cloudflare Workers** enable serverless edge deployment via `npx wrangler deploy`
- **Vercel** delivers zero-config Next.js hosting with automatic builds
- Always configure `NEXT_PUBLIC_BASE_URL` and `CORS_ALLOWED_ORIGINS` before deploying to production
- Mount persistent volumes for SQLite data in containerized environments

---

## Frequently Asked Questions

### What is the minimum infrastructure needed to run OmniRoute in production?

OmniRoute requires a container runtime (Docker) or Node.js 22+ environment with at least 512MB RAM and persistent storage for the SQLite database file. For high-traffic deployments, enable the Bifrost sidecar and allocate 1GB+ RAM with CPU scaling.

### How do I configure OmniRoute when hosting behind a reverse proxy?

Set `NEXT_PUBLIC_BASE_URL` to your public HTTPS endpoint and `OMNIROUTE_BASE_PATH` to any sub-path prefix. These variables ensure OAuth callbacks, generated links, and CORS headers reference the correct external addresses rather than internal container hostnames.

### Can I deploy OmniRoute without Docker?

Yes—OmniRoute runs as a standard Next.js application. Install dependencies with `npm ci`, build with `npm run build`, and start with `npm start`. However, Docker is recommended for production to ensure consistent environments and simplify rollbacks across deployment targets.