How to Deploy an Application Using OmniRoute: Complete Guide for Docker, Fly.io, and Edge Platforms

Deploy an OmniRoute application by containerizing it with Docker, pushing to Fly.io's edge network, or using serverless platforms like Cloudflare Workers and Vercel, while configuring essential environment variables such as NEXT_PUBLIC_BASE_URL and OMNIROUTE_BASE_PATH.

OmniRoute is a Next.js 16 application that functions as a unified AI routing proxy, designed to run as a stateless container or serverless function. Whether you are deploying to a self-hosted Docker environment, Fly.io's edge VMs, or Vercel's serverless platform, the deployment process relies on standard containerization patterns and environment-specific configuration files. This guide walks through the deployment architecture and provides runnable commands for each platform.

Docker Deployment

Docker is the general-purpose container format used for most OmniRoute deployments, offering a reproducible environment across development and production.

Building the Container Image

The Dockerfile at the repository root defines the production image using Node.js 22. Build the image with a specific tag for version control:

docker build -t omniroute:latest .

This command creates a container image that includes the built Next.js application and all runtime dependencies. The build process is documented in the deployment guide at lines 45-48 of [docs/ops/DEPLOYMENT_GUIDE.md](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/DEPLOYMENT_GUIDE.md#L45).

Running the Container Locally

To run OmniRoute locally with environment variables and port mapping:

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

This exposes the application on port 3000 and injects configuration from your .env file. For production deployments, you typically use a process manager like pm2 or systemd to keep the container alive and restart it on failure.

Docker Compose Setup

For multi-service deployments or persistent SQLite storage, use the provided [docker-compose.yml](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.yml). The configuration mounts a volume for the database directory:

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

This compose snippet appears at lines 112-114 of [docs/ops/DEPLOYMENT_GUIDE.md](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/DEPLOYMENT_GUIDE.md#L112), enabling persistent storage for the SQLite database while keeping the application container stateless.

Fly.io Deployment

Fly.io hosts OmniRoute as an edge-deployed VM, providing global distribution and automatic HTTPS.

Launching and Deploying

First, install the Fly CLI (brew install flyctl), then create and deploy your application:

# Create the app (if not already exists)

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

# Deploy the current build

flyctl deploy

The fly.toml configuration file in the repository root defines the application settings, where app = 'omniroute' determines which Fly application receives the deployment. This workflow is documented at lines 9-13 and line 56 of [docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md#L9).

Production Considerations on Fly.io

When deploying to Fly.io, set your environment variables using secrets:

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

The SQLite database should be mounted on a persistent Fly Volume, configured in fly.toml, to ensure data persists across deployments.

Cloudflare Workers Deployment

For serverless edge deployment, OmniRoute supports Cloudflare Workers via Wrangler.

Deploying with Wrangler

Use the npx wrangler deploy command to push your application to Cloudflare's edge network:

npx wrangler deploy

This command is referenced at line 410 of [docs/ops/VM_DEPLOYMENT_GUIDE.md](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 contains the Workers configuration, including routes and environment settings for the Bifrost sidecar.

Vercel Deployment

OmniRoute ships with Vercel-ready configuration. After linking your repository to a Vercel project, the platform automatically runs npm run build and serves the output from the dist/ directory.

Environment Configuration for Vercel

Configure the VERCEL_API_BASE environment variable and other settings in the Vercel dashboard or via CLI. The specific variable VERCEL_API_BASE is documented at line 1038 of [docs/reference/ENVIRONMENT.md](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/ENVIRONMENT.md#L1038).

Essential Environment Configuration

OmniRoute requires specific environment variables to function correctly across deployment targets. These are defined in [docs/reference/ENVIRONMENT.md](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/ENVIRONMENT.md) at lines 46-299.

Critical variables include:

• NEXT_PUBLIC_BASE_URL – Required when OmniRoute sits behind a reverse proxy, ensuring OAuth callbacks and generated links use the public hostname
• OMNIROUTE_BASE_PATH – Enables hosting under a sub-path (e.g., /omniroute)
• CORS_ALLOWED_ORIGINS – Comma-separated list of allowed origins for browser-based API access
• OMNIROUTE_NO_SUDO – Set to 1 for root-less Docker containers to strip sudo from MITM certificate commands
• BIFROST_ENABLED – Controls the high-throughput Bifrost sidecar; can be toggled without redeployment

Key Source Files Reference

Understanding these core files helps troubleshoot deployment issues:

• Dockerfile – Defines the production container image with Node.js 22 and Next.js build steps
• [docker-compose.yml](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.yml) – Orchestrates the container with persistent volume mounting for SQLite
• [fly.toml](https://github.com/diegosouzapw/OmniRoute/blob/main/fly.toml) – Fly.io VM configuration specifying regions, volumes, and environment variables
• [wrangler.toml](https://github.com/diegosouzapw/OmniRoute/blob/main/wrangler.toml) – Cloudflare Workers configuration for serverless edge deployment
• [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) – Entry point for the Bifrost sidecar used in high-throughput deployments
• [src/lib/db/core.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts) – SQLite database initialization showing the DATA_DIR configuration for persistent storage

Summary

• Containerize first – Use the provided Dockerfile to build a reproducible image for any platform
• Choose your platform – Fly.io for edge VMs, Cloudflare Workers for serverless, Vercel for traditional serverless hosting, or Docker Compose for self-hosted infrastructure
• Configure environment variables – Set NEXT_PUBLIC_BASE_URL, OMNIROUTE_BASE_PATH, and CORS_ALLOWED_ORIGINS before deploying
• Persist data correctly – Mount volumes for SQLite in Docker and Fly.io; use external databases for clustered deployments
• Leverage Bifrost – Enable BIFROST_ENABLED for high-throughput routing without code changes

Frequently Asked Questions

How do I deploy OmniRoute to Fly.io for the first time?

Install the Fly CLI with brew install flyctl, run flyctl launch in your repository root to create the application, and then execute flyctl deploy to push your container. The fly.toml file in the repository configures the app name and regions automatically.

Can I run OmniRoute without Docker?

Yes, you can run OmniRoute directly with Node.js using npm run build followed by npm start, but Docker is recommended for production consistency. For serverless platforms like Vercel or Cloudflare Workers, the build process is handled by the platform's native build system.

What environment variables are required for a reverse proxy setup?

You must set NEXT_PUBLIC_BASE_URL to your public-facing URL (e.g., https://omniroute.example.com) and optionally OMNIROUTE_BASE_PATH if hosting under a sub-path. Additionally, configure CORS_ALLOWED_ORIGINS to allow browser requests from your client domains.

How do I enable the Bifrost sidecar for high-throughput deployments?

Set the environment variable BIFROST_ENABLED=1 in your deployment platform. The Bifrost routes are defined in [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) and can be toggled on or off without redeploying the application.

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