Fly.io Deployment Knowledge

Overview

Comprehensive guide for deploying applications to Fly.io, covering configuration, Dockerfiles, volumes, and common pitfalls. Based on official documentation and real deployment experience.

Sources

• Fly.io Configuration Reference
• Fly Volumes Overview
• Fly.io Monorepo Deployments
• Vercel's Official Next.js Dockerfile

---

Critical Limitations

Volumes

A Machine can only mount ONE volume. This is the most common gotcha.

# WRONG - Will fail with "only 1 volume supported"
[[mounts]]
  source = "data"
  destination = "/data"

[[mounts]]
  source = "repos"
  destination = "/repos"

# CORRECT - Single volume with subdirectories
[[mounts]]
  source = "app_data"
  destination = "/data"

# Then use /data/repos, /data/db, etc. in your app

Other volume constraints:

• Volumes are pinned to specific physical hosts
• Cannot shrink volumes, only extend
• Not available during Docker build or release_command
• One-to-one mapping: 1 volume = 1 machine

Build Context

When using fly deploy --config path/to/fly.toml:

• The dockerfile path is relative to where fly.toml is located
• The build context is the current working directory

For monorepos, place fly.toml files in the project root with dockerfile paths like apps/api/Dockerfile.

---

fly.toml Configuration

Minimal Working Example

app = "my-app"
primary_region = "dfw"

[build]
  dockerfile = "Dockerfile"

[env]
  PORT = "8080"

