Fly.io Microservices Deployment Guide¶

BPEVeriFlow is designed as a monolithic Next.js frontend that interacts with a mesh of mocked internal microservices. For a production-ready demonstration, you can deploy the entire architecture onto Fly.io using their global private network (6PN), enabling sub-50ms internal service-to-service communication.

Architecture Overview¶

The system consists of 5 logical deployment units:

Unit	Fly App Name	Port	Visibility
Next.js Frontend	`bpe-veriflow-web`	3000	🌐 Public
API Gateway	`bpe-api-gateway`	4000	🔒 Private (6PN)
Identity Registry	`bpe-identity-registry`	4001	🔒 Private (6PN)
Verify AI Engine	`bpe-verify-ai`	4002	🔒 Private (6PN)
Exception Ticketing	`bpe-exception-ticketing`	4003	🔒 Private (6PN)

Current Prototype

In the current prototype, all microservices are mocked within the Next.js React context. To deploy a true microservices mesh, extract the mock logic into separate Express.js or Go services, then deploy each using the steps below.

Pre-Deployment Checklist¶

Complete Before Any fly deploy Command

[ ] flyctl CLI is installed and you are logged in (fly auth login)
[ ] Each service has a production .env with real secrets (no placeholders)
[ ] JWT_SECRET is a cryptographically random 256-bit key — not the demo value
[ ] DATABASE_URL points to your NeonDB production cluster with sslmode=require
[ ] All microservices are compiled and tested locally with npm run build
[ ] The Next.js app builds without errors: npm run build

1. Prerequisites¶

macOS (Homebrew)Linux / WSL

brew install flyctl
fly auth login

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

2. Deploying the Next.js Frontend¶

Step 1 — Launch¶

Navigate to the project root and initialise the Fly app without deploying immediately:

fly launch --no-deploy --name bpe-veriflow-web

Region: Choose ams (Amsterdam) or lhr (London) for lowest latency to Nigerian users.

Best Region for Nigeria

Fly.io's ams (Amsterdam) region consistently delivers the best round-trip times to Lagos and Abuja — typically 80–120ms — compared to 180–220ms for iad (Virginia). Use ams as your primary_region.

Step 2 — Configure `fly.toml`¶

app = "bpe-veriflow-web"
primary_region = "ams"

[build]
  builder = "paketobuildpacks/builder:base"
  buildpacks = ["gcr.io/paketo-buildpacks/nodejs"]

[env]
  NODE_ENV = "production"
  NEXT_PUBLIC_API_GATEWAY_URL = "http://bpe-api-gateway.flycast"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = false  # (1)!
  auto_start_machines = true
  min_machines_running = 1    # (2)!

Keep auto_stop_machines = false for demos — prevents cold starts that break live walkthroughs.
min_machines_running = 1 ensures at least one instance is always ready to serve traffic.

Step 3 — Set Secrets & Deploy¶

fly secrets set JWT_SECRET="your_secure_random_key"
fly secrets set DATABASE_URL="postgresql://..."
fly deploy

3. Deploying the Microservices Mesh¶

Each internal service is deployed on Fly's private 6PN network — inaccessible from the public internet, only reachable by the Next.js frontend.

Example: Deploying the AI Engine (`bpe-verify-ai`)¶

cd ../bpe-verify-ai
fly launch --no-deploy --name bpe-verify-ai

Configure fly.toml for private networking:

app = "bpe-verify-ai"
primary_region = "ams"

[build]
  # Add your build config here

[http_service]
  internal_port = 4002
  # No [[services]] block with public IPs — this keeps the
  # service strictly on the private Fly 6PN mesh.

Allocate a private IPv6 Flycast address and deploy:

fly ips allocate-v6 --private
fly deploy

Repeat this process for bpe-identity-registry and bpe-exception-ticketing.

4. Scaling Under Load¶

To horizontally scale the AI Verify service during high-traffic periods (e.g., concession bid submission deadlines):

fly scale count 3 --app bpe-verify-ai

Or configure auto-scaling in fly.toml:

[http_service]
  [[http_service.concurrency]]
    type = "requests"
    soft_limit = 200
    hard_limit = 400

This distributes Desk evaluation query loads evenly across all running machines.

5. Securing the Deployment¶

Critical Security Requirements

BPEVeriFlow handles highly sensitive federal concession data. Failure to follow these steps may expose PII and audit records.

Secrets Management: Never commit credentials. Use Fly secrets exclusively:

fly secrets set POSTGRES_URL="postgres://..."
fly secrets set JWT_SECRET="..."

Private Networking: Ensure only bpe-veriflow-web has a public IPv4/IPv6 address. All other microservices must communicate exclusively via *.flycast internal addresses.
Health Monitoring: Set up Fly health checks to alert on service degradation:
```
fly checks list --app bpe-api-gateway
```
Certificate Renewal: Fly automatically renews TLS certificates for public-facing apps. Verify certificate status with:
```
fly certs list --app bpe-veriflow-web
```