infra

2026-07-31 11:47:31 +09:00
parent d338b91e42
commit 3271693051
14 changed files with 3024 additions and 0 deletions
@@ -0,0 +1,372 @@
+# Deploying LinkForty to Fly.io
+
+This guide walks you through deploying LinkForty to [Fly.io](https://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**
+   ```bash
+   # macOS/Linux
+   curl -L https://fly.io/install.sh | sh
+
+   # Windows
+   iwr https://fly.io/install.ps1 -useb | iex
+   ```
+
+3. **Authenticate**
+   ```bash
+   fly auth login
+   ```
+
+4. **LinkForty Built Locally**
+   ```bash
+   npm install
+   npm run build
+   ```
+
+## Step 1: Customize Configuration
+
+1. Edit `infra/fly.io/fly.toml`:
+   ```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+.
+
+```bash
+# 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](https://supabase.com) or another managed PostgreSQL provider and set `DATABASE_URL` manually (see Step 5).
+
+📖 Detailed PostgreSQL setup: [fly.postgres.md](./fly.postgres.md)
+
+## Step 3: Create Redis Cache (Optional but Recommended)
+
+Redis improves performance by ~90% for repeated link lookups.
+
+```bash
+# 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](./fly.redis.md)
+
+## Step 4: Create Your Fly.io App
+
+From the root of your LinkForty project:
+
+```bash
+# 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)
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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:
+```bash
+curl -L https://your-app.fly.dev/abc123
+```
+
+## Scaling Your Deployment
+
+### Vertical Scaling (More Resources Per Machine)
+
+Edit `fly.toml`:
+```toml
+[vm]
+  cpu_kind = "shared"    # or "performance" for dedicated CPUs
+  cpus = 2
+  memory_mb = 512        # or 1024, 2048, etc.
+```
+
+Then deploy:
+```bash
+fly deploy
+```
+
+### Horizontal Scaling (More Machines)
+
+```bash
+# 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:
+```toml
+[[regions]]
+name = "iad"  # US East
+[[regions]]
+name = "lhr"  # Europe
+[[regions]]
+name = "nrt"  # Asia
+```
+
+Deploy:
+```bash
+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:
+```bash
+# SSH into a machine
+fly ssh console
+
+# Run migrations
+npm run migrate
+
+# Exit
+exit
+```
+
+## Monitoring and Logs
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```typescript
+// In your Fastify setup
+fastify.get('/health', async (request, reply) => {
+  return { status: 'ok' };
+});
+```
+
+Check `fly.toml` health check path matches.
+
+### Database Connection Issues
+
+```bash
+# 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`:
+```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
+
+```bash
+# 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:**
+```bash
+fly billing show
+```
+
+## Security Checklist
+
+Before going to production, review [SECURITY.md](./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](./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](../../SECURITY.md)
+
+## Resources
+
+- [Fly.io Pricing](https://fly.io/docs/about/pricing/)
+- [Fly.io Regions](https://fly.io/docs/reference/regions/)
+- [Fly.io Node.js Guide](https://fly.io/docs/languages-and-frameworks/node/)
+- [Fly.io PostgreSQL](https://fly.io/docs/postgres/)