Docker Laravel Package

Getting Started

1. Install the package alongside your Laravel app:

   composer require smorken/docker
   

   The service provider is auto-discovered; no manual registration is usually needed.

2. Publish the Docker assets into your project root:

   php artisan vendor:publish --tag=docker
   

   If the tag is not recognized, run php artisan vendor:publish interactively and pick the Smorken\Docker provider to see exactly which tags and files are available.

3. Inspect what landed. You should now have a docker/ directory (per-service Dockerfiles and config), a docker-compose.yml, and an example environment file (often .env.docker). Start by reading the published docker/README.md and the compose file — those two files define the whole contract of the package.

4. Seed your environment. Copy the example env to .env (or merge the relevant keys) and set APP_KEY, database host, and ports. Then bring the stack up:

   docker-compose up -d
   docker-compose exec app php artisan key:generate
   docker-compose exec app php artisan migrate
   

First use case: a self-contained local dev stack — PHP-FPM + Nginx + MySQL + Redis — so a new developer can clone the repo, run docker-compose up, and have a working app without installing PHP, MySQL, or Redis on the host.

Implementation Patterns

Treat published files as owned by your app. The package is a scaffolding tool, not a runtime dependency. Once published, the Dockerfiles and compose file live in your repo and you edit them directly. The composer package mostly matters at publish time; afterwards you can diverge freely.

Layer customization in the Dockerfile. Add PHP extensions and system packages in the published docker/php/Dockerfile using the existing docker-php-ext-install pattern. Keep composer install above your COPY . . step so dependency layers cache across code-only changes.

Use a compose override for local-only services. Keep docker-compose.yml close to the published baseline (or your CI baseline) and put developer-specific bits — Xdebug, mailhog, a mounted host directory — in docker-compose.override.yml, which Docker Compose merges automatically. This keeps the canonical file clean and CI-friendly.

Separate container env from app env. Use the package's env example for infrastructure values (DB host = the compose service name, Redis host, ports) and keep Laravel's own .env for application configuration. When the two overlap, be explicit about which one the container actually reads.

Wrap repetitive commands. A small Makefile or bin/docker script around docker-compose exec app php artisan …, … composer …, and … phpunit pays off immediately; raw exec invocations with long paths get copied wrong.

CI pattern. Build the app image from the published Dockerfile, then use docker-compose (or just a service container) to run migrations and the test suite against real MySQL/Redis. Because the Dockerfiles are in your repo, CI doesn't need the package at all beyond the initial publish.

Gotchas and Tips

• Re-publishing can overwrite your edits. After publishing, use vendor:publish --force only after diffing against a fresh copy; otherwise you'll clobber customizations. Consider committing the published files and treating the package as a one-time generator.
• File permissions. Bind-mounted storage/ and bootstrap/cache/ frequently end up root-owned because the container process runs as a different UID than the host user. Fix with a UID/GID build arg or chown in an entrypoint, and be aware that artisan cache:clear inside the container can re-break permissions.
• localhost inside a container is the container. DB/Redis hosts must be the compose service names (mysql, redis), not 127.0.0.1. This is the most common "connection refused" cause.
• APP_KEY mismatch. If key:generate was run on the host and again in the container, sessions/encryption break in confusing ways. Generate once, commit nothing, share via the env file.
• Volume persistence surprises. docker-compose down -v deletes the MySQL data volume. Document it; new developers will do it by accident.
• Port collisions. Default 80/3306/6379 will clash with anything already running. Expose them as ${APP_PORT:-80}:80-style variables so each developer can override locally.
• Pin image tags. Replace any latest with specific PHP/Nginx/MySQL versions. Reproducible builds matter more than freshness for a base image layer.
• Architecture. On Apple Silicon, verify the base images have arm64 variants or add platform: linux/amd64; otherwise builds crawl under emulation.
• Debugging. docker-compose logs -f app and docker-compose exec app sh cover most issues; add a healthcheck to the DB service and depends_on: condition: service_healthy so the app doesn't race migrations against a booting MySQL.
• Adoption risk. This is a low-star, Bitbucket-hosted package. Check its PHP/Laravel version constraints and the Dockerfiles' base image versions before adopting; expect to modernize the published files yourself rather than relying on upstream updates.