enuno/flyio

Fly.io Platform Skill

Overview

Fly.io is a platform for deploying full-stack applications and databases globally. It runs your apps on Machines (fast-launching VMs) close to your users and scales compute resources automatically based on demand.

When to Use This Skill

Use Fly.io when you need to:

• Deploy web applications with global distribution
• Run Docker containers in production
• Scale applications automatically based on load
• Deploy databases (Postgres, Redis) close to users
• Run background jobs and workers
• Build multi-region applications with low latency

Core Concepts

Applications

An app on Fly.io can be anything from a simple frontend web app to a complex arrangement of processes and Machines all doing their own thing. Applications are defined using fly.toml configuration files.

Machines

Firecracker micro-VMs that run your application code. Machines can:

• Start in milliseconds
• Scale to zero when idle (autostop/autostart)
• Run anywhere in Fly.io's global network
• Be sized from minimal (shared-cpu-1x) to performance-optimized

Fly Launch

The primary deployment framework that manages the complete application lifecycle:

• Creates and configures applications
• Detects project types automatically
• Builds Docker images
• Provisions resources (IPs, volumes, databases)
• Deploys and scales applications

Quick Start

1. Install flyctl

macOS/Linux:

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

Windows:

pwsh -Command "iwr https://fly.io/install.ps1 -useb | iex"

2. Sign up or log in

fly auth signup  # Create new account
fly auth login   # Existing account

3. Launch your application

cd your-app
fly launch

This will:

• Scan your project and detect the framework
• Create a fly.toml configuration file
• Build your application as a Docker image
• Deploy your app to Fly.io
• Allocate IP addresses (IPv6 dedicated, IPv4 shared)

4. Deploy updates

fly deploy

Common Commands

Application Management

# Launch new app (interactive)
fly launch

# Launch with custom options
fly launch --name my-app --region ord --no-deploy

# Deploy app updates
fly deploy

# Deploy without rebuilding
fly deploy --image registry.fly.io/my-app:latest

# Check app status
fly status

# View app information
fly info

# Open app in browser
fly open

# View logs
fly logs

# SSH into Machine
fly ssh console

# List all apps
fly apps list

# Destroy app
fly apps destroy my-app

Machine Management

# List Machines
fly machines list

# Create Machine
fly machines run registry.fly.io/my-app:latest

# Stop Machine
fly machines stop <machine-id>

# Start Machine
fly machines start <machine-id>

# Destroy Machine
fly machines destroy <machine-id>

Scaling

# Scale Machine count
fly scale count 3

# Scale to specific regions
fly scale count 2 --region ord --region iad

# Scale Machine resources
fly scale vm shared-cpu-2x --memory 2048

# Configure autoscaling
fly autoscale set min=1 max=10

Secrets Management

# Set secret
fly secrets set DATABASE_URL=postgres://...

# List secrets (names only, not values)
fly secrets list

# Unset secret
fly secrets unset DATABASE_URL

# Import secrets from file
fly secrets import < .env.production

Volumes (Persistent Storage)

# Create volume
fly volumes create data --size 10

# List volumes
fly volumes list

# Delete volume
fly volumes delete vol_abc123

# Extend volume size
fly volumes extend vol_abc123 --size 20

Databases

# Create Postgres cluster
fly postgres create --name my-db

# Attach Postgres to app
fly postgres attach --app my-app my-db

# Create Redis instance
fly redis create --name my-redis

# Connect to Postgres
fly postgres connect --app my-db

Configuration (fly.toml)

Basic Structure

# App name
app = "my-app"

# Primary region
primary_region = "ord"

# Build configuration
[build]
  dockerfile = "Dockerfile"

# HTTP service
[[services]]
  protocol = "tcp"
  internal_port = 8080

  [[services.ports]]
    port = 80
    handlers = ["http"]

  [[services.ports]]
    port = 443
    handlers = ["tls", "http"]

# Machine VM size
[vm]
  size = "shared-cpu-1x"
  memory_mb = 256

# Auto stop/start
[auto_stop_machines]
  enabled = true
  min_machines_running = 0

[auto_start_machines]
  enabled = true

Advanced Features

Environment Variables:

[env]
  PORT = "8080"
  NODE_ENV = "production"

Process Groups:

[processes]
  web = "node server.js"
  worker = "node worker.js"

HTTP Service with Health Checks:

