Fly.io Setup

Overview

Fly.io hosts and executes your Shopify extension deployments. Each generation triggers a Fly.io build that compiles your code and deploys it to Shopify.

Why Fly.io?

Zero Config

Automatic setup

Detects build tools
Configures environment
Manages dependencies
Handles secrets

Fast Builds

Quick deployments

Cached layers
Parallel builds
Instant rollback
Hot reloading

GitHub Integration

Seamless connection

Auto-detects pushes
Branch deployments
PR previews
Commit tracking

Shopify CLI

Built-in tools

Shopify CLI installed
Deploy commands
Extension bundling
Version management

Setup Process

Create Fly.io Account

Go to fly.io
Click “Start a New Project”
Sign in with GitHub
Authorize Fly.io app

Generate Fly.io Token

Create API token:

Go to Account Settings → Tokens
Click “Create New Token”
Name it “Synapse Deployment”
Copy the token

Add Token to Synapse

Configure in dashboard:

Go to Settings → Integrations
Find Fly.io section
Paste API token
Click “Connect Fly.io”

Project Created

Synapse automatically creates:

Fly.io project per user
Service per generation
Environment variables
GitHub integration

Fly.io paid planject Structure

Your Fly.io setup:

Fly.io paid planject: synapse-user-{userId}
├── Service: gen-abc123-delivery-estimate
│   ├── Source: GitHub (user-xxx/synapse-extensions:gen-abc123)
│   ├── Build: buildpacks
│   ├── Environment: Production
│   └── Variables: SHOPIFY_*, RAILWAY_*
├── Service: gen-def456-volume-discount
│   ├── Source: GitHub (user-xxx/synapse-extensions:gen-def456)
│   ├── Build: buildpacks
│   ├── Environment: Production
│   └── Variables: SHOPIFY_*, RAILWAY_*
└── Shared Variables
    ├── SHOPIFY_CLI_PARTNERS_TOKEN
    ├── SHOPIFY_CLIENT_ID
    ├── SHOPIFY_CLIENT_SECRET
    └── SHOPIFY_DEV_STORE_URL

How Fly.io Builds Work

GitHub Push

Code pushed to repository triggers Fly.io

Build Detection

Fly.io uses buildpacks to detect:

Language (Node.js, Rust, etc.)
Package manager (npm, pnpm, yarn)
Build commands
Start commands

Dependency Install

Installs packages:

# For UI extensions
npm install

# For Rust functions
cargo fetch

# Shopify CLI
npm install -g @shopify/cli

Extension Build

Compiles extension:

# UI extensions
npm run build

# Rust functions
cargo build --release
shopify app function build

Shopify Deploy

Deploys to Shopify:

shopify app deploy --force
shopify app release --version=latest --force

Completion

Extension live in your dev store

Environment Variables

Fly.io automatically configures:

Variable	Description	Source
`SHOPIFY_CLIENT_ID`	App client ID	Synapse config
`SHOPIFY_CLIENT_SECRET`	App client secret	Synapse config
`SHOPIFY_CLI_PARTNERS_TOKEN`	Partners API token	Synapse config
`SHOPIFY_DEV_STORE_URL`	Development store	User profile
`FLY_REGION`	Deployment environment	Fly.io
`FLY_APP_NAME`	Service identifier	Fly.io
`FLY_APP_ID`	Project identifier	Fly.io

Adding Custom Variables

Add your own environment variables:

Via Fly.io Dashboard
Via Fly.io CLI
Via fly.toml

Open your Fly.io project
Select service
Go to Variables tab
Click “New Variable”
Enter name and value
Click “Add”
Redeploy service

# Install Fly.io CLI
brew install flyctl

# Login
flyctl auth login

# Link to project
flyctl apps list

# Add variable
flyctl secrets set API_KEY=your-key

# Or from file
flyctl secrets set --file .env

Configure in repository:

{
  "build": {
    "builder": "nixpacks"
  },
  "deploy": {
    "numReplicas": 1,
    "restartPolicyType": "ON_FAILURE"
  },
  "env": {
    "NODE_ENV": "production",
    "LOG_LEVEL": "info"
  }
}

buildpacks Build Configuration

Fly.io uses buildpacks for builds. Customize in fly.toml:

{
  "build": {
    "builder": "nixpacks",
    "buildCommand": "npm run build:custom",
    "watchPatterns": [
      "extensions/**/*.tsx",
      "extensions/**/*.rs"
    ]
  },
  "deploy": {
    "startCommand": "./deploy.sh",
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10,
    "numReplicas": 1,
    "healthcheckPath": "/health",
    "healthcheckTimeout": 300
  }
}

Viewing Logs

Monitor deployments in real-time:

Fly.io Dashboard
Fly.io CLI

Open Fly.io project
Select service
Click “Deployments” tab
Click specific deployment
View build and runtime logs

Log output:

Building...
[nixpacks] Detecting builder...
[nixpacks] Using Node.js builder
[nixpacks] Installing dependencies...
[nixpacks] Running build command...
Building extension: delivery-estimate
✓ Built in 12.3s
Deploying to Shopify...
✓ Deployed version 2024.10.30.1
✓ Released to dev store
Deployment complete!

# View logs
flyctl logs

# Follow logs
flyctl logs --follow

# Filter by deployment
flyctl logs --deployment <deployment-id>

# Export logs
flyctl logs > deployment.log

Managing Services

View All Services

See all deployed services:

# Via CLI
flyctl apps list

# Via dashboard
# Open project → View all services

Each generation gets its own service for isolation

Restart Service

Manually restart a service:

