Spin Laravel Package

Product Decisions This Supports

• Developer onboarding as a product surface. spin up collapses "install Docker, read the README, copy env files, remember the three compose commands" into one verb. This is directly measurable: time-to-first-commit for a new hire, and volume of "works on my machine" tickets. If onboarding friction is on your roadmap, this is a cheap, reversible intervention.
• Environment parity as an architecture decision. Spin layers docker-compose.yml + docker-compose.$SPIN_ENV.yml and defaults to dev, with SPIN_ENV=production switching the same toolchain. That makes "same compose definitions from laptop to server" a defensible standard rather than an aspiration — and it's the same lever you'd otherwise spend engineering weeks building internally.
• Build vs. buy on internal DX tooling. The realistic alternative is a hand-rolled Makefile/just/shell-script layer maintained by whoever cares most. Spin is that layer, already written, cross-platform-tested, and free. Adopting it is a deferral of an internal-tooling decision, not a commitment — the pass-through design keeps the exit cheap.
• Standardizing command vocabulary across docs, runbooks, and CI. spin run / spin exec / spin build / spin logs forward flags straight to docker compose, so documentation and CI scripts can reference one stable set of commands without inventing a new DSL. This shrinks the documentation surface area your team must maintain.
• Template and scaffold decisions. If you ship a service template or "golden path" repo, Spin is a candidate component — particularly for Laravel/PHP shops already adjacent to the Server Side Up ecosystem (Docker PHP images, Ansible collection, GitHub Actions).
• Support-burden reduction on file permissions. Running containers with the host user/group ID (SPIN_USER_ID) eliminates the classic root-owned-vendor/-and-node_modules/ support class, which is disproportionately expensive in bind-mounted local dev.
• Roadmap scoping: tactical accelerator, not a strategic bet. The low opportunity signal and modest star count mean this belongs in "reduce friction this quarter," not "platform strategy for next year." Treat it as a decision you can make at team level without architecture review.

When to Consider This Package

Consider it when:

• Your team already uses (or is standardizing on) Docker Compose. Spin is a conventions layer on top of Compose, not a replacement — the value proposition collapses if you're running Kubernetes locally or a bespoke orchestrator.
• You have a mixed-OS engineering org — macOS, Linux, and Windows-via-WSL2 are explicitly supported and tested.
• Install friction is a real constraint: no Node, Ruby, Python, or modern Bash required. Attractive for locked-down corporate laptops, regulated environments, and thin CI images.
• You're a PHP/Laravel or polyglot shop and want one tool that spans local dev, provisioning, and deploy (Compose/Swarm + Ansible) without a platform team.
• You want a thin, inspectable wrapper you can read end-to-end in an afternoon, rather than a platform with its own abstraction layer and upgrade treadmill.

Look elsewhere when:

• Windows-native (non-WSL) developers are in scope. The tool assumes a POSIX shell; requiring WSL2 is an onboarding tax you may not want to impose.
• Dev Containers / GitHub Codespaces is your standard. Those ecosystems solve the same problem with IDE integration Spin doesn't attempt.
• You need batteries-included local dev — database snapshots, mail capture, GUI, hostname-based TLS, per-project service catalogs. DDEV, Lando, or Laravel Sail (if Laravel-only) cover more ground with more polish.
• Your production target is Kubernetes/Helm. The deploy story is Compose and Swarm; that's a mismatch with where most orgs are heading.
• Legal requires permissive licensing. GPL-3.0 is fine for internal use and for invoking the CLI as a separate process, but it warrants review before you fork it, redistribute it, or embed it in anything customer-facing.
• You need a vendor relationship — SLA, security response commitments, roadmap influence, or a named maintainer you can escalate to. This is a small-team open-source project.
• Your existing Make/just/Taskfile layer already works. Migrating conventions for their own sake burns trust and buys little.

Pilot posture: scope to one or two repositories for a quarter, instrument onboarding time and environment-related incidents, and keep the compose files canonical so that reverting to plain docker compose is a one-line change.

How to Pitch It (Stakeholders)

For executives. Spin is a ~1,500-star open-source Bash wrapper that makes Docker environments reproducible with a single command: spin up. It's free, installs with no new dependencies beyond Docker, and is reversible in a sprint — worst case we delete a script and keep the compose files we already own. The business case is onboarding velocity and fewer environment-driven support tickets, not new capability. Two caveats worth naming up front: it's GPL-3.0 licensed (fine for internal use, needs legal review before redistribution or embedding), and it's a small-maintainer project with a modest adoption signal, so we should treat it as a tactical accelerator rather than a platform commitment. Recommended ask: a one-quarter pilot on one or two repos with a documented fallback to plain docker compose.

For engineering. This is conventions, not a new abstraction. Every development command — up, down, build, logs, run, exec — passes arguments straight through to docker compose, so existing knowledge and Compose syntax transfer directly. It layers docker-compose.yml with docker-compose.$SPIN_ENV.yml, giving you environment selection by variable rather than by remembering flags. It runs tooling (Ansible, GitHub CLI, Node, PHP) inside containers, so nothing needs to be installed locally, and it maps the host user ID into containers to avoid root-owned files in bind mounts. Debugging is SPIN_DEBUG=true to see the exact commands executed. Code is readable Bash with ShellCheck in CI and a three-OS test matrix; the tradeoff is deliberate Bash 3.2 compatibility, which constrains contributors but guarantees it runs on stock macOS. If you're already comfortable with Compose, the ramp-up is measured in minutes.

The one-line version. spin up replaces the tribal-knowledge phase of onboarding with a command that either works or fails loudly — and if we stop liking it, our compose files are unchanged.