[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true
  min_machines_running = 0

[[vm]]
  memory = "512mb"
  cpu_kind = "shared"
  cpus = 1

With Volume (for stateful apps)

app = "my-api"
primary_region = "dfw"

[build]
  dockerfile = "apps/api/Dockerfile"

[env]
  DB_PATH = "/data/app.db"
  PORT = "8080"

[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = false  # Keep running for API
  auto_start_machines = true
  min_machines_running = 1

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

[[vm]]
  memory = "1gb"
  cpu_kind = "shared"
  cpus = 1

With Build Args (for Next.js NEXT_PUBLIC_* vars)

[build]
  dockerfile = "apps/web/Dockerfile"
  [build.args]
    NEXT_PUBLIC_API_URL = "https://my-api.fly.dev"

[env]
  PORT = "3000"
  NODE_ENV = "production"
  NEXT_PUBLIC_API_URL = "https://my-api.fly.dev"

---

Dockerfile Patterns

Next.js Standalone (Official Pattern)

FROM node:20-alpine AS base

# Dependencies
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
COPY package.json package-lock.json* ./
RUN npm ci

# Builder
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

ARG NEXT_PUBLIC_API_URL
ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL

RUN npm run build

# Runner
FROM base AS runner
WORKDIR /app

ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"

CMD ["node", "server.js"]

Requirements:

• next.config.js must have output: 'standalone'
• Install sharp if using Next.js Image optimization

FastAPI/Python

FROM python:3.11-slim

RUN apt-get update && apt-get install -y \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

ENV PYTHONUNBUFFERED=1
ENV PYTHONDONTWRITEBYTECODE=1

EXPOSE 8080

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8080/health || exit 1

# IMPORTANT: Use exec form and --proxy-headers for Fly's TLS proxy
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080", "--proxy-headers"]

Multi-stage for External Tools

Pull binaries from official images instead of version-pinning downloads:

# Pull tools from official images (always latest)
FROM ghcr.io/gitleaks/gitleaks:latest AS gitleaks
FROM aquasec/trivy:latest AS trivy

FROM python:3.11-slim

# Copy binaries
COPY --from=gitleaks /usr/bin/gitleaks /usr/local/bin/gitleaks
COPY --from=trivy /usr/local/bin/trivy /usr/local/bin/trivy

# ... rest of Dockerfile

---

Monorepo Deployment

Directory Structure

project-root/
├── fly.api.toml          # API config (in root)
├── fly.web.toml          # Web config (in root)
├── apps/
│   ├── api/
│   │   ├── Dockerfile    # Paths relative to root
│   │   └── ...
│   └── web/
│       ├── Dockerfile    # Paths relative to root
│       └── ...

Deploy Commands

# From project root
fly deploy --config fly.api.toml
fly deploy --config fly.web.toml

Dockerfile Paths for Monorepo

Since Dockerfiles are built with root as context:

# In apps/api/Dockerfile
COPY apps/api/requirements.txt .
COPY apps/api/*.py /app/

# In apps/web/Dockerfile
COPY apps/web/package*.json ./
COPY apps/web/ .

---

Common Commands

# Create apps
fly apps create my-app --org my-org

# Create volume (pick region with good capacity)
fly volumes create app_data --size 10 --app my-app --region dfw

# Check region capacity first
fly platform regions

# Set secrets
fly secrets set \
  API_KEY="xxx" \
  DB_URL="yyy" \
  --app my-app

# Deploy
fly deploy --config fly.api.toml

# View logs
fly logs --app my-app

# SSH into machine
fly ssh console --app my-app

# Check status
fly status --app my-app

# List volumes
fly volumes list --app my-app

---

Region Selection

Check capacity before choosing:

fly platform regions

Pick regions with positive capacity scores. Negative scores mean constrained resources.

Good US options (typically):

• dfw - Dallas
• lax - Los Angeles
• ord - Chicago

---

Troubleshooting

"only 1 volume supported"

You have multiple [[mounts]] sections. Consolidate to one volume with subdirectories.

Dockerfile path doubling

Example: /apps/api/apps/api/Dockerfile

Cause: fly.toml is in a subdirectory with relative dockerfile path. Fix: Place fly.toml in project root with full path: dockerfile = "apps/api/Dockerfile"

Build context wrong

Symptom: COPY apps/web/ . fails with "not found" Fix: Deploy from project root: fly deploy --config fly.web.toml

TypeScript build fails in Docker

Test locally first:

cd apps/web && npx tsc --noEmit

App won't start - connection refused

Check that app binds to 0.0.0.0, not localhost or 127.0.0.1.

HTTPS/proxy issues

For apps behind Fly's TLS proxy, add --proxy-headers to uvicorn or equivalent for your framework.

Next.js "useX must be used within Provider" during build

Symptom: Build fails with errors like:

Error: useAuth must be used within an AuthProvider
Error occurred prerendering page "/dashboard"

Cause: Next.js tries to statically pre-render pages at build time. If pages use React Context hooks (like useAuth, useTheme, etc.) but the Provider isn't wrapping the component tree during SSG, the build fails.

Fix: Ensure your context Provider wraps the entire app in layout.tsx:

// src/components/Providers.tsx
'use client'

import { ReactNode } from 'react'
import { AuthProvider } from '../hooks/useAuth'

export default function Providers({ children }: { children: ReactNode }) {
  return <AuthProvider>{children}</AuthProvider>
}

// src/app/layout.tsx
import Providers from '../components/Providers'
import AppLayout from '../components/AppLayout'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>
          <AppLayout>{children}</AppLayout>
        </Providers>
      </body>
    </html>
  )
}

Key points:

• The Providers component must have 'use client' directive
• Wrap providers around any component that uses context hooks
• This applies to any context: Auth, Theme, Query clients, etc.

Next.js "/app/public": not found

Symptom: Build fails with:

COPY --from=builder /app/public ./public
failed to calculate checksum: "/app/public": not found

Cause: The standard Next.js Dockerfile copies the public directory, but your project doesn't have one.

Fix: Create an empty public directory:

mkdir -p apps/web/public
touch apps/web/public/.gitkeep

Note: The public directory is where Next.js serves static assets (favicon, images, robots.txt, etc.). Even if empty, the directory must exist for the Dockerfile COPY to succeed.

---

Cost Optimization

Free tier includes:

• 3 shared-cpu-1x VMs with 256MB RAM
• 3GB persistent storage
• 160GB outbound bandwidth

To minimize costs:

• Use auto_stop_machines = true for non-critical apps
• Use min_machines_running = 0 when possible
• Start with 256mb memory, increase if needed
• Use single volume with subdirectories instead of multiple volumes