Fly.io Deploy Integration

Overview

Deploy edge applications on Fly.io with Docker containers and the fly.toml configuration file. This skill covers building production images optimized for Fly's micro-VM architecture, configuring fly.toml for services, health checks, and multi-region placement, verifying API connectivity from edge locations, and executing rolling updates with automatic rollback. Fly.io deploys as Firecracker micro-VMs, so containers start in under a second and scale to zero when idle.

Prerequisites

• A deployment owner, scoped CI token, reviewed image, environment config, health criteria, and rollback operator.
• Staging with synthetic traffic and explicit data/region requirements before any multi-region promotion.

Instructions

1. Build reproducibly and run as a non-root user; inject secrets only through the platform.
2. Deploy a small canary, observe redacted health and saturation metrics, and verify graceful failure behavior.
3. Promote region by region only when the canary succeeds; stop and roll back on health, configuration, or access failures.
4. Retain the release reference and recovery evidence for the approved change window.

Output

Record image/release identifier, environment, regions, health criteria, canary metrics, approval, and rollback result. Exclude tokens, env values, request bodies, and user data.

Examples

Deploy a staging image to one region with synthetic traffic, simulate a failed health check, and confirm the release stops before traffic expands. Restore the previous release and verify the readiness endpoint remains generic and redacted.

Docker Configuration

FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build

FROM node:20-slim
RUN addgroup --system app && adduser --system --ingroup app app
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
USER app
EXPOSE 8080
CMD ["node", "dist/index.js"]

Fly.io Configuration

# fly.toml
app = "my-integration"
primary_region = "iad"

[build]
  dockerfile = "Dockerfile"

[env]
  LOG_LEVEL = "info"
  PORT = "8080"

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

[[http_service.checks]]
  interval = "30s"
  timeout = "5s"
  grace_period = "10s"
  method = "GET"
  path = "/health"

Environment Variables

export FLY_API_TOKEN="fo1_xxxxxxxxxxxx"
fly secrets set FLYIO_APP_NAME="my-integration"
fly secrets set LOG_LEVEL="info"

Health Check Endpoint

import express from 'express';

const app = express();

app.get('/health', async (req, res) => {
  try {
    const region = process.env.FLY_REGION || 'unknown';
    const appName = process.env.FLY_APP_NAME || 'unknown';
    res.json({ status: 'healthy', service: 'flyio-integration', region, app: appName, timestamp: new Date().toISOString() });
  } catch (error) {
    res.status(503).json({ status: 'unhealthy', error: (error as Error).message });
  }
});

Deployment Steps

Step 1: Build

fly launch --no-deploy

Step 2: Run

fly deploy --strategy rolling

Step 3: Verify

fly status
curl -s https://my-integration.fly.dev/health | jq .

Step 4: Rolling Update

fly deploy --strategy rolling --wait-timeout 300
fly releases --image
fly releases rollback   # if health check fails

Error Handling

Resources

• Fly.io Deploy Docs
• fly.toml Reference

Next Steps

See flyio-webhooks-events.