Fly.io Deployment

Deploy applications to Fly.io from source code or Docker images.

Prerequisites

Ensure flyctl is installed and authenticated:

# Check installation
fly version

# Authenticate if needed
fly auth login

Deployment Workflow

1. Detect Project Type

Examine the project root to determine the stack:

Read the appropriate reference file for framework-specific configuration.

2. Initialize or Configure

New app:

fly launch --no-deploy

This creates fly.toml. Review and adjust before deploying.

Existing app (no fly.toml):

fly launch --no-deploy
# Or create fly.toml manually using references/fly-toml.md

3. Set Secrets

Set environment variables that shouldn't be in fly.toml:

# Single secret
fly secrets set DATABASE_URL="postgres://..."

# Multiple secrets
fly secrets set KEY1=value1 KEY2=value2

# From .env file
cat .env | fly secrets import

Secrets trigger a redeploy. Use --stage to batch them:

fly secrets set --stage KEY1=value1
fly secrets set --stage KEY2=value2
fly secrets deploy

4. Deploy

fly deploy

Common flags:

• --ha — High availability (2+ machines, default)
• --no-ha — Single machine (dev/staging)
• --strategy rolling|bluegreen|canary|immediate
• --wait-timeout 5m — Extend for slow builds

5. Verify

# Check status
fly status

# View logs
fly logs

# Open in browser
fly open

Troubleshooting

If deployment fails, consult references/troubleshooting.md for common errors and fixes.

Quick checks:

1. Health check passing? Check internal_port matches app's listen port
2. App starting? Check fly logs for crash loops
3. Build failing? Check Dockerfile or buildpack compatibility

Configuration Reference

For detailed fly.toml options, see references/fly-toml.md.

Key settings:

• primary_region — Where machines deploy by default
• [http_service] — HTTP/HTTPS configuration
• [env] — Non-sensitive environment variables
• [[vm]] — CPU/memory sizing