flyio

What this skill does

# Fly.io Infrastructure Skills

**Version**: 1.0.0 | **Target Size**: <25KB | **Purpose**: Fast reference for Fly.io deployments and global application distribution

---

## Overview

**What is Fly.io**: Modern platform-as-a-service (PaaS) for deploying applications globally with minimal configuration. Fly.io transforms containers into micro-VMs that run on physical hardware across 30+ regions worldwide.

**When to Use Fly.io**:
- Simple to moderate applications requiring global distribution
- Fast deployments without complex Kubernetes orchestration
- Minimal operations overhead with PaaS simplicity
- Edge computing and low-latency requirements (anycast routing)
- Startup/SaaS applications with unpredictable traffic patterns
- Databases requiring multi-region active replication (Fly Postgres)

**When to Use Kubernetes Instead**:
- Complex microservices architectures with 10+ interdependent services
- Existing Kubernetes expertise and tooling investment
- Hybrid cloud or multi-cloud requirements (cloud-agnostic)
- Advanced orchestration needs (service mesh, custom operators, advanced scheduling)
- Enterprise compliance requirements (HIPAA, PCI-DSS on-premises)
- Extensive third-party ecosystem integrations (Helm charts, operators)

**Detection Criteria**:
- Auto-loads when `fly.toml` detected in project root
- Manual: `--tools=flyio` flag
- Use Case: Global application deployment with PaaS simplicity

**Progressive Disclosure**:
- **This file (SKILL.md)**: Quick reference for immediate use
- **REFERENCE.md**: Comprehensive guide with advanced patterns and deployment strategies

---

## Table of Contents

1. [fly.toml Quick Reference](#flytoml-quick-reference)
2. [Deployment Patterns](#deployment-patterns)
3. [Secrets Management](#secrets-management)
4. [Networking Basics](#networking-basics)
5. [Health Checks](#health-checks)
6. [Scaling Patterns](#scaling-patterns)
7. [Common Commands Cheat Sheet](#common-commands-cheat-sheet)
8. [Quick Troubleshooting](#quick-troubleshooting)
9. [Framework-Specific Examples](#framework-specific-examples)

---

## fly.toml Quick Reference

### Minimal Configuration (Node.js Express)

```toml
# app name (must be globally unique on Fly.io)
app = "my-express-app"

[build]
  # Dockerfile-based build (default)
  dockerfile = "Dockerfile"

[env]
  # Non-sensitive environment variables
  NODE_ENV = "production"
  PORT = "8080"

[[services]]
  internal_port = 8080  # Container port
  protocol = "tcp"

  [[services.ports]]
    handlers = ["http"]
    port = 80  # External HTTP

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

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

**Key Concepts**:
- **app**: Globally unique application name (DNS-safe)
- **build**: How to build your application (Dockerfile, buildpacks)
- **env**: Non-sensitive configuration (use secrets for sensitive data)
- **services**: Network services exposed to the internet
- **internal_port**: Port your app listens on inside container
- **ports**: External ports (80 HTTP, 443 HTTPS)
- **http_checks**: Health check configuration

---

### Node.js (Express, Fastify, Koa)

```toml
app = "nodejs-api"

[build]
  dockerfile = "Dockerfile"

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

[[services]]
  internal_port = 8080
  protocol = "tcp"
  auto_stop_machines = true
  auto_start_machines = true
  min_machines_running = 1

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

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

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

**Dockerfile** (minimal):
```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
EXPOSE 8080
CMD ["node", "server.js"]
```

---

### Next.js Application

```toml
app = "nextjs-app"

[build]
  dockerfile = "Dockerfile"

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

[[services]]
  internal_port = 3000
  protocol = "tcp"
  auto_stop_machines = true
  auto_start_machines = true

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

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

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

**Dockerfile** (Next.js standalone):
```dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/next.config.js ./
COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
EXPOSE 3000
CMD ["node", "server.js"]
```

---

### Python (Django, FastAPI, Flask)

```toml
app = "python-api"

[build]
  dockerfile = "Dockerfile"

[env]
  PYTHONUNBUFFERED = "1"
  PORT = "8000"

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

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

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

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

**Dockerfile** (FastAPI example):
```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```

---

### Go Microservice

```toml
app = "go-service"

[build]
  dockerfile = "Dockerfile"

[env]
  PORT = "8080"

[[services]]
  internal_port = 8080
  protocol = "tcp"
  auto_stop_machines = true
  auto_start_machines = true

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

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

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

**Dockerfile** (multi-stage Go build):
```dockerfile
FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY go.* ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /app/server

FROM alpine:latest
RUN apk --no-cache add ca-certificates
COPY --from=builder /app/server /app/server
EXPOSE 8080
CMD ["/app/server"]
```

---

### Ruby on Rails

```toml
app = "rails-app"

[build]
  dockerfile = "Dockerfile"

[env]
  RAILS_ENV = "production"
  PORT = "3000"

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

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

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

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

---

### Elixir Phoenix

```toml
app = "phoenix-app"

[build]
  dockerfile = "Dockerfile"

[env]
  PORT = "4000"
  MIX_ENV = "prod"

[deploy]
  release_command = "/app/bin/migrate"

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

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

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

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

**Key Feature**: `release_command` runs database migrations before deployment.

---

## Deployment Patterns

### Zero-Downtime Deployments

Fly.io's **rolling deployment** ensures zero downtime:

```toml
[deploy]
  strategy = "rolling"  # Default
  max_unavailable = 0.33  # 33% of machines can be down during deploy
```

**How it works**:
1. New machines start with updated code
2. Health checks pass on new machines
3. Old machines drain connections (graceful shutdown)
4. Old machines stop after connections close

**Graceful Shutdown**:
```javascript
// Express.js example
const server = app.listen(PORT);

process.on('SIGTERM', () =>