Fly.io Deployment

Quick MVP deployment to fly.io with support for multiple languages, databases, GitHub integration, and production-ready configurations.

When to Use This Skill

Use this skill when you need to:

Deploy a new application to fly.io quickly
Migrate existing applications to fly.io
Set up databases (Managed Postgres, SQLite with volumes, or Tigris object storage)
Configure secrets and environment variables
Add custom domains with SSL certificates
Set up GitHub Actions for continuous deployment
Create PR review apps (preview environments)
Troubleshoot deployment or runtime issues
Optimize fly.io configurations for cost and performance

Quick Start

New Application

# From your app directory
fly launch

# Follow interactive prompts:
# - Choose app name
# - Select region
# - Configure resources
# - Deploy immediately or create config only

Existing Application

# Deploy app with existing fly.toml
fly deploy

# Build on fly.io servers (recommended for CI/CD)
fly deploy --remote-only

Workflow Decision Tree

1. Choose Your Starting Point

New App (No fly.toml) → See: Deploying New Applications

Existing fly.io App → See: Deploying Existing Applications

Migrating from Another Platform → See: references/deployment-workflow.md + Language-specific guides

2. Choose Your Language/Framework

Navigate to the appropriate language guide:

JavaScript/Node.js:

Next.js → references/languages/javascript.md#nextjs
Express → references/languages/javascript.md#express
RedwoodJS → references/languages/javascript.md#redwoodjs

Python:

FastAPI → references/languages/python.md#fastapi
Django → references/languages/python.md#django
Flask → references/languages/python.md#flask

Rust:

Axum → references/languages/rust.md#axum
Rocket → references/languages/rust.md#rocket

Generic Dockerfile: → See: references/deployment-workflow.md

Each language guide includes:

Optimized Dockerfiles (see also: assets/dockerfiles/)
fly.toml configuration examples
Framework-specific best practices
Common issues and solutions

3. Add Data Persistence (Optional)

Choose based on your needs:

Managed Postgres (Recommended for production SQL databases) → See: references/data-persistence.md#managed-postgres → Script: scripts/init_postgres.sh

Volumes (For SQLite, file uploads, or local storage) → See: references/data-persistence.md#fly-volumes

Tigris Object Storage (For media files, user uploads, S3-compatible) → See: references/data-persistence.md#tigris-object-storage → Script: scripts/setup_tigris.sh

External Database (Supabase, PlanetScale, Neon, etc.) → See: references/data-persistence.md#external-databases

4. Configure Secrets

→ See: references/secrets-and-env.md

# Set secrets
fly secrets set DATABASE_URL=postgres://...
fly secrets set API_KEY=abc123

# Generate random secrets
fly secrets set SECRET_KEY=$(openssl rand -hex 32)

5. Add Custom Domain (Optional)

→ See: references/domains-and-networking.md

# Add custom domain
fly certs add example.com

# View DNS instructions
fly certs show example.com

6. Set Up CI/CD (Optional)

GitHub Actions Deployment: → See: references/github-integration.md → Template: assets/workflows/deploy.yml

PR Review Apps: → See: references/github-integration.md#review-apps → Template: assets/workflows/review-apps.yml → Script: scripts/setup_review_apps.sh

Deploying New Applications

Step 1: Prepare Your Application

Ensure your app has:

Dockerfile or package.json/requirements.txt (for buildpacks)
Health endpoint (e.g., /health returning 200 OK)
Port configuration reading from PORT environment variable
Bind to 0.0.0.0 (not localhost or 127.0.0.1)

Example Dockerfiles available in: assets/dockerfiles/

nextjs.Dockerfile
express.Dockerfile
fastapi.Dockerfile
axum.Dockerfile
rocket.Dockerfile

Step 2: Initialize fly.io App

fly launch

Interactive prompts will:

Detect your app type
Suggest a name
Choose a region
Create fly.toml
Optionally deploy immediately

Useful flags:

# Skip deployment, just create config
fly launch --no-deploy

# Specify app name
fly launch --name my-app

# Choose region
fly launch --region ord  # Chicago

Step 3: Configure fly.toml

Review and adjust fly.toml:

app = "my-app"
primary_region = "ord"

[build]
  dockerfile = "Dockerfile"

[env]
  PORT = "8080"

