Vessel Laravel Package

Technical Evaluation

What is actually being versioned. Vessel is not a Composer-installable Laravel/PHP package. It is a versioned Docker development-environment scaffold — docker-compose.yml plus per-service build context (app/php-fpm, nginx, mysql, redis, and optional tooling) — that is copied into a Laravel application repository and thereafter owned by that repository. There is no autoloadable namespace, no service provider, no runtime dependency, and no semver contract with application code. This materially changes the evaluation: the "integration surface" is file templates, compose service names, published ports, volume mount paths, and environment variable names; the "API" is whatever the project's config files and scripts assume about those.

Architecture fit. The topology is a conventional Laravel local-dev stack and 6.0.0 does not change it. All four changes are interior to the images or to generated config: base OS 18.04 → 20.04, GPG key import with IPv6 disabled, nginx/PHP static-content handling so Swagger assets no longer round-trip a 303, and predis no longer installed during init. Fit with a standard Laravel app is unchanged. The one architectural constraint to restate: this is a development-environment artifact and must not be in the production deployment path; if any team has quietly derived staging or CI images from these Dockerfiles, that is now a production-adjacent change and should be re-classified.

Integration feasibility. High, with a mandatory rebuild. The release note explicitly requires rebuilding the app image and points to the documented upgrade/reset procedure. Projects keep their compose file; the delta is the Dockerfile base references and image contents. Effort is concentrated in one owner doing a rebuild-and-verify pass per repository, not in code changes.

Technical risk. This is a major version with declared breaking changes, and the changelog is unusually terse for a base-OS jump. The specific risks:

• Base OS jump is the dominant risk, not the four bullets. Moving 18.04 → 20.04 shifts the PHP minor/patch line, the available extension set and their versions (gd, imagick, intl, pdo_mysql, bcmath, zip), ICU, OpenSSL, default locale, and timezone data. Projects that pin ext-* in composer.json or rely on implicit extensions can fail at composer install inside the container with no obvious link to the release note.
• predis removal is a silent-failure candidate. Removing predis from the init step means it is no longer present unless declared in composer.json. Applications configured with REDIS_CLIENT=predis will boot fine and fail at first cache/queue/session access with a class-not-found. This is the kind of change that surfaces in a demo, not in a build.
• GPG key import with IPv6 disabled is a build-reliability workaround. It should make builds more deterministic on IPv6-broken corporate networks, VPNs, and some CI runners, but it is an environment-conditional behavior and merits a build on a restricted network before rollout.
• Swagger static-content change is low risk for most, but it touches generated config — teams with hand-edited nginx or PHP config that the upgrade overwrites should diff before applying.
• Changelog opacity. No migration note on PHP version, no extension manifest delta, no statement of which predis assumption was removed. The upgrade guide is the only authoritative source and should be read in full before scheduling.

Key questions

1. Which PHP version does the 20.04 app image ship, and which extensions are added or dropped versus the 18.04 image? Need an explicit extension manifest diff, not inference.
2. Is the predis removal a removal from the image only, or does init also stop editing composer.json? What is the sanctioned migration for teams on REDIS_CLIENT=predis?
3. Are these images multi-arch (arm64), and do the 20.04-based tags exist for Apple Silicon developers? A dev environment that regresses half the team's laptops is a bigger cost than the upgrade itself.
4. Is there a supported path to override the PHP base image tag (e.g., PHP 8.x) without forking the scaffold, and is that path covered by the project's docs?
5. Ubuntu 20.04 is now past its standard LTS support window; is there a roadmap item for the next base-image bump, and how much notice will it carry?
6. Does the upgrade procedure discard named volumes (MySQL data, Redis AOF)? If so, is there a documented dump/restore step, and does MySQL major version change across this bump?
7. Is 6.x intended to be a drop-in for 5.x in terms of service names, ports, and env var names, or are there renames that break existing .env files and scripts?

Integration Approach

