Scotty Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: Scotty excels as a remote task runner for Laravel/PHP applications, particularly for deployment, server maintenance, and CI/CD workflows. It replaces Laravel Envoy with a more modern, annotation-driven syntax while maintaining compatibility.
• Laravel Synergy: Seamlessly integrates with Laravel’s ecosystem (e.g., php artisan commands, .env variables) and Envoy’s existing deploy scripts, reducing friction for teams already using Envoy.
• Modularity: Tasks are defined in a Scotty.sh file (Bash + annotations), enabling granular, reusable workflows without coupling to Laravel’s core. Ideal for microservices, multi-server deployments, or legacy PHP apps.

Integration Feasibility

• Low-Coupling Design: Scotty operates outside Laravel’s core, requiring only SSH access to remote servers. No database or framework dependencies, making it easy to adopt incrementally.
• Envoy Migration Path: Direct replacement for Envoy (same @servers, @task syntax), with backward compatibility for existing scripts. Minimal refactoring needed.
• Tooling Ecosystem: Works with GitHub Actions, GitLab CI, or self-hosted runners via SSH keys, aligning with modern DevOps pipelines.

Technical Risk

• SSH Dependency: Requires secure SSH key management (agent forwarding, key rotation). Risk of credential leaks if misconfigured (mitigated via ~/.ssh/config or environment variables).
• Bash Scripting Limits: Complex logic may still require custom Bash scripts or shell workarounds (e.g., parallel tasks, error handling). Scotty’s annotations are not a full DSL (e.g., no native PHP integration for task logic).
• Debugging Overhead: Remote task failures may require SSH debugging (e.g., scotty run --verbose), increasing operational toil compared to local task runners.
• State Management: No built-in task state persistence (e.g., retries, progress tracking) beyond stdout. Teams may need to layer external tools (e.g., Laravel Horizon, custom logs).

Key Questions

1. SSH Infrastructure:
   • Are remote servers SSH-accessible from CI/CD or deployment machines? Are keys rotated/managed securely?
   • Will firewalls/proxies block Scotty’s SSH connections (e.g., corporate networks)?
2. Task Complexity:
   • Do workflows require parallel execution, conditional logic, or PHP-based task steps? If so, how will these be handled?
3. Envoy Migration:
   • What’s the scope of existing Envoy scripts? Can they be lift-and-shifted to Scotty, or do they need rewrites?
4. Observability:
   • How will task logs be aggregated/archived (e.g., for audits)? Scotty’s output is stdout-only by default.
5. Team Adoption:
   • Do developers have Bash scripting familiarity? Will Scotty’s syntax reduce onboarding friction vs. Envoy?

Integration Approach

Stack Fit

• Primary Use Cases:
  • Deployments: Pull code, run migrations, restart services (e.g., scotty run deploy).
  • Server Maintenance: Clear caches, optimize databases, rotate logs (e.g., scotty run maintenance).
  • CI/CD: Post-build steps (e.g., scotty run post-build in GitHub Actions).
• Laravel-Specific Synergy:
  • Replace envoy:run commands with scotty run.
  • Use Laravel’s .env variables in Scotty.sh via @env annotations (e.g., @env APP_URL=${APP_URL}).
  • Integrate with Laravel Forge/Vapor for server provisioning (Scotty handles post-provision tasks).
• Non-Laravel Compatibility:
  • Works with any PHP app (Symfony, WordPress, etc.) or non-PHP servers (Node.js, Python) via SSH.

Migration Path

1. Pilot Phase:
   • Replace 1–2 Envoy scripts with Scotty equivalents (e.g., deploy.sh → Scotty.sh).
   • Test in a staging environment with SSH access.
2. Incremental Rollout:
   • Phase 1: Deployments (highest ROI).
   • Phase 2: Maintenance tasks (e.g., cache clearing).
   • Phase 3: CI/CD hooks (e.g., post-deploy verification).
3. Tooling Updates:
   • Update CI/CD pipelines to call scotty run instead of envoy run.
   • Replace envoy:run in package.json/composer scripts with scotty run.

Compatibility

• Envoy → Scotty:
  • Direct Mapping: @servers, @task, @macro annotations are identical.
  • Breaking Changes:
    • Scotty does not support Envoy’s @parallel or @stop-on-failure (workarounds: Bash & or custom error handling).
    • No native PHP task execution (tasks must be Bash; use php artisan commands).
• SSH Requirements:
  • Servers must have SSH keys configured (password auth may require scotty --password flag).
  • Key-based auth recommended for security and automation.
• Laravel-Specific:
  • Works with Laravel’s SSH config (e.g., ~/.ssh/config host aliases).
  • Can source .env via @env annotations (e.g., @env DB_HOST=${DB_HOST}).

Sequencing

1. Pre-Integration:
   • Audit existing Envoy scripts for Scotty compatibility.
   • Set up SSH key pairs for all target servers (or use existing keys).
2. Development:
   • Convert 1–2 scripts to Scotty.sh format.
   • Test locally with scotty run --dry-run.
3. Deployment:
   • Roll out to staging, then production.
   • Update CI/CD pipelines to use Scotty.
4. Post-Launch:
   • Monitor SSH connection stability and task success rates.
   • Document Scotty.sh templates for the team.

Operational Impact

Maintenance

• Pros:
  • Simpler syntax than Envoy’s PHP-based tasks (Bash is more familiar for server ops).
  • No PHP runtime dependency on remote servers (only SSH/Bash required).
  • Easier to debug than Envoy’s compiled tasks (stdout output is human-readable).
• Cons:
  • Bash scripting maintenance: Complex tasks may require updates to shell scripts.
  • No built-in task versioning: Changes to Scotty.sh are not tracked by Scotty (use Git for history).
  • SSH key rotation: Requires manual updates to ~/.ssh/config or environment variables.

Support

• Troubleshooting:
  • Common Issues:
    • SSH connection failures (check keys, firewalls, scotty --verbose).
    • Task timeouts (adjust @timeout in annotations).
    • Permission errors (ensure remote user has correct access).
  • Debugging Tools:
    • scotty run --verbose for detailed logs.
    • scotty run --dry-run to preview tasks.
• Team Skills:
  • Bash proficiency is a plus but not mandatory (Scotty’s annotations are simple).
  • Laravel devs will adapt quickly due to Envoy familiarity.
• Vendor Support:
  • Community-driven (Spatie’s GitHub repo, no official SLAs).
  • Documentation is solid (README, usage examples, migration guide).

Scaling

• Horizontal Scaling:
  • No server-side scaling needed (Scotty is client-side).
  • Parallel tasks: Use Bash & or external tools (e.g., GNU Parallel) for multi-server jobs.
• Performance:
  • SSH overhead: Each task spawns a new SSH connection (mitigate with @servers grouping).
  • Task execution time: Limited by remote server performance (not Scotty).
• Load Testing:
  • Test with high-frequency tasks (e.g., cron jobs) to validate SSH connection pooling.

Failure Modes