@deftai/directive-content 0.55.0

package/deployments/fly-io/via-flyctl.md

@@ -0,0 +1,653 @@
+# Deploy via flyctl CLI
+
+The primary and recommended method for deploying applications to Fly.io. The `flyctl` CLI provides complete control over your applications from creation through scaling and monitoring.
+
+## Overview
+
+`flyctl` (or `fly`) is Fly.io's command-line tool that enables:
+- **App Deployment**: Deploy containers from source or Dockerfile
+- **Configuration Management**: Manage fly.toml and secrets
+- **Multi-Region Deployment**: Deploy globally with one command
+- **Real-Time Monitoring**: View logs, metrics, and status
+- **Database Management**: Create and manage Fly Postgres
+
+## Installation
+
+### macOS
+
+```bash
+# Using Homebrew
+brew install flyctl
+
+# Or using install script
+curl -L https://fly.io/install.sh | sh
+```
+
+### Linux
+
+```bash
+# Install script
+curl -L https://fly.io/install.sh | sh
+
+# Add to PATH
+export FLYCTL_INSTALL="/home/user/.fly"
+export PATH="$FLYCTL_INSTALL/bin:$PATH"
+```
+
+### Windows (PowerShell)
+
+```powershell
+# Run in PowerShell
+iwr https://fly.io/install.ps1 -useb | iex
+```
+
+### Verify Installation
+
+```bash
+flyctl version
+fly version  # 'fly' is an alias for 'flyctl'
+```
+
+## Quick Start
+
+### 1. Sign Up / Login
+
+```bash
+# Create account and login
+fly auth signup
+
+# Or login to existing account
+fly auth login
+
+# Verify authentication
+fly auth whoami
+```
+
+### 2. Launch Your First App
+
+```bash
+# Navigate to your project directory
+cd my-app
+
+# Launch app (interactive setup)
+fly launch
+
+# This will:
+# - Detect your app type
+# - Generate fly.toml configuration
+# - Create a Dockerfile if needed
+# - Deploy your app
+```
+
+### 3. Deploy Updates
+
+```bash
+# Deploy changes
+fly deploy
+
+# Deploy with specific Dockerfile
+fly deploy --dockerfile Dockerfile.production
+
+# Deploy with remote builder (no local Docker needed)
+fly deploy --remote-only
+```
+
+## Core Commands
+
+### Application Management
+
+```bash
+# Create new app
+fly apps create my-app
+
+# List your apps
+fly apps list
+
+# Show app status
+fly status
+
+# Open app in browser
+fly open
+
+# Destroy app
+fly apps destroy my-app
+```
+
+### Deployment
+
+```bash
+# Standard deployment
+fly deploy
+
+# Deploy from specific directory
+fly deploy --config /path/to/fly.toml
+
+# Deploy with build arguments
+fly deploy --build-arg API_VERSION=v2
+
+# Deploy specific image
+fly deploy --image registry.example.com/my-app:latest
+
+# No cache build
+fly deploy --no-cache
+```
+
+### Configuration
+
+```bash
+# View current configuration
+fly config show
+
+# Edit configuration
+fly config edit
+
+# Validate fly.toml
+fly config validate
+
+# Save current config
+fly config save
+```
+
+### Secrets Management
+
+```bash
+# Set secret
+fly secrets set DATABASE_URL=postgres://...
+
+# Set multiple secrets
+fly secrets set API_KEY=abc123 SECRET_TOKEN=xyz789
+
+# Import secrets from file
+fly secrets import < .env.production
+
+# List secrets (values hidden)
+fly secrets list
+
+# Remove secret
+fly secrets unset API_KEY
+```
+
+### Scaling
+
+```bash
+# Show current scale
+fly scale show
+
+# Scale machine count
+fly scale count 3
+
+# Scale to specific regions
+fly scale count 2 --region iad,lhr
+
+# Scale machine size
+fly scale vm shared-cpu-2x
+
+# Scale memory
+fly scale memory 512
+
+# Autoscaling
+fly autoscale set min=1 max=10
+```
+
+### Regions & Multi-Region
+
+```bash
+# List available regions
+fly platform regions
+
+# Add region
+fly regions add lhr  # London
+
+# Remove region
+fly regions remove lhr
+
+# Set backup region
+fly regions backup iad
+
+# Deploy to multiple regions
+fly scale count 3 --region iad,lhr,syd
+```
+
+## fly.toml Configuration
+
+### Basic Configuration
+
+```toml
+# Application name
+app = "my-app"
+
+# Primary region
+primary_region = "iad"
+
+# Build configuration
+[build]
+  dockerfile = "Dockerfile"
+  # Or use buildpacks
+  # builder = "paketobuildpacks/builder:base"
+
+# Environment variables
+[env]
+  NODE_ENV = "production"
+  PORT = "8080"
+
+# HTTP service
+[[services]]
+  protocol = "tcp"
+  internal_port = 8080
+
+  [[services.ports]]
+    port = 80
+    handlers = ["http"]
+
+  [[services.ports]]
+    port = 443
+    handlers = ["http", "tls"]
+
+  # Health checks
+  [services.http_checks]
+    interval = "10s"
+    timeout = "2s"
+    grace_period = "5s"
+    method = "GET"
+    path = "/health"
+```
+
+### Advanced Configuration
+
+```toml
+app = "advanced-app"
+primary_region = "iad"
+
+# Autoscaling
+[autoscaling]
+  min_machines = 1
+  max_machines = 10
+
+# Processes (multiple process types)
+[processes]
+  web = "npm run start"
+  worker = "npm run worker"
+
+# Metrics
+[metrics]
+  port = 9091
+  path = "/metrics"
+
+# Volumes
+[mounts]
+  source = "data"
+  destination = "/data"
+
+# Private network
+[private_network]
+  name = "my-app-net"
+
+# Deploy configuration
+[deploy]
+  release_command = "npm run migrate"
+  strategy = "rolling"
+  
+  [deploy.max_unavailable]
+    count = 1
+
+# HTTP service with caching
+[[services]]
+  internal_port = 8080
+  protocol = "tcp"
+
+  [[services.ports]]
+    handlers = ["http"]
+    port = 80
+    force_https = true
+
+  [[services.ports]]
+    handlers = ["tls", "http"]
+    port = 443
+
+  # Concurrency limits
+  [services.concurrency]
+    type = "connections"
+    hard_limit = 200
+    soft_limit = 100
+
+  # TCP checks
+  [[services.tcp_checks]]
+    interval = "15s"
+    timeout = "2s"
+    grace_period = "5s"
+```
+
+## Advanced Features
+
+### Fly Machines API
+
+```bash
+# List machines
+fly machines list
+
+# Create machine
+fly machines run nginx
+
+# Stop machine
+fly machines stop MACHINE_ID
+
+# Start machine
+fly machines start MACHINE_ID
+
+# Clone machine
+fly machines clone MACHINE_ID
+
+# Remove machine
+fly machines remove MACHINE_ID
+```
+
+### Volumes (Persistent Storage)
+
+```bash
+# Create volume
+fly volumes create data --region iad --size 10
+
+# List volumes
+fly volumes list
+
+# Extend volume
+fly volumes extend VOLUME_ID --size 20
+
+# Snapshot volume
+fly volumes snapshots create VOLUME_ID
+
+# Restore from snapshot
+fly volumes create data --snapshot-id SNAPSHOT_ID
+```
+
+### Postgres Database
+
+```bash
+# Create Postgres cluster
+fly postgres create
+
+# Attach to app
+fly postgres attach MY_POSTGRES_APP
+
+# Connect to database
+fly postgres connect
+
+# List databases
+fly postgres db list
+
+# Create database
+fly postgres db create mydb
+
+# Show connection string
+fly postgres config show
+```
+
+### Private Networking
+
+```bash
+# Create private network
+fly wireguard create
+
+# Add peer
+fly wireguard peer add
+
+# List peers
+fly wireguard list
+
+# Connect via WireGuard
+fly proxy 5432:5432 -a my-postgres-app
+```
+
+### SSH & Console Access
+
+```bash
+# SSH into running instance
+fly ssh console
+
+# SSH with specific command
+fly ssh console -C "ls -la"
+
+# Open Rails console
+fly ssh console --pty -C "rails console"
+
+# Run one-off command
+fly ssh console -C "bin/rails db:migrate"
+```
+
+## Monitoring & Debugging
+
+### Logs
+
+```bash
+# Stream logs
+fly logs
+
+# Filter by region
+fly logs --region iad
+
+# Show specific number of lines
+fly logs -n 100
+
+# Search logs
+fly logs | grep ERROR
+```
+
+### Metrics & Monitoring
+
+```bash
+# Open Grafana dashboard
+fly dashboard
+
+# Show metrics
+fly dashboard metrics
+
+# VM status
+fly status --all
+
+# Check health
+fly checks list
+```
+
+### Debugging
+
+```bash
+# View deployment history
+fly releases
+
+# Rollback to previous version
+fly releases rollback
+
+# Show app info
+fly info
+
+# Check app health
+fly status
+
+# Test connectivity
+fly ping
+```
+
+## Deployment Strategies
+
+### Blue-Green Deployment
+
+```bash
+# Deploy new version
+fly deploy --strategy bluegreen
+
+# Or configure in fly.toml
+[deploy]
+  strategy = "bluegreen"
+```
+
+### Canary Deployment
+
+```bash
+# Deploy to limited machines first
+fly deploy --strategy canary
+
+# Manual canary
+fly scale count 1 --region iad  # Deploy to one region
+# Verify, then scale up
+fly scale count 3 --region iad,lhr,syd
+```
+
+### Rolling Deployment
+
+```toml
+# fly.toml
+[deploy]
+  strategy = "rolling"
+  max_unavailable = 1  # One at a time
+```
+
+## Best Practices
+
+### 1. Use fly.toml in Version Control
+
+```bash
+# Generate fly.toml
+fly launch --no-deploy
+
+# Commit to git
+git add fly.toml
+git commit -m "Add Fly.io configuration"
+```
+
+### 2. Manage Secrets Properly
+
+```bash
+# Never commit secrets to git
+echo ".env" >> .gitignore
+
+# Use fly secrets for production
+fly secrets set $(cat .env.production | xargs)
+```
+
+### 3. Health Checks
+
+```toml
+[[services]]
+  # Always configure health checks
+  [[services.http_checks]]
+    interval = "10s"
+    timeout = "2s"
+    method = "GET"
+    path = "/health"
+    protocol = "http"
+```
+
+### 4. Multi-Region for High Availability
+
+```bash
+# Deploy to multiple regions
+fly regions add iad lhr syd
+
+# Verify distribution
+fly status --all
+```
+
+### 5. Use Volumes for Persistent Data
+
+```bash
+# Create volume before first deploy
+fly volumes create data --region iad
+
+# Mount in fly.toml
+[mounts]
+  source = "data"
+  destination = "/data"
+```
+
+## Troubleshooting
+
+### Deployment Fails
+
+```bash
+# Check build logs
+fly logs --timestamps
+
+# Deploy with verbose output
+fly deploy --verbose
+
+# Check app status
+fly status
+
+# View recent events
+fly events
+```
+
+### App Not Responding
+
+```bash
+# Check if instances are running
+fly status --all
+
+# Restart all instances
+fly restart
+
+# Scale up
+fly scale count 2
+```
+
+### Connection Issues
+
+```bash
+# Test DNS
+dig my-app.fly.dev
+
+# Check certificates
+fly certs show
+
+# Verify routing
+fly ips list
+```
+
+### High Memory Usage
+
+```bash
+# Check current usage
+fly status
+
+# Scale memory
+fly scale memory 1024
+
+# Or upgrade VM
+fly scale vm dedicated-cpu-2x
+```
+
+## Common Workflows
+
+### Deploy from CI/CD
+
+```bash
+# Non-interactive deploy
+fly deploy --remote-only --now
+```
+
+### Database Migration
+
+```bash
+# Run migration before deployment
+[deploy]
+  release_command = "rails db:migrate"
+
+# Or manually
+fly ssh console -C "npm run migrate"
+```
+
+### Environment-Specific Deployments
+
+```bash
+# Use different fly.toml files
+fly deploy --config fly.staging.toml
+fly deploy --config fly.production.toml
+```
+
+## References
+
+- [flyctl CLI Reference](https://fly.io/docs/flyctl/)
+- [fly.toml Configuration](https://fly.io/docs/reference/configuration/)
+- [Deployment Guide](https://fly.io/docs/reference/deployment/)
+- [Fly Machines](https://fly.io/docs/machines/)
+- [Troubleshooting](https://fly.io/docs/getting-started/troubleshooting/)