# Via CLI
flyctl apps restart

# Via dashboard
# Service → Settings → Restart Service

Useful for applying new environment variables

Delete Service

Remove unused services:

# Via CLI
flyctl apps destroy <service-id>

# Via dashboard
# Service → Settings → Delete Service

Frees up project resources

Service Metrics

Monitor performance:

CPU usage
Memory consumption
Network traffic
Build duration
Deployment frequency

Available in Fly.io dashboard under Metrics tab

Deployment Strategies

Instant Deploy (Default)
Manual Deploy
PR Previews

Every push triggers immediate deployment:Pros:

Fast feedback
Always up-to-date
No manual steps

Cons:

May deploy broken code
No review process

Best for: Development, rapid iteration

Approve deployments manually:

// fly.toml
{
  "deploy": {
    "requireApproval": true
  }
}

Pros:

Review before deploy
Controlled releases
Prevent mistakes

Cons:

Slower deployment
Manual intervention

Best for: Production, sensitive changes

Cost Management

Fly.io pricing and optimization:

Free Tier

$5 free credit per month
Pauses after 500 hours
Shared resources
Community support

Pro Plan ($20/month)

$20 credit included
Usage-based billing
Dedicated resources
Priority support

Optimization Tips

Remove Unused Services

Delete old generation services to save resources

Use Sleep Mode

Configure services to sleep when inactive

Optimize Builds

Cache dependencies, minimize build time

Monitor Usage

Track resource consumption in dashboard

Advanced Configuration

Custom Dockerfile

Use custom Docker build instead of buildpacks:

# Dockerfile
FROM node:20-alpine

# Install Shopify CLI
RUN npm install -g @shopify/cli

# Copy extension code
WORKDIR /app
COPY . .

# Install dependencies
RUN npm install

# Build extension
RUN npm run build

# Deploy to Shopify
CMD ["shopify", "app", "deploy", "--force"]

Fly.io automatically detects and uses Dockerfile

Multi-Stage Builds

Optimize image size:

# Build stage
FROM node:20 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

# Deploy stage
FROM node:20-alpine
RUN npm install -g @shopify/cli
WORKDIR /app
COPY --from=builder /app/extensions ./extensions
COPY shopify.app.toml .
CMD ["shopify", "app", "deploy", "--force"]

Webhooks

Trigger actions on deployment events:

Service → Settings → Webhooks
Add webhook URL
Select events:
- Deployment started
- Deployment succeeded
- Deployment failed
Receive JSON payload

{
  "event": "deployment.succeeded",
  "project": "synapse-user-123",
  "service": "gen-abc123",
  "deployment": "dep-xyz789",
  "timestamp": "2025-10-30T12:00:00Z"
}

Troubleshooting

Build Failed

Error: Build fails during npm install or compilationCauses:

Missing dependencies
Node version mismatch
Memory limit exceeded

Solutions:

Check package.json

Specify Node version in package.json:

{
  "engines": {
    "node": "20.x"
  }
}

Review build logs for specific errors
Upgrade to Pro plan for more resources

Deployment Timeout

Error: Deployment exceeds time limitCauses:

Large extension bundle
Slow Shopify API
Network issues

Solutions:

Optimize bundle size
Retry deployment

Increase timeout in fly.toml:

{
  "deploy": {
    "healthcheckTimeout": 600
  }
}

Environment Variables Missing

Error: SHOPIFY_CLIENT_ID not foundCauses:

Variables not configured
Service not linked to project

Solutions:

Verify variables in dashboard

Re-add via Fly.io CLI:

flyctl secrets set SHOPIFY_CLIENT_ID=xxx

Redeploy service

Next Steps

GitHub Integration

Configure GitHub connection

Deployment Pipeline

Understand the full pipeline

Debugging

Debug deployment issues

Best Practices

Optimize your workflow

Get Started

Core Concepts

Building Extensions

Building Functions

Development

Deployment

Advanced

Overview

Why Fly.io?

Zero Config

Fast Builds

GitHub Integration

Shopify CLI

Setup Process

Fly.io paid planject Structure

How Fly.io Builds Work

Environment Variables

Adding Custom Variables

buildpacks Build Configuration

Viewing Logs

Managing Services

Deployment Strategies

Cost Management

Free Tier

Pro Plan ($20/month)

Optimization Tips

Remove Unused Services

Use Sleep Mode

Optimize Builds

Monitor Usage

Advanced Configuration

Troubleshooting

Next Steps

GitHub Integration

Deployment Pipeline

Debugging

Best Practices

​Overview

​Why Fly.io?

Zero Config

Fast Builds

GitHub Integration

Shopify CLI

​Setup Process

​Fly.io paid planject Structure

​How Fly.io Builds Work

​Environment Variables

​Adding Custom Variables

​buildpacks Build Configuration

​Viewing Logs

​Managing Services

​Deployment Strategies

​Cost Management

​Free Tier

​Pro Plan ($20/month)

​Optimization Tips

Remove Unused Services

Use Sleep Mode

Optimize Builds

Monitor Usage

​Advanced Configuration

​Troubleshooting

​Next Steps

GitHub Integration

Deployment Pipeline

Debugging

Best Practices

Overview

Why Fly.io?

Setup Process

Fly.io paid planject Structure

How Fly.io Builds Work

Environment Variables

Adding Custom Variables

buildpacks Build Configuration

Viewing Logs

Managing Services

Deployment Strategies

Cost Management

Free Tier

Pro Plan ($20/month)

Optimization Tips

Advanced Configuration

Troubleshooting

Next Steps