Spin Laravel Package

Technical Evaluation

Architecture fit

• Spin is a thin Bash CLI wrapper (bin/spin + one file per command under lib/actions/) over docker compose, with Docker images used as the execution vehicle for Ansible, GitHub CLI, Node, and PHP tooling. There is no PHP library surface, no Composer package, and no runtime coupling to the Laravel application — it never enters the application’s dependency graph or request lifecycle.
• Its design intent is environmental parity, not application logic: docker-compose.yml plus an environment overlay (docker-compose.$SPIN_ENV.yml) reproduces a production-shaped stack locally with spin up. That makes it a developer-experience layer, not an architectural component.
• The abstraction is deliberately shallow — arguments are passed through to the underlying Compose subcommand. Low magic means low lock-in, but it also means Spin adds little value if the team is already fluent in raw Compose or already standardized on Laravel Sail, DDEV, or Lando.
• Framework-agnostic by construction, so it is a poor fit only where Compose is not the orchestration model (Kubernetes-first shops, Podman-only shops, Nix-based dev shells).

Integration feasibility

• Very high for a Compose-based Laravel codebase. Installation is a single script, requires only Docker, and imposes no PHP version, extension, or composer.json change. There is nothing to add to composer.lock, nothing to build, and nothing in the deployable artifact.
• The closest integration seam is documentation plus a thin shim: a Makefile target or npm-style script alias so developers can adopt Spin incrementally without the team rewriting muscle memory or CI scripts on day one.
• The friction point is version pinning. Spin is installed as a global binary with a self-upgrade path and a cached update check. Per-repository reproducibility (the thing a TPM actually cares about) is not guaranteed by the tool itself; that has to be engineered by us.

Technical risk

• Licensing: GPL-3.0. Invoking the CLI in a development workflow is normally unproblematic, but redistribution (bundling it into an internal dev image or a distributed developer toolkit) is a copyleft conversation. Route to legal before any bundling decision.
• Bus factor / stewardship: a single-vendor open-source project (serversideup) at ~1.5k stars with a modest opportunity score. Signals a mature, stable, low-differentiation utility — good for stability, weak for influence over roadmap. Do not plan to fork and extend; the Bash 3.2 compatibility constraint (no associative arrays, no mapfile) makes upstream contributions slower than a typical library.
• Blast radius beyond dev: spin provision and spin deploy touch servers and Swarm. Those commands must be explicitly out of scope for the initial rollout, or governed by a separate ops review — that is a different risk class than "makes local dev nicer."
• Platform surface: macOS, Linux, and WSL2 are supported; native Windows shells are not. Bash 3.2 compatibility is a real reliability risk carried by the maintainers, not by us — but any wrapper we write must not break it.
• Opportunity score of 2.65 reads as "little value for us to extend or compete." That argues for adopt and constrain, not invest in.

Key questions

1. What is our per-repository version-pinning policy for a globally installed CLI, and can we enforce a minimum Spin version in onboarding docs or a preflight check?
2. Is our current local-dev standard Laravel Sail, DDEV, or raw Compose? If Sail, is the migration worth the churn, given overlapping value?
3. Does legal clear GPL-3.0 for developer-machine use and, separately, for internal dev-image bundling?
4. Are provision and deploy in scope at all, or is this strictly a up/down/exec/logs/build/run decision for now?
5. Do any existing .env files set COMPOSE_FILE, SPIN_ENV, or COMPOSE_CMD, and would Spin’s defaults silently override them?
6. What is the supported matrix — Docker Desktop only, or also Colima/Rancher Desktop — and who owns diagnosing Docker-level failures?

Integration Approach

Stack fit

• Strongest fit: Laravel (or any PHP) application on serversideup/php images with a Compose v2 workflow. The default serversideup/php:cli and Node images align with the broader serversideup toolchain (docker-php, Ansible collection, GitHub Actions), so choosing Spin is really a decision to lean into that ecosystem.
• Neutral fit: any containerized application already using Compose files. Spin is a convenience, not a requirement.
• Poor fit: teams on Sail/DDEV with no intent to change, Kubernetes-based local environments, or shops that restrict Docker Desktop licensing.

Migration path

1. Keep the existing docker-compose.yml untouched as the source of truth; add a docker-compose.dev.yml overlay rather than rewriting service definitions.
2. Introduce Spin alongside the current workflow — document spin up / spin down / spin exec as an alternative, not a replacement, for one sprint.
3. Add a Makefile (or composer script) facade so make up, make test, make migrate route to Spin internally. This decouples developer habits from the tool and gives a single place to swap implementations later.
4. Remove the incumbent tooling only after a full sprint of parallel use and a documented rollback (uninstall script / revert to prior commands).

