373 lines
7.8 KiB
Markdown
373 lines
7.8 KiB
Markdown
# 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/)
|