Scotty Laravel Package

Technical Evaluation

Architecture Fit

• Laravel/PHP Ecosystem Alignment: Scotty is a drop-in replacement for Laravel Envoy, leveraging the same task runner philosophy but with a modern, SSH-focused approach. This makes it a natural fit for Laravel-based deployments, CI/CD pipelines, or any PHP project requiring remote server automation.
• Task Orchestration: The macro-based workflow (e.g., @macro deploy pullCode runComposer) aligns well with Laravel’s Artisan task chaining and service provider bootstrapping, enabling seamless integration into existing Laravel workflows.
• SSH-Centric Design: Unlike Envoy (which relies on Blade templates), Scotty uses plain Bash with annotations, reducing complexity for teams already familiar with SSH scripting. This is particularly valuable for legacy PHP systems or non-Laravel PHP projects where Blade isn’t used.

Integration Feasibility

• Minimal Laravel Dependency: Scotty is language-agnostic (works with any SSH-accessible server) but Laravel-friendly due to its Envoy compatibility. A TPM can integrate it into:
  • Laravel Deployments: Replace envoy:run with scotty run deploy in artisan commands or CI scripts.
  • CI/CD Pipelines: Use Scotty as a pre-deploy step in GitHub Actions, GitLab CI, or Jenkins (via SSH keys).
  • Local Development: Automate homestead/valet provisioning or forge server tasks.
• Tooling Compatibility:
  • Works with Laravel Forge, Envoyer, or custom VPS setups.
  • Supports SSH config files (~/.ssh/config) for complex auth (e.g., jump hosts, key-based auth).
  • No PHP dependencies: Runs as a standalone PHAR, reducing bloat in Laravel’s vendor/ directory.

Technical Risk

• SSH Configuration Overhead:
  • Risk: Teams may need to standardize SSH configs (e.g., ~/.ssh/config) for multi-server setups.
  • Mitigation: Document SSH setup as part of onboarding (e.g., scotty doctor for validation).
• Bash vs. Blade Tradeoffs:
  • Risk: Scotty’s Bash format lacks Blade’s templating (e.g., dynamic server lists from config).
  • Mitigation: Use environment variables or Bash includes (source) for dynamic paths.
• Error Handling:
  • Risk: Scotty stops on failure by default, which may break CI pipelines expecting non-zero exits.
  • Mitigation: Use --continue flag or wrap Scotty calls in CI scripts with set +e.
• Debugging Complexity:
  • Risk: Debugging failed tasks requires manual SSH inspection if Scotty’s output isn’t sufficient.
  • Mitigation: Log task outputs to a file (scotty run deploy > deploy.log) or use --pretend for dry runs.

Key Questions for the TPM

1. Deployment Strategy:
   • Will Scotty replace Envoy, Deployer, or custom SSH scripts? If mixed, how will conflicts (e.g., overlapping tasks) be resolved?
2. Security:
   • How will SSH keys be managed (e.g., CI secrets, user-specific keys)? Will scotty doctor be integrated into pre-deploy checks?
3. CI/CD Integration:
   • Should Scotty tasks be gated (e.g., require manual approval for production) or fully automated?
4. Team Adoption:
   • Will developers need Bash proficiency? If not, consider providing pre-written Scotty.sh templates for common workflows (e.g., Laravel deployments).
5. Monitoring:
   • How will task success/failure be logged (e.g., Laravel’s logs/deploy.log or a third-party tool like Sentry)?

Integration Approach

Stack Fit

• Primary Use Cases:
  • Laravel Deployments: Replace envoy:run with Scotty for SSH-based deployments (e.g., scotty run deploy in artisan or CI).
  • Server Automation: Automate post-deploy tasks (e.g., cache clearing, queue restarts) without manual SSH.
  • Multi-Server Workflows: Manage load-balanced servers or database replicas with @servers annotations.
• Complementary Tools:
  • Laravel Forge/Envoyer: Use Scotty for custom tasks not covered by Forge’s UI.
  • GitHub Actions: Invoke Scotty via SSH from CI (e.g., scotty run deploy --branch=${{ github.ref_name }}).
  • Laravel Telescope: Log Scotty task outputs to Telescope for auditing.

Migration Path

1. Pilot Phase:
   • Replace one critical SSH workflow (e.g., production deployments) with Scotty.
   • Example: Migrate from a custom deploy.sh script to Scotty.sh.
2. Incremental Adoption:
   • Start with non-critical tasks (e.g., cache clearing) before migrating core deployments.
   • Use scotty --pretend to validate scripts before live runs.
3. Tooling Updates:
   • Update CI/CD scripts to call scotty run instead of raw SSH.
   • Replace Envoy recipes with Scotty macros (e.g., @macro deploy instead of @setup).

Compatibility

• Laravel-Specific:
  • Artisan Integration: Add a custom artisan command (e.g., php artisan scotty:run) to wrap Scotty calls.
  • Service Providers: Use Scotty in bootstrapping (e.g., post-install tasks).
• Non-Laravel PHP:
  • Use Scotty for any PHP project with SSH access (e.g., WordPress, Symfony).
  • Example: Automate composer install and php artisan cache:clear in a Scotty.sh file.
• Legacy Systems:
  • Replace custom Bash scripts or Ansible for simple SSH tasks with Scotty’s declarative syntax.

Sequencing

1. Pre-Deployment:
   • Run scotty doctor to validate SSH connectivity.
   • Use scotty tasks to list available macros.
2. Deployment:
   • Execute scotty run deploy --branch=main (with --continue for CI).
   • Log outputs to a file for auditing.
3. Post-Deployment:
   • Verify task success with scotty run verify (custom macro).
   • Roll back via scotty run rollback if needed.

Operational Impact

Maintenance

• Pros:
  • Single Source of Truth: Scotty.sh files live in the repo, ensuring team alignment.
  • No PHP Dependencies: Scotty’s PHAR format reduces Laravel’s vendor/ bloat.
  • Self-Documenting: Tasks are visible in the codebase (unlike Envoy’s Blade templates).
• Cons:
  • Bash Maintenance: Teams must version-control SSH configs (e.g., ~/.ssh/config) if used.
  • Debugging: Complex Bash logic may require SSH expertise to troubleshoot.

Support

• Developer Onboarding:
  • Provide a Scotty.sh template for new projects (e.g., Laravel starter kits).
  • Document common patterns (e.g., @option, @macro, @task).
• Troubleshooting:
  • Use scotty --pretend to simulate runs without side effects.
  • Log outputs to Laravel’s storage/logs for centralized monitoring.
• Escalation Path:
  • For SSH issues, escalate to DevOps; for Bash errors, involve backend engineers.

Scaling

• Multi-Server Scalability:
  • Scotty’s @servers annotation supports parallel task execution (e.g., deploy to multiple web servers).
  • Example: @servers web-1=..., web-2=... with @task on:web-1,web-2.
• Performance:
  • No overhead: Scotty streams SSH output in real-time (unlike Envoy’s Blade compilation).
  • Connection pooling: Reuses SSH connections for multiple tasks.
• Limitations:
  • No built-in parallelism: Tasks run sequentially unless manually orchestrated (e.g., with & in Bash).
  • Large teams: May need role-based access (e.g., restrict scotty run deploy to admins).

Failure Modes