Fly.io

Overview

Fly.io deploys applications to Firecracker microVMs across 30+ edge regions worldwide, providing sub-50ms latency to users. It supports scale-to-zero machines, persistent NVMe volumes, LiteFS for multi-region SQLite replication, and private WireGuard networking between services.

Instructions

• When deploying applications, use

  fly launch

  to auto-detect the framework and generate a Dockerfile, then

  fly deploy

  for zero-downtime rolling updates with health checks.
• When configuring scaling, use

  auto_stop_machines

  and

  auto_start_machines

  in

  fly.toml

  to scale to zero when idle and wake on incoming requests, and set machine sizing appropriate to the workload.
• When managing multi-region deployments, use

  fly scale count --region

  to distribute machines,

  fly-replay

  header to route writes to the primary region, and LiteFS for SQLite read replicas.
• When handling persistent data, attach volumes for durable storage (machines are ephemeral), use LiteFS for multi-region SQLite, or Tigris for S3-compatible object storage.
• When connecting services, use

  .internal

  DNS for private service-to-service communication over the WireGuard mesh and never expose internal services to the public internet.
• When managing secrets, use

  fly secrets set KEY=value

  for encrypted secret storage accessible as environment variables.
• When troubleshooting, use

  fly logs

  for real-time streaming,

  fly ssh console

  to access running machines, and

  fly proxy

  to tunnel to internal services.

Examples

Example 1: Deploy a multi-region web application

User request: "Deploy my app globally with Fly.io in US, Europe, and Asia"

Actions:

1. Initialize with

   fly launch

   and configure Dockerfile
2. Deploy machines to three regions:

   fly scale count 2 --region iad,cdg,nrt

3. Set up LiteFS for SQLite replication across regions
4. Configure

   fly-replay

   header for write routing to the primary region

Output: A globally distributed app with read replicas in three regions and automatic write routing.

Example 2: Configure a cost-efficient staging environment

User request: "Set up a Fly.io staging environment that scales to zero when not in use"

Actions:

1. Create a staging app with

   fly launch

2. Configure

   auto_stop_machines = "stop"

   and

   auto_start_machines = true

   in

   fly.toml

3. Attach a volume for persistent database storage
4. Set health checks with appropriate timeouts for routing

Output: A staging environment that stops idle machines and wakes in sub-second on the next request.

Example 3: Canary deployment with auto-rollback

User request: "Deploy my app to Fly.io but test on one machine first. If the health check fails, roll back."

Actions:

1. Deploy with

   --strategy canary

   to spin up a single new machine
2. Health check the canary machine at the app's health endpoint
3. If healthy, promote with

   fly deploy --strategy rolling

   to replace all machines
4. If unhealthy, rollback with

   fly releases rollback

#!/bin/bash
# deploy-canary.sh — Fly.io canary deployment with auto-rollback
set -euo pipefail

APP="${1:?Usage: deploy-canary.sh <app-name>}"
HEALTH_PATH="${2:-/api/health}"

echo "🐤 Deploying canary..."
fly deploy --app "$APP" --strategy canary --wait-timeout 120

HEALTH_URL="https://${APP}.fly.dev${HEALTH_PATH}"
HEALTHY=false
DEADLINE=$((SECONDS + 60))

while [ $SECONDS -lt $DEADLINE ]; do
  STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$HEALTH_URL" || true)
  [ "$STATUS" = "200" ] && HEALTHY=true && break
  sleep 3
done

if [ "$HEALTHY" = true ]; then
  echo "✅ Canary healthy! Promoting..."
  fly deploy --app "$APP" --strategy rolling
  echo "🎉 Production deploy complete"
else
  echo "❌ Canary failed! Rolling back..."
  fly releases rollback --app "$APP"
  echo "⏪ Rolled back"
  exit 1
fi

Guidelines

• Use

  auto_stop_machines = "stop"

  for dev/staging to save costs; machines stop after idle timeout.
• Keep

  auto_start_machines = true

  so machines wake on incoming requests with sub-second cold start.
• Use

  .internal

  DNS for service-to-service calls; never expose internal services publicly.
• Store persistent data on volumes, not the machine filesystem, since machines are ephemeral.
• Use LiteFS for SQLite apps needing multi-region reads; it is simpler than PostgreSQL replication.
• Set health checks with realistic timeouts; Fly Proxy uses them for routing, not just monitoring.
• Use

  fly-replay

  header for write operations in multi-region setups to route to the primary region.