[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = "stop"
  auto_start_machines = true
  min_machines_running = 0  # Scale to zero for cost savings

  [[http_service.checks]]
    grace_period = "10s"
    interval = "30s"
    path = "/health"

[[vm]]
  memory = "256mb"
  cpus = 1

→ For complete fly.toml reference: references/deployment-workflow.md

Step 4: Deploy

fly deploy

Your app will be available at: https://my-app.fly.dev

Deploying Existing Applications

For apps with existing fly.toml:

# Standard deployment
fly deploy

# Remote build (recommended for CI/CD)
fly deploy --remote-only

# Specific deployment strategy
fly deploy --strategy rolling  # Zero downtime (default)
fly deploy --strategy immediate  # Faster, brief downtime

Common Tasks

Adding a Database

Managed Postgres (Recommended):

# Using the provided script
./scripts/init_postgres.sh --app my-app

# Or manually
fly postgres create --name my-app-db
fly postgres attach my-app-db

Tigris Object Storage:

# Using the provided script
./scripts/setup_tigris.sh --app my-app

# Or manually
fly storage create

→ See: references/data-persistence.md

Managing Secrets

# Set secrets
fly secrets set DATABASE_URL=postgres://...
fly secrets set API_KEY=secret123

# List secrets (names only)
fly secrets list

# Remove secrets
fly secrets unset API_KEY

→ See: references/secrets-and-env.md

Setting Up Review Apps

# Using the provided script
./scripts/setup_review_apps.sh --org personal --region ord

# Or copy template manually
cp assets/workflows/review-apps.yml .github/workflows/

→ See: references/github-integration.md#review-apps

Adding Custom Domain

# Add domain
fly certs add example.com

# Get your app's IP addresses
fly ips list

# Configure DNS (A and AAAA records)
# Then verify
fly certs show example.com

→ See: references/domains-and-networking.md

Scaling

# Scale memory
fly scale memory 512

# Scale machine size
fly scale vm shared-cpu-2x

# Scale instance count
fly scale count 3

# Scale across regions
fly scale count 2 --region ord,iad

→ See: references/deployment-workflow.md#scaling

Troubleshooting

Common Issues

App won't start:

# Check logs
fly logs

# Verify port configuration
# App must listen on PORT env var and bind to 0.0.0.0

Health checks failing:

# Test health endpoint
fly ssh console -C "curl http://localhost:8080/health"

# Adjust grace period in fly.toml if needed

Database connection errors:

# Verify DATABASE_URL is set
fly secrets list

# Test from within app
fly ssh console
echo $DATABASE_URL

Deployment slow or timing out:

# Use remote builder
fly deploy --remote-only

# Check build cache
fly deploy --no-cache

→ For comprehensive troubleshooting: references/troubleshooting.md

Debugging Commands

# View app status
fly status

# Stream logs
fly logs

# SSH into running machine
fly ssh console

# List machines
fly machine list

# View deployments
fly releases

# Check health checks
fly checks list

Reference Documentation

Core Guides

Deployment Workflow - fly.toml configuration, deployment strategies, scaling
Data Persistence - Postgres, volumes, Tigris, external databases
Secrets Management - Environment variables, secret handling, security
GitHub Integration - GitHub Actions, review apps, CI/CD
Custom Domains - DNS setup, SSL certificates, networking
Troubleshooting - Common issues, debugging techniques, solutions

Language-Specific Guides

JavaScript/Node.js - Next.js, Express, RedwoodJS
Python - FastAPI, Django, Flask
Rust - Axum, Rocket

Bundled Resources

Scripts (`scripts/`)

Automation scripts for common tasks:

setup_review_apps.sh - Generate GitHub Actions workflow for PR review apps
init_postgres.sh - Create and attach Managed Postgres database
setup_tigris.sh - Configure Tigris object storage bucket

All scripts include help text. Run with --help or without arguments for usage.

Dockerfile Templates (`assets/dockerfiles/`)

Production-ready Dockerfiles for each framework:

nextjs.Dockerfile - Next.js with standalone output (minimal image)
express.Dockerfile - Express.js with multi-stage build
fastapi.Dockerfile - FastAPI with uvicorn
axum.Dockerfile - Axum with optimized Rust build
rocket.Dockerfile - Rocket with multi-stage build

Copy and customize for your app.

GitHub Actions Workflows (`assets/workflows/`)

Ready-to-use workflow templates:

deploy.yml - Basic deployment on push to main
review-apps.yml - PR review apps with automatic cleanup
test-and-deploy.yml - Run tests before deploying

Copy to .github/workflows/ and customize.

Best Practices

Always use health checks - Ensures reliable deployments
Start with minimal resources - Scale up based on actual usage
Use Managed Postgres for production - Don't run unmanaged databases
Set secrets properly - Never commit secrets to git
Use remote builds for CI/CD - fly deploy --remote-only
Test locally first - Build and test Docker images locally
Monitor logs regularly - fly logs helps catch issues early
Use review apps - Test changes before merging
Configure graceful shutdown - Handle SIGTERM properly
Keep dependencies updated - Security and performance

Quick Reference

# Essential commands
fly launch              # Create new app
fly deploy             # Deploy app
fly status             # Check app status
fly logs               # View logs
fly ssh console        # SSH into machine

# Database
fly postgres create    # Create database
fly postgres attach    # Attach to app
fly storage create     # Create Tigris bucket

# Configuration
fly secrets set KEY=value    # Set secret
fly secrets list            # List secrets
fly scale memory 512        # Scale memory
fly scale count 3           # Scale instances

# Domains
fly certs add example.com   # Add domain
fly certs show example.com  # Check certificate
fly ips list               # Get IP addresses

# Troubleshooting
fly logs                    # Stream logs
fly ssh console            # Access machine
fly checks list            # View health checks
fly releases               # View deployments

Getting Help

Documentation: https://fly.io/docs/
Community Forum: https://community.fly.io/
Status Page: https://status.flyio.net/
This Skill: Check references/troubleshooting.md for common issues

Note: fly.io changes frequently. This skill is based on documentation current as of January 2026. If commands or features have changed, consult the official fly.io documentation at https://fly.io/docs/