[[services]]
  protocol = "tcp"
  internal_port = 8080

  [[services.http_checks]]
    interval = "10s"
    timeout = "2s"
    grace_period = "5s"
    method = "GET"
    path = "/health"

  [[services.tcp_checks]]
    interval = "15s"
    timeout = "2s"
    grace_period = "5s"

Mounted Volumes:

[mounts]
  source = "data"
  destination = "/data"

Architecture & Deployment Blueprints

1. Resilient Applications with Multiple Machines

Pattern: Build high-availability apps using multiple Machines across regions

Key Concepts:

• Each Machine runs on a single physical host (no automatic failover)
• Service-based apps automatically get 2 Machines with autostop/autostart
• Apps with volumes get only 1 Machine (requires manual replication)
• Standby Machines for worker processes watch primary and start if it fails

Configuration Example:

[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = "stop"
  auto_start_machines = true
  min_machines_running = 0

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

Scaling Commands:

# Add redundancy with multiple Machines
fly scale count 2

# Multi-region deployment for geographic redundancy
fly scale count 20 --region ams,ewr,gig

# Create standby Machine for workers
fly machine clone <id> --standby-for <id>
fly machine run <image> --standby-for <machine-id>

Cost Efficiency:

• Stopped Machines charge only for rootfs storage (~$0.18/month for 1.2GB)
• No CPU or RAM charges when stopped
• Makes redundancy financially practical for side projects

When to Use:

• ✅ Production systems with paying users
• ✅ Customer-facing services requiring 99.9% uptime
• ✅ Regulated environments needing geographic availability
• ⚠️ Optional for staging/internal tools/side projects

2. Architecture Patterns

Available Patterns from Fly.io Blueprints:

N-Tier Architecture

• Multiple Machine resilience for high availability
• Session persistence strategies (sticky sessions)
• Shared Nothing architectural approaches

Multi-Region Database Patterns

• Deploy databases close to users
• Use fly-replay for write forwarding
• Read replicas in multiple regions

Networking & Connectivity

• Private application access via Flycast
• WireGuard VPN integration
• Cross-deployment bridging
• SSH server deployment for secure access

3. Scaling & Performance Blueprints

Autoscaling Configuration:

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

[auto_stop_machines]
  enabled = true
  min_machines_running = 0

[auto_start_machines]
  enabled = true

Machine Autoscaling:

# Set autoscaling bounds
fly autoscale set min=2 max=10

# Configure concurrency limits
fly scale concurrency soft=200 hard=250

# Private app autostart/autostop
# (automatically configured for internal services)

Volume Forking:

• Fork volumes for rapid Machine initialization
• Faster cold starts with pre-populated data
• Useful for read-heavy workloads

4. Background Jobs & Automation

Distributed Work Queue:

# Deploy worker Machines
fly machines run <image> --env WORKER=true --region ord

# Use standby workers for redundancy
fly machine run <image> --env WORKER=true --standby-for <primary-id>

Cron-Based Task Scheduling:

# Using Supercronic for cron execution
FROM alpine:latest
RUN apk add --no-cache supercronic
COPY crontab /etc/crontab
CMD ["supercronic", "/etc/crontab"]

Infrastructure Automation:

• Alternatives to Terraform for Fly.io infrastructure
• Programmatic Machine creation via fly-machines API
• Event-driven automation using webhooks

5. Developer Workflow Blueprints

Zero-Downtime Deployments:

# Default behavior with multiple Machines
fly deploy

# Rolling deployment with custom strategy
fly deploy --strategy rolling

Application Rollback:

# List recent releases
fly releases

# Rollback to previous version
fly releases rollback

GitHub Preview Environments:

# .github/workflows/preview.yml
name: Deploy Preview
on: pull_request

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: superfly/[email protected]
        with:
          args: "deploy --app my-app-pr-${{ github.event.pull_request.number }}"

Staging/Production Isolation:

# Create separate apps for environments
fly launch --name myapp-staging --org staging
fly launch --name myapp-production --org production

# Deploy to specific environment
fly deploy --app myapp-staging
fly deploy --app myapp-production

Per-User Development Environments:

# Create ephemeral dev environment
fly machines run <image> --name dev-$USERNAME --region ord

# Destroy when done
fly machines destroy dev-$USERNAME

6. Deployment Patterns

Static Site (Node.js)

FROM node:18-alpine as builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80

API Server (Python FastAPI)

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

Multi-region Deployment

# Deploy to multiple regions
fly deploy --region ord,iad,lhr

# Or configure in fly.toml

[regions]
  ord = 2  # 2 Machines in Chicago
  iad = 2  # 2 Machines in Virginia
  lhr = 1  # 1 Machine in London

Best Practices

Performance

1. Use health checks - Configure HTTP/TCP checks for automatic recovery
2. Enable autoscaling - Set min/max Machine counts based on load
3. Choose regions wisely - Deploy close to users and dependencies
4. Optimize Docker images - Use multi-stage builds, minimal base images
5. Use volumes sparingly - Volumes add latency; use managed databases when possible

Security

1. Use secrets - Never hardcode credentials in fly.toml or Dockerfile
2. Enable HTTPS - Fly.io provides free TLS certificates
3. Private networking - Use Fly.io private network (6PN) for inter-app communication
4. Least privilege - Deploy tokens and access controls appropriately
5. Regular updates - Keep base images and dependencies current

Cost Optimization

1. Autostop/autostart - Enable for low-traffic apps to scale to zero
2. Right-size Machines - Don't over-provision CPU/RAM
3. Use shared CPUs - Sufficient for most workloads
4. Monitor usage - Check fly dashboard for resource consumption
5. Clean up unused apps - Destroy test/staging apps when not needed

Reliability

1. Multiple Machines - Run at least 2 Machines for high availability
2. Health checks - Automatic traffic routing away from unhealthy Machines
3. Rolling deployments - Default behavior prevents downtime during updates
4. Backup volumes - Snapshot important data regularly
5. Monitor logs - Use fly logs or integrate with logging services

Troubleshooting

Common Issues

App won't start:

# Check logs
fly logs

# Verify configuration
fly config validate

# SSH into Machine
fly ssh console

Port binding errors:

• Ensure app listens on 0.0.0.0 not localhost
• Match internal_port in fly.toml with app's listening port
• Check PORT environment variable

Build failures:

# Build locally to test
fly deploy --local-only

# Use remote builder
fly deploy --remote-only

# Check Dockerfile syntax
docker build .

Slow performance:

• Check Machine size (CPU/RAM)
• Review autoscaling configuration
• Verify database connection pooling
• Enable connection reuse
• Check region proximity to users/services

Database connection issues:

• Verify DATABASE_URL secret is set
• Check Postgres cluster status: fly status --app my-db
• Use Fly.io private network addresses (.internal)
• Ensure connection pooling (pgbouncer)

Getting Help

# Community forum
fly open https://community.fly.io

# Documentation
fly docs

# Support
fly support

# Status page
fly open https://status.fly.io

Resources

Official Documentation

• Fly.io Docs: https://fly.io/docs/
• flyctl Reference: https://fly.io/docs/flyctl/
• Fly Launch: https://fly.io/docs/launch/
• App Configuration: https://fly.io/docs/reference/configuration/

Community

• Community Forum: https://community.fly.io
• GitHub: https://github.com/superfly
• Twitter: @flydotio

Pricing

• Free tier: 3 shared-cpu-1x Machines (256MB RAM)
• Additional resources: Pay-as-you-go
• Pricing calculator: https://fly.io/docs/about/pricing/

Examples in Repository

See knowledge/ directory for:

• Multi-region deployment examples
• Database integration patterns
• Background worker configurations
• Advanced networking setups

Changelog

Version 1.1 (2026-01-21)

• ✨ Added comprehensive Architecture & Deployment Blueprints section
• ✨ Added resilient applications pattern with multiple Machines
• ✨ Added autoscaling configuration examples
• ✨ Added background jobs and automation patterns
• ✨ Added developer workflow blueprints (zero-downtime, rollback, preview environments)
• ✨ Added cost efficiency guidance for stopped Machines
• ✨ Enhanced scaling commands with multi-region examples
• ✨ Added standby Machine pattern for worker processes

Version 1.0 (2026-01-21)

• Initial skill creation
• Core Fly.io concepts and quick start guide
• Common commands and configuration
• Basic deployment patterns
• Best practices for performance, security, cost, and reliability
• Troubleshooting guide

---

Version: 1.1 Last Updated: 2026-01-21 Source: Fly.io Official Documentation + Blueprints Maintained By: Claude Command and Control