Takeout Laravel Package

Technical Evaluation

Architecture fit. Takeout is a require-dev Composer package that generates and drives a per-project docker-compose.yml for backing services only — MySQL/MariaDB, PostgreSQL, Redis, Memcached, Mailhog/Mailpit, MinIO, and search. It is deliberately out of the application runtime: it does not ship Docker, does not rewrite .env, does not touch config/database.php, and does not manage PHP versions. That narrowness is the architectural selling point. It fits teams that want a thin, MIT-licensed, maintained wrapper around standard Docker tooling rather than an internal dev-harness build, and it fits per-project isolation as a first-class property: each app gets its own containers, ports, and named volumes.

Integration feasibility. Adoption is a single composer require --dev tighten/takeout, followed by ./vendor/bin/takeout list and ./vendor/bin/takeout enable <service>. The binary lives at vendor/bin/takeout, not Artisan. The only hard prerequisites are a running Docker engine and Compose v2 on PATH; both should be verified with docker compose version before installation, because Takeout shells out to docker compose and inherits every failure of that layer. Realistic pilot is half a day: enable MySQL, paste the printed port into .env, php artisan config:clear, php artisan migrate, then disable/enable and confirm data survived.

Technical risk.

• Port drift is the dominant support cost. enable assigns a free host port, may assign a different one after disable/enable, and never updates .env. The symptom is "connection refused," routinely misdiagnosed as credentials or auth-plugin failure.
• Upstream image movement. v3.2.1 is a PostgreSQL 18 volume-path fix (/var/lib/postgresql/data → /var/lib/postgresql); anyone tracking postgres:latest was moved by an upstream push and hit initdb errors. Pin tags in the committed YAML immediately, for every service.
• Orchestrator collision. Takeout and Laravel Sail both own docker-compose.yml and both bind host ports. Running both on one project is a known, confusing failure mode, not a preference.
• Generated-artifact lifecycle. Hand-editing the generated file works until the next regeneration overwrites it. The supported extension point is docker-compose.override.yml, which Compose merges automatically.
• Platform variance. Apple Silicon may need platform: linux/amd64 in the override file for amd64-only images; Linux needs the user in the docker group; localhost resolves to ::1 on many setups, so 127.0.0.1 should be the documented default for DB_HOST and Redis.
• Data-expectation mismatch. takeout disable preserves named volumes; docker compose down -v destroys them irrecoverably. Engineers routinely expect the opposite of whichever one they ran.
• Ecosystem signal. Zero dependents and a narrow scope mean low coupling and low blast radius, but also little external validation beyond the project's own ~1.7k stars and maintenance cadence.

Key questions for the decision record.

1. What is the default orchestrator per project — Takeout, Sail, DDEV, or platform-provided — and who records that decision?
2. Is the team concurrency-first (per-developer assigned ports, .env not committed, README documents the copy step) or determinism-first (fixed ports via --default-port or post-enable YAML edits, committed)?
3. Which services are in the pilot scope, and what is the exit criterion (time-to-first-migrate, onboarding hours, environment-variance incidents)?
4. Are there org policy constraints — approved registries, hardened base images, network isolation — that would force an internal harness instead?
5. Who owns the committed docker-compose.yml artifacts and the image-tag bump PRs?
6. What is the documented laptop ceiling for concurrent projects (each MySQL/Postgres is a few hundred MB of RAM)?

Integration Approach

Stack fit. Laravel applications on composer, with Docker Desktop, OrbStack, or Colima on macOS and native Docker with docker group membership on Linux; Windows via Docker Desktop/WSL2. Host-run php artisan connects to containers over published ports on 127.0.0.1. Redis can serve cache, queue, and session from one container, so php artisan queue:work on the host works against it without an extra service. Mail is the highest-value, lowest-risk first adoption: set MAIL_MAILER=smtp and point at the printed Mailpit/Mailhog port to get a per-project web inbox.

Migration path.

• From manual local installs or Homebrew services: stop and disable the host services first, then adopt Takeout service-by-service to avoid two things claiming the same port.
• From Laravel Sail: do not run both. Choose one orchestrator per project, remove or archive the other's compose file in the same PR, and state the choice in the README. This is the single most important migration guardrail.
• From nothing (greenfield): verify Docker and Compose v2, install, enable MySQL, wire .env, migrate, then commit the generated YAML.
• Never from CI or staging — Takeout is a developer-convenience CLI, not a pipeline or deployment tool.

