Forge Cli Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer global require laravel/forge-cli
   

   Ensure ~/.composer/vendor/bin is in your PATH or use the full path to forge commands.

2. Authentication:

   forge auth login
   

   Follow prompts to authenticate via Forge’s web interface (opens in browser).

3. First Command:

   forge server list
   

   Verify connection by listing existing servers.

First Use Case: Deploying a Laravel App

forge create:server --name="prod-server" --server=linode --plan=1gb
forge site:create --name="myapp" --server=prod-server --repo="git@github.com:user/repo.git"
forge site:deploy --site="myapp"

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline: Use Forge CLI in GitHub Actions/GitLab CI to automate deployments:

   - name: Deploy to Forge
     run: forge site:deploy --site="$SITE_NAME" --branch="$CI_COMMIT_REF_NAME"
   

2. Local Development → Production:

   # Local: Commit changes
   git push origin main
   
   # Remote: Trigger deployment
   forge site:deploy --site="myapp" --branch="main"
   

3. Server Management:

   # Provision a new server
   forge server:create --name="staging" --server=digitalocean --plan=2gb
   
   # Configure PHP version
   forge server:php --version=8.2 --server="staging"
   
   # Set up SSL
   forge ssl:install --server="staging" --site="myapp"
   

Common Patterns

• Environment Sync:

  forge site:env --site="myapp" --key="APP_ENV" --value="production"
  

• Database Management:

  forge database:create --name="myapp_db" --server="prod-server"
  forge database:user --name="myapp_user" --password="securepass" --server="prod-server"
  

• Scheduled Tasks:

  forge cron:add --site="myapp" --command="php artisan schedule:run >> /dev/null 2>&1" --minute="*"
  

Forge CLI + Laravel Artisan

Combine Forge CLI with Laravel’s artisan for post-deploy tasks:

forge site:deploy --site="myapp" && ssh user@server "cd /sites/myapp && php artisan migrate --force"

Gotchas and Tips

Pitfalls

1. Authentication Caching:

   • If forge auth login fails, clear cached credentials:

     forge auth logout
     forge auth login
     

   • Tip: Use forge auth:token to manually set a token if API issues arise.

2. Server Provider Quirks:

   • Linode/DigitalOcean plans may have different naming conventions. Verify with:

     forge server:plans --server=linode
     

   • Gotcha: Some providers require SSH keys pre-configured in their dashboard.

3. Deployment Failures:

   • Check logs with:

     forge site:logs --site="myapp"
     

   • Tip: Use --verbose flag for detailed output:

     forge site:deploy --site="myapp" --verbose
     

4. Environment Variables:

   • Forge CLI does not override .env files directly. Use:

     forge site:env --site="myapp" --key="DB_PASSWORD" --value="newpass"
     

   • Gotcha: Ensure APP_KEY is set via Forge or manually in .env.

5. SSH Key Management:

   • If SSH fails, regenerate keys in Forge’s UI and re-add them to your server provider.

Debugging

• Dry Runs: Use --dry-run to preview changes (where supported):

  forge server:php --version=8.1 --server="test-server" --dry-run
  

• API Debugging: Enable Forge CLI’s debug mode:

  forge --debug server:list
  

Extension Points

1. Custom Scripts: Add post-deploy hooks via Forge’s UI under Site > Deployment Scripts or use:

   forge site:script --site="myapp" --type="post-deploy" --content="php artisan optimize"
   

2. Webhooks: Trigger Forge CLI commands via Forge’s webhook events (e.g., post-deploy):

   # Example: Run after a Git push
   forge site:deploy --site="myapp" --branch="main" --webhook-trigger
   

3. Local Testing: Use forge local (if supported) to mirror server configs locally:

   forge local:config --server="prod-server" --output="forge-config.php"
   

Configuration Quirks

• PHP Extensions: Extensions must be enabled via Forge’s UI or CLI before deployment:

  forge server:php --extensions="redis,opcache" --server="prod-server"
  

• Nginx Configs: Custom Nginx rules require editing via Forge’s UI or:

  forge site:nginx --site="myapp" --custom-config="path/to/custom.conf"
  

• Queue Workers: Manage workers via Forge CLI:

  forge queue:worker --site="myapp" --daemon --queue="high,default"