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

> Deploy your application with OmniRoute on Docker, Fly.io, or edge platforms. Master containerization, environment variables, and serverless deployments for seamless integration.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/Dockerfile) at the repository root defines the production image using Node.js 22. Build the image with a specific tag for version control:

```bash
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)](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:

```bash
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)](https://github.com/diegosouzapw/OmniRoute/blob/main/docker-compose.yml). The configuration mounts a volume for the database directory:

```yaml
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)](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:

```bash

# Create the app (if not already exists)

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

# Deploy the current build

flyctl deploy

```

The [`fly.toml`](https://github.com/diegosouzapw/OmniRoute/blob/main/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)](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:

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

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