fly-io

Deploy on Fly.io

You are deploying an app to Fly.io: a fly.toml, Machines (Firecracker microVMs) placed in regions close to users, optional region-pinned Volumes, secrets, and the right scaling lever. Get the mental model right first, then the config follows. If none of that placement control matters, ../railway/SKILL.md is the git-push PaaS with no Machines/regions model.

Mental model

• App is the logical unit. It owns a name, a primary_region, and config in fly.toml. Why: every command targets an app.
• Process groups ([processes], e.g. web, worker) split one image into roles. Why: a web group takes traffic, a worker group does not — they bind services and VMs separately.
• Machines are Firecracker microVMs running your image. Each runs in exactly one region. Why: latency and volumes are per-Machine, so placement is the whole game.
• Fly Proxy is the anycast front door. It routes a request to the nearest running Machine, can start a stopped one, and obeys fly-replay headers. Why: it is what makes "global" cheap — you do not run a load balancer.
• Volumes are local NVMe disks pinned to one Machine in one region. No replication. Why: this single fact dictates every stateful architecture decision below.

Deploy fast (4 commands)

fly launch                              # detects framework, generates fly.toml + Dockerfile, creates the app
fly secrets set DATABASE_URL=postgres://...  # restarts every Machine; never put this in [env]
fly deploy                              # builds image, runs release_command, rolls out Machines
fly scale count 2 --region iad,ams      # place Machines in Virginia + Amsterdam

fly launch is interactive and writes a starter fly.toml. Treat that file as a draft — review it against the next section before the first real deploy. Run fly status and fly logs after any deploy.

A fly.toml that works

app            = "my-api"
primary_region = "iad"            # 3-letter region code: iad, ord, ams, syd, gru, nrt...

[build]
  # dockerfile = "Dockerfile"     # Fly builds from your Dockerfile; see ../docker/SKILL.md

[deploy]
  release_command = "npm run migrate"   # one-shot Machine that runs BEFORE the new version goes live
  strategy        = "rolling"            # rolling | bluegreen | canary | immediate

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

[http_service]
  internal_port       = 8080
  force_https         = true
  auto_stop_machines  = "stop"   # "off" | "stop" | "suspend" — set WITH auto_start_machines
  auto_start_machines = true
  min_machines_running = 0       # 0 = scale to zero; honored only in primary_region
  processes           = ["web"]

  [http_service.concurrency]
    type       = "requests"
    soft_limit = 200             # Proxy starts spreading load past this
    hard_limit = 250             # Proxy stops sending past this

[[vm]]                            # formerly [[compute]]
  size       = "shared-cpu-1x"
  memory     = "512mb"
  cpu_kind   = "shared"          # "shared" | "performance"
  processes  = ["web"]

[[mounts]]
  source       = "data"          # volume NAME, created with `fly volumes create data`
  destination  = "/data"
  processes    = ["web"]
  initial_size = "1gb"