---

name: fly-io description: >- Assists with deploying applications globally on Fly.io edge infrastructure. Use when deploying Docker-based apps, configuring multi-region machines, setting up persistent storage, or managing global databases. Trigger words: fly.io, fly deploy, fly machines, fly launch, multi-region, edge deployment, flyctl. license: Apache-2.0 compatibility: "Requires flyctl CLI and a Fly.io account" metadata: author: terminal-skills version: "1.0.0" category: devops tags: ["fly-io", "deployment", "edge", "multi-region", "infrastructure"]

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.