Stack fit. Vessel sits alongside — not inside — the application dependency graph. Laravel app code, composer.json, and CI pipelines are untouched; only the local-container layer moves. That containment is the main reason this upgrade is tractable: blast radius is bounded to developer machines and any tooling that shells into the containers.

Migration path. Treat it as a scaffold refresh, not a package bump:

1. Read the upgrade/reset guide end to end and inventory what the project has customised (Dockerfile edits, extra services, mounted config, xdebug settings, cron/scheduler container).
2. Diff the 5.x → 6.0 scaffolding against the project's copies; classify each delta as accept / preserve / conflict.
3. Rebuild the app image (plus any service whose build context changed) with --no-cache so no stale 18.04 layers survive behind a moved tag.
4. Reconcile extension requirements: run composer install and the test suite inside the rebuilt container, and diff php -m before and after.
5. Resolve the predis question explicitly — declare predis/predis if the app is configured for it, or switch REDIS_CLIENT to phpredis after confirming the extension is present.
6. Run smoke coverage: php artisan migrate against a fresh or restored database, queue worker start, scheduler, storage/asset serving, and the Swagger/API docs route that the 303 change affects.

Compatibility. Two compatibility axes matter. Downward — older Laravel versions on the team's other projects; Vessel is Laravel-version-agnostic, so the constraint is really PHP version compatibility with each app's composer.json. Sideways — host platform (Intel vs Apple Silicon vs Windows/WSL2), where base-image architecture availability is the gating factor. Neither axis is addressed in the release note and both should be verified empirically before a team-wide announcement.

Sequencing. One repository, one owner, one branch first. Prove the rebuild, the extension diff, the Redis path, and the DB volume behaviour there. Then roll the remaining repositories in waves, keeping 5.x scaffolding on a branch or tag so a regression is a revert rather than a re-derivation. Publish the validated extension manifest and the predis decision to the team before wave two — most of the support cost in this kind of upgrade comes from every developer rediscovering the same two failures independently.

Operational Impact

Maintenance. The scaffold is now a fork the team owns. Every future Vessel release is a manual diff-and-merge against local customisations, and the cost grows with how much each repository has drifted. Two disciplines reduce this permanently: keep customisations in a separate override file or docker-compose.override.yml rather than editing shipped files, and record the adopted version in the repo (README or a version marker) so drift is visible. Note also that the previous base OS is now two LTS generations behind — if there is no cadence for taking these bumps, the effort per bump will keep increasing, since each skipped release compounds.

Support. Expect a predictable first-week support load concentrated in three tickets: Class "Predis\Client" not found, a missing or changed PHP extension during composer install, and a container that builds but serves stale code because of cached layers or an un-rebuilt image. Pre-empting these with a short internal note — the extension diff, the Redis decision, and the mandatory --no-cache rebuild — will absorb most of it. The GPG/IPv6 change may generate a fourth ticket class from developers on restrictive networks; that one is environment-specific and hard to predict, so keep a fallback build recipe.

Scaling. Scaling here means team size and CI ephemerality, not production throughput. Two considerations. First, image build time and registry caching: a base-OS change invalidates every layer, so the first build across N developers and CI runners is the slowest one; publish the built image to a registry (or a shared cache) before broad rollout to convert N slow builds into one. Second, onboarding cost is low — a new developer is productive in well under a day with containerised dependencies — and 6.0.0 does not change that, provided the extension manifest is documented. CI runners that build these images are the practical scaling constraint; ARM64 runner availability is worth confirming in the same pass as developer laptops.

Failure modes. Ranked by likelihood × cost:

The two that warrant explicit pre-flight checks are the predis removal and the database volume/MySQL version question, because both produce a working-looking environment that fails later rather than a loud build error.

Ramp-up. Low for developers — the mental model is unchanged and the commands are the same. Elevated for whoever owns the upgrade: budget roughly one to two days for the first repository (rebuild, extension diff, Redis decision, DB volume reconciliation, smoke tests) and a few hours per repository thereafter. The dominant unknown is documentation quality of the upgrade guide; the release note itself defers entirely to it, so read it before committing to a rollout date rather than after.