Deployment Strategy for OmniRoute: Multi-Environment Build and Release

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

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.

# 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 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 proxies traffic to the Bifrost service instead of handling requests directly within the Node.js process.

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

Data Persistence and Scaling Considerations

Single-instance deployments use SQLite by default, with the database connection managed in 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.

# 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.
• Validate rigorously: Verify BUILD_SHA and database migrations post-deployment via 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.

How does OmniRoute handle database migrations during deployment?

The docs/ops/RELEASE_CHECKLIST.md mandates that post-deploy validation runs database migrations via 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 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.

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