linkforty/infra/fly.io/DEPLOYMENT.md

Deploying LinkForty to Fly.io

This guide walks you through deploying LinkForty to Fly.io, a global application platform that makes deployment simple.

Prerequisites

1. Fly.io Account

   • Sign up at https://fly.io/app/sign-up
   • Credit card required (but has generous free tier)

2. Fly CLI Installed

   # macOS/Linux
   curl -L https://fly.io/install.sh | sh
   
   # Windows
   iwr https://fly.io/install.ps1 -useb | iex
   

3. Authenticate

   fly auth login
   

4. LinkForty Built Locally

   npm install
   npm run build
   

Step 1: Customize Configuration

1. Edit infra/fly.io/fly.toml:

   app = "your-unique-app-name"  # Must be globally unique
   primary_region = "iad"         # Choose your region
   

2. Available regions (run fly platform regions for full list):

   • iad - Washington DC (US East)
   • lax - Los Angeles (US West)
   • lhr - London (Europe)
   • fra - Frankfurt (Europe)
   • syd - Sydney (Asia-Pacific)
   • nrt - Tokyo (Asia-Pacific)

Step 2: Create PostgreSQL Database

LinkForty requires PostgreSQL 13+.

# Create a Postgres cluster
fly postgres create --name linkforty-db --region iad

# Choose configuration when prompted:
# - Development: 1GB RAM, 10GB storage (free tier eligible)
# - Production: 2GB+ RAM, 20GB+ storage

# Attach database to your app
fly postgres attach linkforty-db --app your-unique-app-name

This automatically sets the DATABASE_URL secret in your app.

Alternative: Use Supabase or another managed PostgreSQL provider and set DATABASE_URL manually (see Step 5).

📖 Detailed PostgreSQL setup: fly.postgres.md

Step 3: Create Redis Cache (Optional but Recommended)

Redis improves performance by ~90% for repeated link lookups.

# Create Upstash Redis (Fly's Redis partner)
fly redis create --name linkforty-redis --region iad

# Choose plan when prompted:
# - Development: Free tier (256MB)
# - Production: Eviction-$10 or Eviction-$40

# Note the REDIS_URL provided - you'll set it in Step 5

📖 Detailed Redis setup: fly.redis.md

Step 4: Create Your Fly.io App

From the root of your LinkForty project:

# Copy fly.toml to root directory
cp infra/fly.io/fly.toml fly.toml

# Create the app (don't deploy yet)
fly apps create your-unique-app-name --org personal

Step 5: Set Secrets (Environment Variables)

# DATABASE_URL (automatically set if you used fly postgres attach)
# If using external PostgreSQL:
fly secrets set DATABASE_URL="postgresql://user:password@host:5432/dbname?sslmode=require"

# REDIS_URL (from Step 3 output)
fly secrets set REDIS_URL="redis://default:password@host:6379"

# CORS Origin (your frontend domain)
fly secrets set CORS_ORIGIN="https://yourdomain.com"

# Optional: Custom port (defaults to 8080)
fly secrets set PORT="8080"

# View configured secrets (values are hidden)
fly secrets list

⚠️ Security Note: Never commit secrets to git. Use fly secrets set only.

Step 6: Initial Deployment

# Deploy from the root directory (where fly.toml is located)
fly deploy

# This will:
# 1. Build your Docker image
# 2. Push to Fly.io registry
# 3. Run migrations (via release_command in fly.toml)
# 4. Deploy to your chosen region(s)
# 5. Start health checks

First deployment takes 3-5 minutes. Subsequent deployments are faster.

Step 7: Verify Deployment

# Check app status
fly status

# View recent logs
fly logs

# Open your app in browser
fly open

# Test the health endpoint
curl https://your-app.fly.dev/health

Step 8: Create Your First Link

# Using curl
curl -X POST https://your-app.fly.dev/api/links \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-123",
    "iosUrl": "myapp://product/123",
    "androidUrl": "myapp://product/123",
    "webUrl": "https://mysite.com/product/123"
  }'

# Response includes your short code
# {"code":"abc123","shortUrl":"https://your-app.fly.dev/abc123"}

Test the redirect:

curl -L https://your-app.fly.dev/abc123

Scaling Your Deployment

Vertical Scaling (More Resources Per Machine)

Edit fly.toml:

[vm]
  cpu_kind = "shared"    # or "performance" for dedicated CPUs
  cpus = 2
  memory_mb = 512        # or 1024, 2048, etc.

Then deploy:

fly deploy

Horizontal Scaling (More Machines)

# Scale to 3 machines in primary region
fly scale count 3

# Or use auto-scaling (edit fly.toml first)
# Uncomment the [[services.autoscaling]] section
fly deploy

Multi-Region Deployment

Edit fly.toml to uncomment regions:

[[regions]]
name = "iad"  # US East
[[regions]]
name = "lhr"  # Europe
[[regions]]
name = "nrt"  # Asia

Deploy:

fly deploy

Fly.io automatically routes users to the nearest region.

Database Migrations

Migrations run automatically on deploy (via release_command in fly.toml).

To run manually:

# SSH into a machine
fly ssh console

# Run migrations
npm run migrate

# Exit
exit

Monitoring and Logs

# Real-time logs
fly logs

# Filter by app instance
fly logs -i instance-id

# View metrics dashboard
fly dashboard

# Check machine status
fly status

# View recent deployments
fly releases

Troubleshooting

Deployment Fails

# Check build logs
fly logs --app your-app

# Verify secrets are set
fly secrets list

# Check app configuration
fly config show

Health Checks Failing

Ensure your app exposes /health endpoint:

// In your Fastify setup
fastify.get('/health', async (request, reply) => {
  return { status: 'ok' };
});

Check fly.toml health check path matches.

Database Connection Issues

# Verify DATABASE_URL is set
fly secrets list

# Check database status
fly postgres status linkforty-db

# View database connection info
fly postgres db list linkforty-db

Out of Memory Errors

Increase memory allocation in fly.toml:

[vm]
  memory_mb = 512  # Increase from 256

High Latency

Consider:

• Enabling Redis cache (see Step 3)
• Multi-region deployment
• Increasing machine resources
• Database connection pooling (already configured)

Updating Your Deployment

# After making code changes:
npm run build
fly deploy

# To rollback to previous version:
fly releases
fly releases rollback <version>

Cost Optimization

Free Tier Eligible Setup:

• 1x shared-cpu-1x machine (256MB) = Free
• Fly Postgres (1GB, development tier) = Free
• Upstash Redis (256MB) = Free
• Total: $0/month for low-traffic apps

Small Production Setup (~$10-15/month):

• 1x shared-cpu-1x (512MB) = ~$3.50/month
• Fly Postgres (2GB) = ~$7/month
• Upstash Redis (Eviction-$10) = ~$10/month
• Total: ~$20/month

View your costs:

fly billing show

Security Checklist

Before going to production, review SECURITY.md for:

• Environment variable security
• Database SSL configuration
• CORS settings
• Secret rotation
• Backup strategy

Next Steps

• Set up custom domain: https://fly.io/docs/app-guides/custom-domains-with-fly/
• Configure TLS certificates: Automatic with Fly.io
• Set up monitoring alerts: https://fly.io/docs/reference/metrics/
• Enable database backups: See fly.postgres.md

Getting Help

• Fly.io Docs: https://fly.io/docs/
• Fly.io Community: https://community.fly.io/
• LinkForty Issues: https://github.com/yourusername/linkforty-core/issues
• Security Issues: See SECURITY.md

Resources

• Fly.io Pricing
• Fly.io Regions
• Fly.io Node.js Guide
• Fly.io PostgreSQL