Scotty Laravel Package

Getting Started

Minimal Steps

1. Install Scotty:

   curl -L https://github.com/spatie/scotty/releases/latest/download/scotty -o scotty
   chmod +x scotty
   

   Place it in your project root or add to $PATH.

2. Create a Scotty.sh file:

   touch Scotty.sh
   

   Add a basic server definition:

   #!/usr/bin/env scotty
   # @servers remote=deployer@your-server.com
   

3. Verify SSH connection:

   ./scotty doctor
   

4. First task:

   # @task on:remote
   testConnection() {
       echo "Hello from remote!"
   }
   

   Run it:

   ./scotty run testConnection
   

First Use Case

Automate a Laravel deployment:

# @servers production=deployer@prod-server.com
# @macro deploy pullCode runMigrations restartServices

# @task on:production
pullCode() {
    cd /var/www/laravel-app
    git pull origin main
}

# @task on:production
runMigrations() {
    cd /var/www/laravel-app
    php artisan migrate --force
}

# @task on:production
restartServices() {
    sudo systemctl restart nginx
    sudo systemctl restart php-fpm
}

Run with:

./scotty run deploy

Implementation Patterns

Workflows

1. Modular Deployments:

   • Split tasks into logical functions (e.g., deploy, rollback, backup).
   • Use macros to chain them:

     # @macro fullDeploy deploy backup rollbackSafetyNet
     

2. Environment-Specific Configs:

   • Define servers and paths per environment:

     # @servers staging=deployer@staging.example.com production=deployer@prod.example.com
     

   • Use options to switch environments:

     # @option env=staging
     

     Run with:

     ./scotty run deploy --env=production
     

3. Laravel-Specific Tasks:

   • Cache clearing, queue restarts, or artisan commands:

     # @task on:remote
     optimizeApp() {
         cd $APP_DIR
         php artisan optimize:clear
         php artisan config:cache
     }
     

4. Local Development:

   • Use 127.0.0.1 for local testing:

     # @servers local=127.0.0.1
     # @task on:local
     testLocally() {
         php artisan test
     }
     

Integration Tips

• Version Control: Commit Scotty.sh to your repo for team consistency.

• CI/CD: Trigger Scotty from GitHub Actions or GitLab CI:

  - name: Deploy
    run: ./scotty run deploy --branch=$CI_COMMIT_REF_NAME
  

• SSH Config: Leverage ~/.ssh/config for complex setups (e.g., jump hosts):

  # @servers prod=prod-server
  

  (Ensure prod-server is defined in ~/.ssh/config.)

• Blade Templates: For dynamic scripts, use Blade syntax (e.g., @if(env('APP_ENV') === 'local')).

• Error Handling: Use set -e in tasks to exit on failure:

  # @task on:remote
  deploy() {
      set -e
      cd $APP_DIR
      git pull origin $BRANCH || exit 1
  }
  

Gotchas and Tips

Pitfalls

1. SSH Key Issues:

   • Ensure ~/.ssh/id_rsa.pub is added to authorized_keys on remote servers.
   • Debug with scotty doctor --verbose.

2. Path Repetition:

   • Avoid hardcoding paths. Use variables:

     APP_DIR="/var/www/my-app"
     

   • Gotcha: Forgetting to update variables when paths change.

3. Task Dependencies:

   • Scotty stops on failure by default. Use --continue to bypass:

     ./scotty run deploy --continue
     

   • Tip: Add || exit 1 to critical tasks to enforce failure handling.

4. Option Conflicts:

   • Undeclared options (@option) are rejected. Always declare them:

     # @option branch=main
     

   • Gotcha: Typos in option names break execution.

5. Blade vs. Bash:

   • @option directives are ignored in Blade files. Use environment variables instead:

     # In Blade:
     @set('branch', env('BRANCH', 'main'))
     

6. Pretend Mode:

   • Use --pretend to dry-run, but verify SSH commands manually for complex setups.

Debugging

• Verbose Output:

  ./scotty run deploy --verbose
  

• Task Isolation: Run tasks individually to pinpoint failures:

  ./scotty run pullCode
  

• SSH Debugging: Add -vvv to SSH commands in tasks to debug connections:

  # @task on:remote
  debugSSH() {
      ssh -vvv deployer@your-server.com "echo 'Connected!'"
  }
  

Tips

1. Aliases: Add Scotty to your shell config for convenience:

   alias scotty='./scotty'
   

2. Template Files: Use scotty init to scaffold new files:

   ./scotty init --format=bash --server=deployer@new-server.com
   

3. Pause/Resume: Press p during execution to pause and inspect the server state.

4. Summary Mode: Use --summary for quick CI/CD feedback:

   ./scotty run deploy --summary
   

5. Macro Reuse: Define reusable macros for common patterns (e.g., backup, restart):

   # @macro backup
   #   @task on:remote
   #   backupDB() { ... }
   #   @task on:remote
   #   backupFiles() { ... }
   

6. Local Testing: Use 127.0.0.1 for local tasks to avoid SSH overhead:

   # @servers local=127.0.0.1
   # @task on:local
   testArtisan() {
       php artisan --version
   }
   

7. Environment Variables: Pass secrets via environment variables (e.g., DB_PASSWORD):

   # @task on:remote
   deploy() {
       export DB_PASSWORD="$DB_PASSWORD"
       php artisan migrate
   }
   

   Run with:

   DB_PASSWORD=secret ./scotty run deploy
   

8. Confirmations: Add confirm to critical tasks to prevent accidents:

   # @task on:remote confirm="Are you sure? (y/n)"
   deleteData() {
       rm -rf /tmp/old-data
   }