Compatibility notes.

• Compose v2 must work standalone before Takeout is installed.
• Pin image tags in committed YAML; specifically pin PostgreSQL to an explicit 17.x or 18.x rather than latest.
• Use 127.0.0.1, not localhost, for DB_HOST and Redis host.
• Run php artisan config:clear after every .env change; cached config is the second-most-common false alarm.
• Add platform: linux/amd64 in docker-compose.override.yml, never in the generated file, for amd64-only images on Apple Silicon.
• .env values are perspective-dependent: 127.0.0.1:<published> for host-run PHP, service name and internal port if the app is later containerized. Do not copy .env across that boundary.

Sequencing.

1. Verify docker compose version; fix the Docker engine and Linux group membership before touching the package.
2. composer require --dev tighten/takeout; run takeout list and takeout <command> --help to establish the authoritative service spelling.
3. Enable MySQL only; wire .env; config:clear; migrate; run the disable/enable persistence check. This is the proof-of-concept gate.
4. Pin the image tag and commit the generated docker-compose.yml as a reviewable artifact.
5. Add Redis (cache + queue + session) next, then Mailpit, then MinIO or search — one service, one smoke test, one commit at a time.
6. Add docker-compose.override.yml only when a real customization appears; never hand-edit the base file.
7. Publish an onboarding README block ending in takeout enable, and consider a composer setup script that stops by instructing the developer to run it. Do not automate port injection into .env — half-working automation here is worse than a two-line README.
8. For CI, mirror the pinned tags from the committed YAML into explicit services: blocks with healthchecks; do not wrap Takeout into the pipeline.

Operational Impact

Maintenance. Low and mostly mechanical. Keep composer update in the normal cadence; the meaningful maintenance work is image-tag pinning, which converts upstream image pushes into reviewable PRs instead of surprise outages. Service changes go through takeout disable <service> && takeout enable <service>, not hand-editing, so the generated file stays reproducible. The committed docker-compose.yml and per-project config file are the durable artifacts and should live in the repo next to the code.

Support. Expect a predictable ticket queue, and put it in the README rather than rediscovering it per incident:

• Port drift / .env mismatch is ticket #1. The triage question is always "did you re-run enable, and does .env match docker compose ps?"
• Stale config cache after an .env fix is #2 — php artisan config:clear.
• "My data disappeared" / "my broken schema came back" is #3 — state plainly that disable preserves volumes and down -v destroys them.
• Sail coexistence and Linux docker group permissions round out the list; the latter looks like a Takeout bug and never is.
• Debugging commands worth standardizing in the runbook: docker compose ps, docker compose logs -f <service>, docker compose down -v, ./vendor/bin/takeout list.

Scaling. Per-project containers and named volumes are the actual differentiator: an engineer can hold several client apps, branches, or demos live at once with isolated databases and no port collisions. Plan the ceiling explicitly — each MySQL/Postgres container is a few hundred MB of RAM — so engineers self-limit rather than discovering the limit during a demo. Org-wide, scaling is a standardization problem, not a technical one: one default orchestrator, one documented port stance, one README block, replicated per repository.

Failure modes to design around.

• Connection refused from port drift, or from localhost resolving to ::1 against a container not listening on IPv6.
• PostgreSQL 18 initdb: directory not empty or a restart loop after an upstream move; the fix is regeneration plus a pinned tag, not hand-patching the mount.
• Two orchestrators fighting over docker-compose.yml and host ports, producing genuinely confusing errors.
• Irrecoverable loss of seed data from an incidental down -v.
• Silent overwrite of hand edits on the next enable.
• Slow or failing amd64-only images on Apple Silicon until a platform override is added.

Ramp-up. A developer with working Docker is productive in well under a day; a team with a good README block is productive on their first clone. The high-leverage measurement is time-from-clone-to-first-successful-migrate for new hires, tracked before and after adoption, plus environment-variance incidents per onboarding. Assign one owner for the committed compose artifacts and tag bumps, and document the boundary of the tool explicitly — Takeout will not rewrite .env, manage PHP versions, provide an app runtime, or handle multi-repo networking. When someone wishes it did, that is the signal to evaluate Sail, DDEV, or a platform solution as a deliberate per-project choice, not to bolt capability onto Takeout.