Plume Laravel Package

Getting Started

• Install with Composer and pin the pre-release explicitly — composer require <vendor>/<package>:1.0.0-rc.3 — since ^1.0 will not resolve to a release candidate under the default stable minimum-stability.
• Read the README's Docker section first, before the PHP configuration section. This release's headline change is a Docker entrypoint, so the container is the primary integration surface and the docs are the fastest way to see the expected script path and contract.
• Sanity-check the container before wiring it into anything:

  docker run --rm --entrypoint sh <image>:1.0.0-rc.3 -c 'ls -la /entrypoint* /usr/local/bin/*'
  

  This tells you the exact entrypoint path and whether the default is a shell wrapper (ENTRYPOINT ["/entrypoint.sh"]) or exec-form. You will need that path in the next step.
• First real use case: boot the stock image against your app, confirm the default entrypoint does the expected setup (permissions, config caching, migrations), then override it. Don't start by customising — you want to see the baseline behaviour once so you can recognise when your override silently drops something.
• Publish any package config (php artisan vendor:publish --tag=<package>-config if a tag is documented) and commit it. Config published during an RC is the most likely thing to need re-publishing on the next tag.

Implementation Patterns

Config-driven setup over code. Prefer published config and environment variables over subclassing or editing vendor files. Anything you set in config/<package>.php survives a composer update cleanly; anything you patch into the image does not.

Wire the image into Compose rather than hand-rolling docker run. Keep the default entrypoint for web/app containers and use a distinct service for one-shot tasks:

services:
  app:
    image: <image>:1.0.0-rc.3
    volumes: [.:/var/www/html]

  worker:
    image: <image>:1.0.0-rc.3
    entrypoint: ["/entrypoint.sh"]
    command: ["php", "artisan", "queue:work", "--tries=3"]

Custom entrypoint as a thin wrapper, not a replacement. The documented pattern after rc.3 is to supply your own script that does the environment-specific prep and then hands off:

#!/bin/sh
set -e
wait-for-db.sh
php artisan migrate --force
exec "$@"          # exec is what preserves signal handling

Mount it at the image's conventional entrypoint path, or override entrypoint: and pass the original script path as the first command element. The wrapper approach keeps you one line away from upstream's default behaviour if you need to diff them later.

Use the entrypoint for the "prepare the runtime" phase only. Database wait loops, storage/ permission fixes, config/route caching, and one-off migrations belong there. Long-lived processes (queue workers, Octane, schedulers) should be command, not entrypoint — otherwise your override runs once and the process it spawns becomes PID 1 without supervision.

Separate local and CI usage of the same tag. Locally, bind-mount the source for fast iteration. In CI, build or pull the immutable 1.0.0-rc.3 tag and run tests inside it so the entrypoint's setup path is exercised on every pipeline run — that is the cheapest place to catch a broken migrate --force.

Log the entrypoint's decisions. Echo which branch of the script ran (waiting for db, running migrations, skipping in CI). When a container exits non-zero at boot, the first question is always which line of the entrypoint got there.

Gotchas and Tips

• Pre-release tags are not latest. docker pull <image> will very likely give you an older stable build, or fail if no stable exists. Always pin the full -rc.3 tag in Compose, CI, and deploy manifests, and expect to bump it deliberately.
• Composer stability. A bare 1.0.0-rc.3 constraint needs "minimum-stability": "RC" (or @RC on the require) in projects that haven't already relaxed it. Teams that bump minimum-stability globally to get this installed tend to leave it there and silently pull other unstable transitive deps — use the per-package flag instead.
• Overriding entrypoint: discards the default script entirely. Docker's entrypoint: key replaces rather than wraps. If you override, you are responsible for everything upstream did — permissions, config caching, wait loops. Check with docker image inspect <image>:1.0.0-rc.3 --format '{{json .Config.Entrypoint}} {{json .Config.Cmd}}' before deciding.
• Signal handling. Entrypoint scripts must use exec "$@" (or exec-form ENTRYPOINT) as their last line. A script that ends in php artisan ... without exec leaves a shell as PID 1, and docker stop will time out at 10s instead of shutting the worker down gracefully — visible as ERROR: Aborting / orphaned jobs in production.
• Script permissions and line endings. Bind-mounted entrypoint scripts from a Windows checkout arrive CRLF-encoded and non-executable. set -e plus a CRLF shebang produces exec format error or : not found, which reads like a missing file rather than a formatting problem. Add .gitattributes entries or run chmod +x in a build layer.
• config:cache ordering. If the entrypoint caches config before environment variables are present (common when the script runs before the orchestrator injects secrets), the container boots with empty config values and fails confusingly later. Cache after your env checks, or skip caching in the entrypoint and do it in the deploy step.
• RC docs lag the code. "Documentation updates" alongside a behaviour change means you should verify the described path against the actual image, not trust the README's path or flag names. Inspect the image; treat docs as a hint.
• Pin the image and the Composer package to the same version. The published image and the package code are released together; mixing 1.0.0-rc.3 in composer.json with an rc.2 image is the most common source of "works locally, fails in CI" reports during a pre-release cycle.
• Extension point to prefer: upstream ships the entrypoint as a standalone script precisely so it can be composed. Wrapper-plus-exec is the intended extension point; patching the file inside a derived Dockerfile is the fallback and will need updating every release.