jamesmorrison/laravel-queue repository overview

⁠Laravel Queue Docker Images

Dedicated Laravel queue runner extending jamesmorrison/php. Processes queued jobs continuously through Laravel's native Artisan worker.

Image: jamesmorrison/laravel-queue

⁠Versions and platforms

PHP versions: 8.2, 8.3, 8.4 and 8.5.

Platforms: linux/amd64 and linux/arm64.

Version tags follow the format jamesmorrison/laravel-queue:<version>. Test tags use <version>-test-<commit-sha>.

Each version builds on the matching jamesmorrison/php:<version> image. The application must support the selected PHP version.

⁠Runtime defaults

PHP-FPM is installed in the base image but is not started by this image. The queue runner does not provide an HTTP or FastCGI service.

⁠Queue execution

The runner executes php artisan queue:work immediately after startup validation.

The worker remains active when the queue is empty. Idle polling, job retries and timeouts follow Laravel's worker defaults.

The command does not specify a connection, queue name or additional worker options. Laravel's application configuration and command defaults apply.

Artisan output is written to the container logs. Worker exit status is propagated to the container; the entrypoint does not restart the worker or hide failures. Configure a container restart policy if workers should restart automatically, including after Laravel's queue:restart.

Tini forwards shutdown signals to the worker's process group, including subprocesses, and reaps orphaned processes. Laravel handles queue-worker shutdown signals; allow sufficient container stop grace time for active jobs.

Invalid startup paths or a missing artisan file cause the container to exit.

⁠Environment variables

QUEUE_FREQUENCY has been removed. If it is still supplied, startup fails with an explicit error instead of silently ignoring it.

⁠Application requirements

The image does not install Laravel or application dependencies. It requires:

• An artisan file inside LARAVEL_ROOT_DIR.
• Installed Composer dependencies and valid application configuration.
• Access to the queue backend, database and any services required by jobs.
• File permissions suitable for www-data, including writable Laravel storage and cache directories.

The runner should use the same application code and relevant configuration as the web application.

Queue retry, timeout, failed-job and concurrency policies are controlled by Laravel and the queue backend, not by this entrypoint.

⁠Inherited PHP runtime

PHP extensions, Composer and other tools are inherited from the PHP image⁠.

CLI OPcache is disabled by default. Queue workers are long-running PHP processes; disabling OPcache does not make an active worker reload application code.

This image replaces the PHP base image's startup script. It does not perform the base script's mail, FPM session or opt-in Datadog configuration.

⁠Build arguments

PHP settings are inherited from the selected base image.

⁠Health check

Checks that the native php artisan queue:work process is present.

This is a process-liveness check. Idle workers and long-running jobs do not become unhealthy merely because no batch has completed. It does not detect a hung worker or verify queue connectivity or job success. Docker health status alone does not restart the container.

⁠CI runtime checks

Both Build and Test workflows build and run an amd64 image for each PHP version before publishing multi-platform images. Runtime checks gate publishing on trunk pushes, weekly builds and test-branch pushes.

An Artisan test double checks the selected worker command, startup validation, exit-status propagation, health without completion timestamps and shutdown signal delivery to both the worker and a child process. These are container runtime checks, not application-level Laravel job tests.

Manual workflow runs accept base_tag_suffix, such as -test-<commit-sha>, to test against PHP test images. An empty suffix uses release base tags.

⁠Local runtime checks

From this repository root, build an image and run the same checks used by CI:

docker build --build-arg PHP_VERSION=8.5 -t laravel-queue:verify-8.5 . &&
  bash tests/run.sh laravel-queue:verify-8.5

Replace 8.5 with another supported PHP version, or pass an already-built image tag to bash tests/run.sh IMAGE.

To build and test all supported PHP versions in one run:

bash <<'SH'
set -euo pipefail
for version in 8.2 8.3 8.4 8.5; do
  docker build --build-arg PHP_VERSION="$version" -t "laravel-queue:verify-$version" .
  bash tests/run.sh "laravel-queue:verify-$version"
done
SH

Startup and exit-propagation checks have a 20-second deadline. Test containers are tracked for cleanup, including when a check times out.