fly-io

name	fly-io
title	Fly.io
category	Hosting & Deploy
description	Use to deploy Docker/containerized apps close to users on Fly Machines, configured with fly.toml and the flyctl CLI.
tags	["hosting","deploy","docker","edge","machines","containers"]
official_docs	https://fly.io/docs
sources	["https://fly.io/docs/launch/","https://fly.io/docs/apps/secrets/"]
last_verified	2026-08-10T00:00:00.000Z

Fly.io — Skillship

Run full apps (not just functions) as lightweight VMs called Machines, deployed close to users in many regions. You bring a Dockerfile (or let Fly detect one); fly launch and fly deploy do the rest.

🧭 When to use this skill

• Use when: you want an always-on containerized app running in specific/multiple regions.
• Use when: you need real VMs (persistent volumes, custom runtimes) rather than serverless functions.
• Don't use for: static-only sites (a CDN host is simpler) or pure edge functions (use Cloudflare).

⚡ Quickstart

1. Install flyctl + sign in

# macOS/Linux: curl -L https://fly.io/install.sh | sh   | Windows: iwr https://fly.io/install.ps1 -useb | iex
fly auth login

2. Launch (creates fly.toml, detects/builds a Dockerfile, provisions the app)

fly launch     # walks you through app name, region, and optional Postgres/Redis

3. Deploy / redeploy

fly deploy
fly open        # open the app URL
fly logs        # tail logs

🧩 Common recipes

Recipe: Set runtime secrets (NOT in fly.toml)

fly secrets set STRIPE_SECRET_KEY=sk_live_... DATABASE_URL=postgres://...
fly secrets list        # names only
# Setting/removing secrets triggers a new deploy so machines pick them up.

Recipe: Minimal fly.toml

app = "my-app"
primary_region = "iad"

[build]
  # dockerfile = "Dockerfile"   # auto-detected if present

[http_service]
  internal_port = 8080          # must match the port your app listens on
  force_https = true
  auto_stop_machines = true     # scale to zero when idle
  auto_start_machines = true
  min_machines_running = 0

[[vm]]
  cpu_kind = "shared"
  cpus = 1
  memory_mb = 512

Recipe: Scale (count + size + regions)

fly scale count 3                 # run 3 machines
fly scale vm shared-cpu-1x --memory 1024
fly regions add fra sin           # add regions

Recipe: Add a persistent volume

fly volumes create data --size 10 --region iad
# then mount it in fly.toml:
# [mounts]
#   source = "data"
#   destination = "/data"

🚀 Ship to production

• Runtime secrets set via fly secrets set (encrypted) — never in fly.toml or the image.
• internal_port in fly.toml matches the port your app actually listens on (bind 0.0.0.0).
• force_https = true; health checks configured so bad deploys don't take traffic.
• primary_region chosen near users/DB; add regions only when needed (watch DB latency).
• Decide on auto_stop_machines (cost) vs min_machines_running (no cold starts).
• Persistent state on a volume, not the ephemeral machine filesystem.

🔐 Security & secrets

• fly secrets are encrypted and injected as env vars at runtime; changing them redeploys the app.
• Never bake secrets into the Docker image or commit them in fly.toml.
• Use fly ips / private networking to avoid exposing internal services publicly.

🐛 Common errors & fixes

Symptom	Likely cause	Fix
Deploy healthchecks fail / no traffic	App not listening on internal_port	Match internal_port; bind 0.0.0.0, not 127.0.0.1
Secret changes not applied	App read env at build time	Read process.env at runtime; secrets redeploy machines
Data lost after deploy	Wrote to ephemeral FS	Use a mounted volume
Cold starts	auto_stop_machines with 0 running	Set min_machines_running = 1
High latency to DB	App region far from DB	Colocate primary_region with the database

📚 Sources

• https://fly.io/docs/launch/
• https://fly.io/docs/apps/secrets/