Scotty Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/scotty
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Spatie\Scotty\ScottyServiceProvider"
   

2. First Task File: Create Scotty.sh in your project root with a basic task:

   #!/usr/bin/env scotty
   # @servers remote=deployer@your-server.com
   # @task on:remote
   hello() {
       echo "Hello from remote server!"
   }
   

3. Run It:

   scotty run hello
   

Key First Use Cases

• Deployments: Run git pull, composer install, and artisan migrate sequentially.
• Server Maintenance: Execute cleanup tasks (logs, cache) across multiple servers.
• Laravel-Specific: Replace Envoy tasks with Scotty while keeping the same syntax.

Implementation Patterns

Core Workflows

1. Task Definition:

   • Use # @task on:remote for server-side execution.
   • Use # @task on:local for local-only tasks (e.g., composer install).
   • Group tasks with # @macro for reusable workflows:

     # @macro deploy pullCode runMigrations
     

2. Server Management:

   • Define servers in scotty.php config or inline:

     # @servers remote=deployer@server1.com,backup=deployer@server2.com
     

   • Use environment variables for dynamic hostnames:

     # @servers remote=deployer@${SERVER_HOST}
     

3. Laravel Integration:

   • Artisan Commands: Call Scotty from Laravel commands:

     Scotty::run('deploy'); // Runs the 'deploy' macro
     

   • Artisan Tasks: Use Scotty in Artisan::call():

     Artisan::call('scotty:run', ['task' => 'deploy']);
     

4. Parallel Execution:

   • Run tasks on multiple servers in parallel:

     # @servers remote=deployer@server1.com,deployer@server2.com
     # @task on:remote
     syncData() { ... }
     

     Execute with:

     scotty run --parallel syncData
     

Advanced Patterns

• Conditional Tasks: Use if statements in tasks with SSH output checks:

  # @task on:remote
  backupDb() {
      if [ -f "/backup/db.sql" ]; then
          echo "Backup exists. Skipping."
      else
          mysqldump -u user -p db_name > /backup/db.sql
      fi
  }
  

• File Transfers: Use scp-like logic via scotty:

  # @task on:local
  uploadFile() {
      scp local-file.txt deployer@server:/remote/path/
  }
  

• Environment-Specific Tasks: Use .env variables to switch between staging/production:

  # @servers remote=deployer@${APP_SERVER}
  

Gotchas and Tips

Common Pitfalls

1. SSH Key Issues:

   • Ensure ~/.ssh/id_rsa is properly set up or specify keys in scotty.php:

     'ssh' => [
         'key' => '/path/to/private_key',
     ],
     

   • Debug with scotty run --verbose.

2. Task Ordering:

   • Scotty executes tasks top-to-bottom in the file. Use macros to group logically:

     # @macro deploy pullCode installDeps migrate
     

     Avoid relying on implicit ordering.

3. Output Parsing:

   • Remote task output is streamed in real-time. Avoid parsing output mid-execution (e.g., grep in tasks).

4. Local vs. Remote Confusion:

   • # @task on:local runs on your machine; on:remote runs on the server. Mixing them requires explicit file transfers.

Debugging Tips

• Verbose Mode:

  scotty run --verbose deploy
  

  Shows raw SSH commands and output.

• Dry Runs: Use --dry-run to preview commands without execution.

• Logging: Enable Laravel logging for Scotty events in config/scotty.php:

  'log' => true,
  

Extension Points

1. Custom SSH Config: Override SSH options per server:

   # @servers remote=deployer@server.com --port=2222 --timeout=30
   

2. Pre/Post Hooks: Use local tasks to wrap remote execution:

   # @task on:local
   preDeploy() {
       echo "Starting deployment..."
   }
   # @task on:remote
   deploy() { ... }
   # @task on:local
   postDeploy() {
       echo "Deployment complete!";
   }
   

3. Dynamic Servers: Fetch server lists from Laravel models or APIs:

   # @servers remote=$(php artisan server:list)
   

4. Parallelism Limits: Configure max parallel tasks in scotty.php:

   'parallel' => [
       'max_processes' => 4,
   ],
   

Pro Tips

• Template Tasks: Store reusable tasks in separate files and source them:

  #!/usr/bin/env scotty
  source ./tasks/deploy.sh
  source ./tasks/backup.sh
  

• Git Hooks: Integrate Scotty into post-receive hooks for zero-downtime deployments:

  #!/bin/bash
  cd /var/www/app && ./vendor/bin/scotty run deploy
  

• CI/CD: Use Scotty in GitHub Actions/GitLab CI for remote deployments:

  - name: Deploy
    run: ./vendor/bin/scotty run deploy