Compatibility

• No PHP, framework, or database compatibility implications — Spin sits outside the app runtime entirely.
• Docker Compose v2 is assumed; verify developer Docker versions before rollout.
• Multi-file Compose layering (COMPOSE_FILE with : separators) is the main collision risk with existing environment variables; audit and namespace before enabling.
• UID/GID mapping (SPIN_USER_ID) is a genuine plus for Linux file-permission pain, and should be validated on the Linux cohort during the PoC.
• For AI/CI/subprocess use, spin run -T / spin exec -T is required to disable TTY allocation — worth codifying in the team’s command conventions up front, since omitting it produces confusing hangs.

Sequencing

• Phase 0 (1 week): PoC in one repository, one developer per OS (macOS, Linux, WSL2). Success criteria: spin up from clean clone to working app in under 15 minutes, no manual steps.
• Phase 1 (1 week): Pin the version, write the onboarding doc, add the Makefile facade, confirm GPL clearance for the intended use.
• Phase 2 (2–4 weeks): Voluntary rollout with a feedback channel; track onboarding time and Docker-related support tickets as the two metrics that justify the decision.
• Phase 3 (deferred): Evaluate spin run in CI and only then open a separate review for provision/deploy with the infrastructure owner.

Operational Impact

Maintenance

• Low code surface, low maintenance burden for us — there is no vendor code in our repositories. The ongoing cost is upgrade hygiene: because the binary is global, version drift across the team is the default state. Assign an explicit owner for "Spin version used by the team" and revisit quarterly, or on any breaking change upstream.
• The cached auto-update check is convenient but noisy in air-gapped or firewalled environments; confirm behavior and provide an opt-out in the onboarding doc.
• Our own wrapper surface (the Makefile facade, any preflight scripts) is the part we maintain. Keep it under ~50 lines so it never becomes a second product.

Support

• Net support load typically decreases: one command replaces a multi-step Compose invocation, and error messages are explicit and colored (Docker-not-running, invalid command).
• Residual tickets concentrate in Docker itself — resource limits, port conflicts, volume mount performance on macOS — not in Spin. Set that expectation with the first-line support group so Spin is not blamed for Docker Desktop issues.
• --remove-orphans is applied automatically on up/down; developers with non-standard container names should be warned, since it can remove containers they did not expect.

Scaling

• Scales cleanly with headcount: no server component, no shared state, no per-seat licensing. Onboarding cost per developer is roughly an hour.
• Does not scale across repositories or teams as a coordination tool — each repo carries its own Compose files, and Compose file sprawl becomes the real long-term cost, not Spin.
• Ansible-driven provisioning scales to fleets but belongs to an infrastructure owner; treat that as a separate platform decision, not part of the developer-experience rollout.

Failure modes

• Docker daemon not running → handled gracefully with a clear message and non-zero exit.
• Image pull failures or registry auth → surfaces as Compose errors; document --skip-pull / --force-pull as the escape hatches.
• Compose version drift between developers → the most likely recurring, low-severity failure; mitigate with a documented minimum Docker version.
• Environment variable leakage (COMPOSE_FILE, SPIN_ENV) → silent, hard-to-diagnose misconfiguration; this is the failure mode most worth pre-empting.
• Cross-platform shell divergence (Bash 3.2 on macOS, sed/base64/readlink differences) → upstream’s problem, but it means bug reports should include OS and ShellCheck-level detail.
• Production-adjacent commands (deploy, provision) → highest severity, lowest probability if scoped out; keep them out of the initial rollout and out of developer muscle memory.

Ramp-up

• Documentation quality is above average for a utility of this size: a dedicated docs site, a full command reference, pass-through semantics clearly stated, and agent-oriented skill files that double as onboarding material.
• Expect ~1 hour per developer, dominated by unlearning the incumbent tool rather than learning Spin. Provide a one-page cheat sheet mapping old commands to spin equivalents.
• Budget half a day of platform-engineer time for the PoC, the pinning decision, and the facade — that is the entire internal investment.
• Recommendation for the decision record: adopt as a dev-only convenience layer behind a Makefile facade, pinned and documented; explicitly exclude provision/deploy from scope; revisit only if onboarding time or environment-drift tickets fail to improve.