# Deployment Strategy for OmniRoute: Multi-Environment Build and Release > Discover OmniRoute's deployment strategy: build once, deploy anywhere. Learn how to deploy to VMs, Docker, Fly.io, or VPS using environment variables and Bifrost. - Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute) - Tags: deployment-strategy - Published: 2026-07-15 --- **OmniRoute follows a build-once-deploy-anywhere model where `npm run build` generates a static distribution bundle, enabling deployment to VMs, Docker containers, Fly.io, or VPS hosts via environment-variable configuration and optional Bifrost sidecars.** The `diegosouzapw/OmniRoute` repository implements a portable deployment pipeline designed for maximum flexibility. The strategy compiles both the Next.js application and CLI tooling into a single `dist/` directory, allowing operators to promote identical artifacts across development, staging, and production environments without recompiling. ## Build Stage: Creating the Production Bundle The deployment process begins with two npm commands. First, `npm run build` executes the Next.js production build, outputting optimized assets to `.build/next/`. Second, `npm run build:cli` bundles the command-line interface binary. These artifacts are consolidated into the `dist/` directory, and the system writes a **BUILD_SHA** file containing the current git commit hash to `dist/BUILD_SHA` for version traceability. According to [`docs/ops/RELEASE_CHECKLIST.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/RELEASE_CHECKLIST.md), this build phase must complete successfully before any deployment target is considered valid. ## Deployment Targets: Four Proven Methods OmniRoute supports four primary deployment patterns, each managed through specific configuration files and automation scripts in the repository. ### Virtual Machines and Bare-Metal Servers For VM deployments, operators copy the entire `dist/` folder to the target host and execute `node .` to start the server. The [`docs/ops/VM_DEPLOYMENT_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/VM_DEPLOYMENT_GUIDE.md) provides step-by-step instructions for manual installation on Linux-based virtual machines. ### Docker Containers The repository ships with a `Dockerfile` that copies the `dist/` directory into a container image and configures the entrypoint to start the Node.js server. This image can be published to any container registry and deployed to Kubernetes, AWS ECS, or other container platforms. ### Fly.io Platform Fly.io deployments utilize the [`fly.toml`](https://github.com/diegosouzapw/OmniRoute/blob/main/fly.toml) file to define the application configuration, persistent volumes, and environment variables. The command `flyctl deploy` uploads the pre-built image to Fly’s platform. Detailed instructions are available in [`docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md). ### VPS and Custom Scripts The `skills/` directory contains automated deployment scripts (e.g., `deploy-vps-local-cc`) that leverage rsync to transfer the `dist/` directory to remote servers and restart systemd services automatically. ```bash # Build the application npm run build npm run build:cli # Deploy to Fly.io flyctl deploy # Or deploy to VPS using built-in skills omniroute skill run /deploy-vps-local-cc ``` ## Runtime Configuration via Environment Variables All deployment targets rely exclusively on environment variables for runtime configuration, eliminating environment-specific rebuilds. Critical variables include `NEXT_PUBLIC_BASE_URL`, `CORS_ALLOWED_ORIGINS`, and `BIFROST_ENABLED`. The [`docs/reference/ENVIRONMENT.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/ENVIRONMENT.md) file provides a comprehensive reference of every configurable option and its default source file. ## Optional High-Throughput Sidecars For high-throughput production scenarios, OmniRoute supports an optional **Bifrost** Go sidecar. When `BIFROST_ENABLED` is set to `1`, the routing logic 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) proxies traffic to the Bifrost service instead of handling requests directly within the Node.js process. ```bash # Enable Bifrost sidecar docker run -d -p 3000:3000 \ -e NEXT_PUBLIC_BASE_URL=https://api.example.com \ -e BIFROST_ENABLED=1 \ omniroute:latest ``` ## Post-Deploy Validation and Verification After deployment, the release checklist executes smoke tests against the live endpoint. The validation process verifies that `dist/BUILD_SHA` matches the current git SHA and confirms that database migrations have applied successfully via [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrationRunner.ts). ## Data Persistence and Scaling Considerations Single-instance deployments use **SQLite** by default, with the database connection managed in [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts). For multi-replica deployments, operators must configure external databases or Redis to share quota counters and cache state, as detailed in [`docs/routing/QUOTA_SHARE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/routing/QUOTA_SHARE.md). ```bash # Start on bare metal with SQLite export NEXT_PUBLIC_BASE_URL=http://localhost:3000 node . ``` ## Summary - **Build once**: `npm run build` and `npm run build:cli` generate a portable `dist/` bundle. - **Deploy anywhere**: Choose from VMs, Docker, Fly.io, or VPS scripts in `skills/`. - **Configure via env vars**: Control all behavior through variables documented in [`docs/reference/ENVIRONMENT.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/ENVIRONMENT.md). - **Validate rigorously**: Verify `BUILD_SHA` and database migrations post-deployment via [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrationRunner.ts). - **Scale sidecars**: Enable Bifrost for high throughput; use external databases for multi-replica persistence. ## Frequently Asked Questions ### What is the minimum deployment requirement for OmniRoute? Any environment capable of running Node.js and hosting the `dist/` directory is sufficient. The simplest method involves copying the build folder to a virtual machine and executing `node .` to start the server, as documented in [`docs/ops/VM_DEPLOYMENT_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/VM_DEPLOYMENT_GUIDE.md). ### How does OmniRoute handle database migrations during deployment? The [`docs/ops/RELEASE_CHECKLIST.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/RELEASE_CHECKLIST.md) mandates that post-deploy validation runs database migrations via [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrationRunner.ts) and confirms their successful completion before considering the release valid. ### Can I deploy OmniRoute to Fly.io without managing Dockerfiles manually? Yes. The repository includes a [`fly.toml`](https://github.com/diegosouzapw/OmniRoute/blob/main/fly.toml) configuration file, and the command `flyctl deploy` handles containerization automatically. You do not need to manually edit Dockerfiles to deploy to Fly.io. ### What is the purpose of the BUILD_SHA file in the dist directory? The `BUILD_SHA` file stores the git commit hash captured at build time. During post-deploy validation, the system checks this value to ensure the running code matches the intended release version, preventing configuration drift.