laravoltdev/image repository overview

⁠laravoltdev/image

Ready-made Docker images for Laravolt 8 applications, published to Docker Hub: https://hub.docker.com/r/laravoltdev/image⁠.

Pull instead of building: every laptop, CI runner and server uses the same image, built once by this repository's GitHub Actions. The images extend ServerSideUp PHP⁠ (FrankenPHP on Debian) and add the PHP extensions Laravolt needs.

⁠Tags

Every release also publishes versioned tags such as php8.5-prod-v2.0.0 and php8.5-dev-v2.0.0. Pin a versioned tag in production. The plain tags follow main. They are rebuilt whenever src/ changes, and every Monday so that Debian security updates reach them.

Every image is built for linux/amd64 and linux/arm64, so it runs natively on Apple Silicon. The CI image is built on native arm64 runners. Each image ships with SBOM and provenance attestations.

⁠What is inside

PHP extensions added on top of ServerSideUp:

• bcmath, exif, gd, intl
• pdo_sqlsrv and sqlsrv (Microsoft SQL Server, with msodbcsql18)

ServerSideUp already provides zip, the PDO drivers for MySQL, PostgreSQL and SQLite, Redis, and OPcache.

The base is ServerSideUp v5 (SERVERSIDEUP_VERSION in src/Dockerfile).

The dev image adds Bun and Xdebug. Xdebug is off by default; turn it on with XDEBUG_MODE=debug or XDEBUG_MODE=coverage.

⁠Use it

⁠Production

FROM laravoltdev/image:php8.5-prod-v2.0.0

COPY --chown=www-data:www-data . /var/www/html
RUN composer install --no-dev --optimize-autoloader

⁠Local development

# docker-compose.yml
services:
  app:
    image: laravoltdev/image:php8.5-dev
    ports:
      - "8080:8080"   # app
      - "5173:5173"   # Vite (run `bun run dev` inside the container)
    volumes:
      - .:/var/www/html

docker compose up -d
docker compose exec app composer install
docker compose exec app bun install
docker compose exec app bun run dev

⁠Laravolt entrypoint hook

When these are set, the container runs php artisan laravolt:link on start. The dev image sets them by default.

AUTORUN_ENABLED=true
AUTORUN_LARAVOLT_LINK=true
APP_BASE_DIR=/var/www/html

The hook is safe to skip: if Laravel or Laravolt is not installed, it exits without failing the container.

⁠Security

Every runtime image is pushed by digest first and gets its tags only after that exact digest passes these checks (Trivy runs on both amd64 and arm64; the PHP checks run on amd64):

• PHP and extensions. The PHP version (the full patch version is printed in the log) and the extensions listed above are checked.
• No world-writable files outside sticky directories such as /tmp. ServerSideUp v4.3.1 to v5.0.4 shipped a world-writable Caddyfile (GHSA-xx74-jh2r-mgm3⁠).
• Session upload progress is off (session.upload_progress.enabled), until PHP fixes CVE-2026-115560. Laravel does not use it.
• Trivy scan. A critical vulnerability with a fix available stops the tagging, for the runtime and the dev image. The repository's Security tab lists every HIGH or CRITICAL vulnerability that has a fix, so each alert there calls for action. The ones still waiting for a fix are listed in the summary of each build run.
  • The scan skips kernel CVEs reported against linux-libc-dev. That package only holds the headers used to compile PHP extensions, and a container runs on the host's kernel. Patch the host for those.
• Pending Debian security updates are installed at build time.

The weekly rebuild keeps the plain tags patched. A workflow opens a PR when ServerSideUp publishes a newer release in the same major version, once it is 14 days old. Dependabot keeps the GitHub Actions current.

⁠Upgrading from v1 (ServerSideUp v4)

v2 moves the base to ServerSideUp v5. Most apps need no change. Check these points:

• A failed autorun step stops the container. For example, storage:link fails when public/ belongs to root. ServerSideUp v4 let that pass. Create the link in your Dockerfile, as root (php artisan storage:link), or set AUTORUN_LARAVEL_STORAGE_LINK=false. The autorun skips a link that already exists.
• FrankenPHP logs go to stderr. The format is JSON when there is no terminal. Set CADDY_LOG_FORMAT=console if something parses the old lines.
• TRUSTED_PROXY defaults to cloudflare. Behind your own load balancer or reverse proxy, set TRUSTED_PROXY=local so the app sees the real client IP.
• OPcache: with PHP_OPCACHE_ENABLE=1, files are no longer re-checked (PHP_OPCACHE_VALIDATE_TIMESTAMPS=0). This is fine for a baked image. If you mount code, set it back to 1.
• Requests with more than 16 KiB of headers get a 431. Large cookies are the usual cause.
• Laravel Octane can use the image's Caddyfile: php artisan octane:start --server=frankenphp --port=8080 --caddyfile=/etc/frankenphp/Caddyfile.
• The dev image sets AUTORUN_LARAVEL_SKIP_IF_NOT_FOUND=true, so it starts even before a project is mounted.

The ServerSideUp v5 release notes⁠ and migration guide⁠ cover the rest.

⁠Build locally

You should not need to, but:

docker build \
  --build-arg PHP_VERSION=8.5 \
  --build-arg BASE_VARIATION=frankenphp-debian \
  -t laravoltdev/image:php8.5-prod \
  src

docker build -f src/dev.Dockerfile --build-arg BASE_IMAGE=laravoltdev/image:php8.5-prod -t laravoltdev/image:php8.5-dev src

⁠Releasing

1. Merge to main. The plain tags are rebuilt and pushed after the checks in Security⁠. Pull requests run the same checks, and also build laravel-starter-kit's production image on top of the new image and load its login page.
2. Publish a GitHub release (vX.Y.Z). The same workflow builds the release tag and pushes the versioned tags and latest.
3. Changes to this README are copied to the Docker Hub overview⁠ by the docker-hub-readme workflow (needs the DOCKER_HUB_README_TOKEN secret).

⁠License

MIT. See LICENSE⁠. The images contain third-party software under their own licenses, such as ServerSideUp PHP (GPL-3.0), PHP, FrankenPHP and the Debian packages.