fly-iac-and-deployment

Fly IaC and Deployment

When to use

• Designing a CI/CD pipeline for a Fly-hosted application.
• Writing or reviewing a fly.toml configuration.
• Choosing between deploy strategies for a service.
• Setting up GitHub Actions for automated deployment.
• Scripting multi-region machine configuration via the Machines API.
• Evaluating the Pulumi flyio/fly provider for infrastructure management.

flyctl — the primary interface

flyctl (alias: fly) is the canonical CLI and the primary IaC surface for Fly. As of flyctl ≥ 0.3.x:

• fly deploy — build and deploy an app from source or a pre-built image.
• fly machine run — launch an ephemeral or long-running machine directly.
• fly machine update — update machine config (size, env, image) without a full deploy.
• fly releases — list and manage releases.
• fly scale — adjust machine count and size.
• fly ssh — interactive shell into a machine.
• fly postgres, fly redis, fly storage — manage attached services.

Version-pin flyctl in CI. Fly moves fast; pin a specific version in your GitHub Actions workflow to avoid surprise breakage.

fly.toml — configuration-as-code

fly.toml is the app's configuration file. It is version-controlled alongside the application code. It defines services, environment variables, health checks, mount points, deploy strategy, and resource constraints.

v2 format is required as of flyctl 0.1.x. Use fly config show to validate the format.

Annotated fly.toml example

# fly.toml — v2 format

app = "myapp"
primary_region = "iad"

[build]
  dockerfile = "Dockerfile"

[env]
  # Non-sensitive config only. Secrets go in fly secrets.
  PORT = "8080"
  LOG_LEVEL = "info"
  FLY_APP_NAME = "myapp"

[deploy]
  strategy = "rolling"    # or "bluegreen", "canary", "immediate"
  release_command = "python manage.py migrate"  # Run before new machines start

[[vm]]
  size = "shared-cpu-2x"
  memory = "512mb"

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

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

[[http_service.checks]]
  grace_period = "10s"
  interval = "15s"
  method = "GET"
  path = "/healthz"
  timeout = "5s"

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

[[metrics]]
  port = 9091
  path = "/metrics"    # Prometheus-compatible endpoint for Fly to scrape