DEV Community: Muhammad Yasir Amin

Lesson 1: Deploying Laravel with Docker

Muhammad Yasir Amin — Sun, 08 Nov 2026 16:10:30 +0000

Laravel Docker Lessons · Lesson 1

This lesson documents the Docker setup I created for the docker-laravel application: Laravel 12 running inside one PHP 8.2 + Apache container. It is the first entry in a practical series in the Build & Learn blog section. The goal is to understand the files already in the project, prepare Laravel's dependencies, and start the application using Docker Compose.

The configuration uses a host-mounted checkout and local HTTP access. It gives us a foundation for learning container deployment; it does not yet define a complete production release pipeline.

1. Understand the application and request path

The service is named web. Docker builds its image from the root Dockerfile and names that image my-laravel-app. A browser request to http://localhost:8081 reaches Apache on port 80 inside the container. Apache serves Laravel from /var/www/html/public, with public/index.php as the application's front controller.

The actual setup has one service: PHP and Apache run together in the web container.

The files that define this setup are:

docker-laravel/
├── Dockerfile
├── docker-compose.yaml
├── .docker/
│   └── apache/
│       └── default.conf
├── public/
│   ├── index.php
│   └── .htaccess
├── storage/
└── bootstrap/cache/

composer.json requires PHP ^8.2 and Laravel ^12.0. The project's lock file resolves Laravel to 12.69.3. The Compose file contains no separate database, Redis, queue-worker, or frontend-development service.

2. Read the existing Dockerfile

Here is the project's Dockerfile, reproduced from the implementation:

FROM php:8.2-apache

WORKDIR /var/www/html

RUN apt-get update && apt-get install -y \
    libzip-dev \
    unzip \
    && docker-php-ext-install zip pdo_mysql

COPY . /var/www/html

RUN chown -R www-data:www-data /var/www/html
RUN chown -R www-data:www-data /var/www/html/storage /var/www/html/bootstrap/cache
RUN chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache

EXPOSE 80

php:8.2-apache supplies PHP and Apache in one image. WORKDIR sets the directory used by later instructions and container commands. The package-install step adds libzip-dev and unzip, then builds the PHP zip and pdo_mysql extensions.

COPY . /var/www/html includes the application checkout in the image. The ownership commands assign the copied files to Apache's www-data account and make storage and bootstrap/cache writable with mode 775. These directories hold logs, sessions, compiled views, and Laravel's cached bootstrap files.

EXPOSE 80 documents the container's HTTP port. The host port is published by Compose. The Dockerfile inherits the base image's Apache startup command; it adds no custom entrypoint, dependency-install command, key generation, or migration step.

Composer and Node.js are not installed by this Dockerfile. Application dependencies and compiled frontend assets must therefore be prepared outside this container with compatible host tools.

3. Read the existing Compose configuration

version: '3'

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    image: my-laravel-app
    ports:
      - "8081:80"
    volumes:
      - .:/var/www/html
      - /var/www/html/storage
      - /var/www/html/bootstrap/cache
      - ./.docker/apache/default.conf:/etc/apache2/sites-enabled/000-default.conf
    working_dir: /var/www/html
    user: "www-data"

build.context: . uses the project root as the build context, and dockerfile: Dockerfile selects the file above.
image: my-laravel-app names the built image; it does not push that image to a registry.
8081:80 maps host port 8081 to Apache's port 80.
working_dir: /var/www/html makes that directory the default for commands such as docker compose exec web php artisan ....
user: "www-data" selects the runtime account. Runtime permissions still depend on the mounted files and the host platform.

The file retains version: '3'. Modern Docker Compose reports that field as obsolete and ignores it; the service configuration still resolves. No explicit restart policy, health check, or named volume is declared.

How the four mounts work

The root bind mount shares the checkout; two anonymous volumes overlay Laravel's writable directories.

.:/var/www/html is a bind mount. At runtime it overlays the image's application directory with the host checkout, so PHP source changes are immediately visible. The host's vendor directory and built assets are also visible through this mount. Ownership set during image build does not automatically rewrite ownership of the host files.

/var/www/html/storage and /var/www/html/bootstrap/cache are anonymous Docker volumes because their entries specify only container paths. They overlay those two subdirectories. Logs and cache files written there do not simply appear in the equivalent host directories. Anonymous volumes can outlive a container, but this file gives them no stable names; a later deployment may attach different volumes. Treat retained data deliberately when recreating services.

The final bind mount places .docker/apache/default.conf at Apache's enabled-site path, /etc/apache2/sites-enabled/000-default.conf. The project directory, database files, and environment file remain supplied by the host checkout.

4. Serve Laravel through Apache's public directory

The mounted virtual-host file contains:

<VirtualHost *:80>
    DocumentRoot /var/www/html/public

    <Directory /var/www/html>
        AllowOverride All
    </Directory>
</VirtualHost>

The DocumentRoot points at Laravel's public directory. This is where the HTTP entrypoint and public assets live. The AllowOverride All directive allows per-directory rules such as the existing public/.htaccess to take effect.

Laravel's .htaccess uses mod_rewrite to send requests for paths that are not existing files or directories to index.php. There is no a2enmod rewrite instruction in this project's Dockerfile, so allowing overrides is not evidence that rewriting is enabled. Check the loaded modules before assuming every Laravel route works:

docker compose exec web apache2ctl -M

Look for rewrite_module. If it is absent, enabling that module in the image is a required follow-up for rewritten routes. That change is not part of the configuration documented in this lesson.

5. Prepare the checkout before starting Docker

Use Docker Desktop with its Linux engine running, Docker Compose, PHP 8.2 or newer, Composer, and Node.js 20.19+ on the 20.x line or 22.12+. Those Node requirements come from the installed Vite 7 and Laravel Vite plugin packages. Run the following preparation commands from the application root. The Docker image does not perform these steps for you.

First, create an environment file only when the checkout does not already have one. In PowerShell:

if (-not (Test-Path .env)) { Copy-Item .env.example .env }

Install the locked PHP dependencies with a PHP-compatible Composer executable:

php -v
composer install

When creating a new local environment whose APP_KEY is empty, generate its key once:

php artisan key:generate

The checked-out local environment uses SQLite and file sessions. The example environment instead uses database-backed sessions, cache, and queues. A database/database.sqlite file exists in this project, and the Apache PHP base image includes SQLite PDO support. Installing pdo_mysql does not switch the application to MySQL or create a database service.

For a fresh SQLite checkout without its database file, create it before running migrations:

if (-not (Test-Path database/database.sqlite)) {
    New-Item -ItemType File -Path database/database.sqlite | Out-Null
}

Apply the existing migrations on the prepared local database. They create the users/session, cache, and queue tables used by Laravel's configured drivers:

php artisan migrate

If the application generates absolute local URLs, set the local APP_URL to match the address you use, such as http://localhost:8081. That is a local environment choice; Compose's 8081:80 mapping is what exposes the container.

The project declares npm run build for Vite assets. To prepare those assets using the existing lock file:

npm ci
npm run build

There is no Vite service or Vite port mapping in this Compose file. The default Laravel welcome template has a fallback stylesheet when no build manifest or hot file exists, so seeing the welcome page alone does not prove the frontend asset build has run.

6. Build, start, and inspect the service

Validate the service list, then build and start the container:

docker compose config --services
docker compose up -d --build
docker compose ps
docker compose logs --tail=100 web

The service-list command resolves web. Open http://localhost:8081 after the container starts. Useful checks inside the existing service are:

docker compose exec web php -v
docker compose exec web php -m
docker compose exec web php artisan migrate:status
docker compose exec web apache2ctl -M

Inspect php -m for the application's database driver and the installed zip extension. If Laravel reports a write-permission error, inspect the mounted storage/cache paths rather than assuming the Dockerfile's build-time ownership commands changed the host checkout. Rewritten-route failures require checking mod_rewrite as described above.

SQLite also needs write access to both its file and containing directory. These checks should succeed for the configured www-data runtime account:

docker compose exec web test -w /var/www/html/database/database.sqlite
docker compose exec web test -w /var/www/html/database
docker compose exec web test -w /var/www/html/storage
docker compose exec web test -w /var/www/html/bootstrap/cache

To stop the application temporarily:

docker compose stop

To remove the service container and its Compose network:

docker compose down

Review the anonymous volumes and any data you need before recreating the environment. The project has no named-volume backup or restore workflow.

7. What this first lesson establishes

This implementation separates the image definition, service configuration, and Apache virtual host into three small files. PHP and Apache run together; port 8081 exposes the application; the checkout supplies the runtime source; and dedicated anonymous mounts hold Laravel's writable storage and cache directories.

The current project has no .dockerignore. Its COPY . instruction therefore includes whatever is in the build context, including local environment files and dependency folders. This local learning image should not be distributed as a production artifact without addressing that build context. HTTPS, a release-specific image build, backups, and a queue-worker service are also outside the implemented setup.

During this review, Compose successfully resolved the single web service. Docker Desktop's Linux engine was unavailable, so a running container and HTTP response were not verified. The startup and diagnostic commands above are the steps to check this configuration on a machine with a running Docker engine.

Future entries in Laravel Docker Lessons will continue in the same Build & Learn blog section as the implementation develops.

References

The project files are the source of truth for the configuration shown here. For the underlying behavior, see Docker Compose's application model and commands, Docker bind mounts, Docker volumes, the official PHP 8.2 image source, and Laravel 12 deployment documentation.

Get the matching lesson source

Browse the lesson-1 snapshot for the Dockerfile, Compose file and Apache configuration discussed here. The repository's main branch contains later lessons, so it may differ from the files in this guide.

Use the course repository lesson index to select a lesson tag, and read the written correction notes before following historical snapshots.

Originally published at yasiramin.dev.

Lesson 2: Adding MySQL to Laravel’s Apache Docker Setup

Muhammad Yasir Amin — Sun, 08 Nov 2026 16:10:07 +0000

Laravel Docker Lessons · Lesson 2

In Lesson 1, Laravel ran in a single PHP 8.2 + Apache container. Lesson 2 adds a separate MySQL 8.0 database service, enables Apache rewriting and tightens the virtual-host directory configuration. This walkthrough uses the committed files and separates configured infrastructure from Laravel's current database selection.

Use the correct lesson snapshot

This article documents the lesson-2 GitLab tag. The repository is public; you can inspect the tagged files without requesting access. Its commit is 189d6836d37046f066137c2211d2fa1a81c6ccda.

To inspect it without changing your current lesson checkout, create a separate Git worktree:

git fetch origin --tags
git worktree add --detach ../docker-laravel-lesson-2 lesson-2
cd ../docker-laravel-lesson-2

Prepare the host dependencies with composer install, npm ci and npm run build. For a fresh checkout, copy .env.example to .env and generate a local key with php artisan key:generate. The Dockerfile does not install Composer or Node.js. Review the database connection explicitly before running migrations.

1. Two services and two different port mappings

The web service still combines PHP and Apache. HTTP enters at localhost:8081 and reaches Apache on port 80. The new db service runs MySQL on container port 3306 and publishes host port 3307 for local clients. Compose supplies service-name resolution on its default network.

Lesson 2 service architecture: browser, Apache PHP web container and MySQL database.

2. The Apache Dockerfile

FROM php:8.2-apache

WORKDIR /var/www/html

RUN apt-get update && apt-get install -y \
    libzip-dev \
    unzip \
    && docker-php-ext-install zip pdo_mysql

RUN a2enmod rewrite

COPY . /var/www/html

RUN chown -R www-data:www-data /var/www/html
RUN chown -R www-data:www-data /var/www/html/storage /var/www/html/bootstrap/cache
RUN chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache

The base remains php:8.2-apache. ZIP and pdo_mysql are installed, and RUN a2enmod rewrite is new. Laravel's public/.htaccess uses rewriting to route requests to its front controller. The ownership and writable-directory instructions remain. The earlier EXPOSE 80 line was removed; the Compose port mapping still publishes HTTP.

3. The complete Compose file

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    image: my-laravel-app
    ports:
      - "8081:80"
    volumes:
      - .:/var/www/html
      - /var/www/html/storage
      - /var/www/html/bootstrap/cache
      - ./.docker/apache/default.conf:/etc/apache2/sites-enabled/000-default.conf
    working_dir: /var/www/html
    user: "www-data"
    depends_on:
      - db
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: laravel_app
      MYSQL_PASSWORD: secret
    ports:
      - 3307:3306
    volumes:
      - dbdata:/var/lib/mysql
volumes:
  dbdata:

The obsolete top-level version field is removed. depends_on: db starts the database service before the web service, but there is no health check or readiness condition. MySQL may still be initializing when Laravel first connects. Check database logs before treating a connection error as a credentials problem.

The project bind mount and anonymous storage and bootstrap/cache volumes remain. The Apache configuration is mounted into /etc/apache2/sites-enabled/000-default.conf. The new named dbdata volume is independent of those anonymous Laravel volumes.

4. Apache serves only the public directory

<VirtualHost *:80>
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/html/public

    <Directory /var/www/html/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

The directory block now targets /var/www/html/public, matching DocumentRoot, and explicitly grants access with Require all granted. AllowOverride All permits the project's .htaccess rules. PHP and Apache still run together; no Nginx service exists in this tag.

Database settings: distinguish the container from Laravel

The committed .env.example still sets DB_CONNECTION=sqlite. Adding a MySQL container does not automatically change Laravel's database connection. The inspected local checkout also selects SQLite. The repository therefore demonstrates the MySQL service configuration, but does not establish that Laravel has switched to MySQL.

For a deliberate local MySQL connection, the values below are derived from the Compose service. They are a suggested private .env change, not a committed configuration or a verified migration:

DB_CONNECTION=mysql
DB_HOST=db
DB_PORT=3306
DB_DATABASE=laravel_app
DB_USERNAME=root
DB_PASSWORD=root

Inside the web container, db:3306 is the database endpoint. A host-side database client instead uses 127.0.0.1 and the published host port. The Compose sample uses the root password root. Its MYSQL_PASSWORD: secret does not create a separate application user because MYSQL_USER is absent. These are local example credentials, not production credentials.

After intentionally configuring MySQL and confirming it is ready, run docker compose exec web php artisan config:clear, then docker compose exec web php artisan migrate. Migrations create the application tables in the selected database; they do not transfer existing SQLite records. The database-backed session, cache and queue defaults also need their tables in the selected connection.

The named dbdata volume stores MySQL data at /var/lib/mysql. Initialization variables apply when the data directory is first initialized; changing Compose values does not reset an existing database. Preserve this volume when stopping the stack.

Docker service connections and configuration review notes.

5. Start and inspect this lesson

docker compose config
docker compose up -d --build
docker compose ps
docker compose logs --tail=80 db web
docker compose exec web apache2ctl -t
docker compose exec web php -m

Use http://localhost:8081 for HTTP and 127.0.0.1:3307 for a host-side MySQL client. The PHP module check should include pdo_mysql before attempting a MySQL connection. These are reproduction and diagnostic commands derived from this tag; this review did not start the Lesson 2 stack or migrate a database.

Run lessons separately. Lesson 2 and Lesson 3 both name their application image my-laravel-app; rebuilding one can replace the local tag used by the other. Their unqualified Compose commands also use the checkout directory as the project name. Keep track of which checkout, image and volumes you are using.

What this lesson adds

Lesson 2 introduces a database container, persistent MySQL storage, service networking and explicit Apache rewrite support. The committed environment example still chooses SQLite. A production deployment would need its own credentials, database-access policy and operational configuration; those are not supplied by this lesson.

Continue with Lesson 3: Laravel with Nginx, PHP-FPM and MySQL in Docker. Visit the course for the published video lessons as they are added.

References

The tagged project files are the source of truth. Supporting behavior is documented in Docker Compose startup order, the official MySQL image, Laravel database configuration and Nginx FastCGI configuration.

Originally published at yasiramin.dev.

Lesson 3: Laravel with Nginx, PHP-FPM and MySQL in Docker

Muhammad Yasir Amin — Sun, 08 Nov 2026 16:09:51 +0000

Lesson 4 correction: use the fixed Nginx configuration

Update, 16 October 2026: the original lesson-3 tag below is preserved as its historical snapshot. The corrected, tested configuration is now part of the lesson-4 tag; the old tag has not been moved or rewritten.

The fixes replace listen 80. with listen 80;, restore $query_string, and add the missing FastCGI and access-rule semicolons. Use this complete corrected server block:

.docker/nginx/default.conf

server {
    listen 80;
    index index.php index.html;
    root /var/www/html/public;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass web:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
        fastcgi_buffers 16 16k;
        fastcgi_buffer_size 32k;
    }

    location ~ /\.ht {
        deny all;
    }
}

Lesson 4 also restores the PHP image build definition and explicitly connects Laravel containers to db:3306. The new Compose file adds a MySQL readiness health check, retains the named database volume and provides configurable HTTP/database host ports. Its optional scheduler service is separate from Nginx and PHP-FPM.

After preparing dependencies and the private environment, validate and start the updated stack:

git fetch origin --tags
git switch main
git pull --ff-only origin main
docker compose --profile scheduler config --quiet
docker compose up -d --build db web nginx
docker compose exec web php artisan config:clear
docker compose exec web php artisan migrate --force
docker compose restart nginx
docker compose exec nginx nginx -t

Save or commit any local edits before switching or pulling. This follows the current main branch; for the exact corrected lesson snapshot, inspect lesson-4 in a separate checkout. The Lesson 4 guide includes the full Compose file, scheduler command, database migration and Blade user page. Read Lesson 4: Laravel Scheduler and Cron Jobs with Docker.

Historical snapshot follows: configuration errors described below refer to the original Lesson 3 tag, before the corrections above.

Laravel Docker Lessons · Lesson 3

Lesson 3 changes the architecture from Apache with embedded PHP to separate Nginx and PHP-FPM services, while retaining MySQL. It builds on Lesson 2: Adding MySQL to Laravel’s Apache Docker Setup. This article reproduces the pushed tag exactly, including the configuration issues that need attention before the intended request path can work.

Snapshot status: the committed Nginx file contains syntax errors, and the web service no longer has a build definition. This is a configuration walkthrough and troubleshooting lesson, not a claim that the tagged stack starts successfully unchanged.

Use the correct lesson snapshot

This article documents the lesson-3 GitLab tag. The repository is public; you can inspect the tagged files without requesting access. Its commit is 640e6e7e1b021b8a8b36a158d5cfdbaaef844996.

To inspect it without changing your current lesson checkout, create a separate Git worktree:

git fetch origin --tags
git worktree add --detach ../docker-laravel-lesson-3 lesson-3
cd ../docker-laravel-lesson-3

1. The intended three-service request path

The browser enters through localhost:8080, mapped to Nginx port 80. Nginx serves files from /var/www/html/public and is intended to forward PHP requests to web:9000 using FastCGI. The web service should run PHP-FPM. MySQL remains reachable internally as db:3306; the host database mapping changes to 3308:3306.

Lesson 3 intended architecture: browser, Nginx, PHP FPM and MySQL; configuration needs correction.

2. PHP switches from Apache to FPM

FROM php:8.2-fpm

WORKDIR /var/www/html

RUN apt-get update && apt-get install -y \
    libzip-dev \
    unzip \
    && docker-php-ext-install zip pdo_mysql

COPY . /var/www/html

RUN chown -R www-data:www-data /var/www/html
RUN chown -R www-data:www-data /var/www/html/storage /var/www/html/bootstrap/cache
RUN chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache

The base image becomes php:8.2-fpm. Apache and a2enmod rewrite are removed. ZIP, PDO MySQL, the application copy and Laravel directory permissions remain. PHP-FPM receives FastCGI requests; it does not replace Nginx as an HTTP server. Both services mount the same checkout so the script paths agree.

3. The actual Compose services

services:
  web:
    image: my-laravel-app
    volumes:
      - .:/var/www/html
      - /var/www/html/storage
      - /var/www/html/bootstrap/cache
    working_dir: /var/www/html
    user: "www-data"
    depends_on:
      - db

  nginx:
    image: nginx:latest
    ports:
      - "8080:80"
    volumes:
      - .:/var/www/html
      - ./.docker/nginx/default.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - web

  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: laravel_app
      MYSQL_PASSWORD: secret
    ports:
      - "3308:3306"
    volumes:
      - dbdata:/var/lib/mysql
volumes:
  dbdata:

The web service has no published HTTP port and no Apache config mount. Nginx gains the HTTP mapping and its own configuration mount. It depends on web, while web depends on db. These short dependencies control startup order, not application readiness. The MySQL named volume remains dbdata.

Image preparation gap: web refers to my-laravel-app but no longer declares build. Therefore docker compose up --build does not rebuild this Dockerfile. A previously built Apache image can still occupy that name. At review time, the local image's command was apache2-foreground, confirming that image reuse needs attention. To deliberately build the FPM image from this tag before starting it, use:

docker build -t my-laravel-app .
docker image inspect my-laravel-app --format "{{json .Config.Cmd}}"

This is an explicit reproduction step derived from the Dockerfile, not a build step already automated by Compose. Inspect the result for the FPM startup command before expecting web:9000 to accept connections. Avoid running Apache and FPM lessons simultaneously under the same local image tag.

4. Read the committed Nginx configuration

server {
    listen 80.
    index index.php index.html;
    root /var/www/html/public;

    location / {
        try_files $uri $uri/ /index.php?query_string;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass web:9000
        fastcgi_index index.php
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name
        fastcgi_param PATH_INFO $fastcgi_path_info
        fastcgi_buffers 16 16k
        fastcgi_buffer_size 32k
    }

    location ~ /\.ht {
        deny all
    }
}

The root points to Laravel's public directory. The PHP location is intended to send FastCGI requests to web, with SCRIPT_FILENAME identifying the PHP script and PATH_INFO passing path information. The final location is intended to deny requests for .ht files. Unlike Apache, Nginx does not consume Laravel's .htaccess.

5. Configuration corrections required before startup

An isolated Nginx syntax check against the exact tagged file failed with host not found in "80." of the "listen" directive. The check used a temporary container and a read-only configuration mount; it did not restart the application stack or change the source files.

The following are recommended corrections to the displayed snapshot. They were not committed as part of the lesson-3 tag, and this article does not silently substitute them for the source:

listen 80. must become listen 80;.
The front-controller fallback /index.php?query_string needs the variable: /index.php?$query_string.
Add trailing semicolons to fastcgi_pass, fastcgi_index, both fastcgi_param directives, fastcgi_buffers, fastcgi_buffer_size and deny all.
Build the PHP-FPM Dockerfile explicitly, or restore a Compose build definition in a later reviewed change.

A YAML configuration check can succeed while the mounted Nginx file is invalid. After making the corrections in your own checkout and preparing the FPM image, use the service-level checks below. If nginx -t fails, resolve that before testing HTTP:

docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail=80 nginx web db
docker compose exec web php -m

The --no-deps syntax check can also report an unresolved web upstream if no web service is running. That is distinct from the punctuation errors. The lesson files were reviewed without restarting the existing stack, rebuilding its image or migrating its database.

Docker service connections and configuration review notes.

Database settings: distinguish the container from Laravel

For a deliberate local MySQL connection, the values below are derived from the Compose service. They are a suggested private .env change, not a committed configuration or a verified migration:

DB_CONNECTION=mysql
DB_HOST=db
DB_PORT=3306
DB_DATABASE=laravel_app
DB_USERNAME=root
DB_PASSWORD=root

What changes, and what still needs work

Lesson 3 defines the separation between HTTP serving, PHP execution and database storage. Its intended HTTP port is 8080 and its host-side MySQL port is 3308. The committed Nginx syntax and image preparation must be resolved to make that architecture operational. Laravel's tracked environment example remains SQLite, so a MySQL switch must be deliberate.

Return to Lesson 1 · Lesson 2: Adding MySQL to Laravel’s Apache Docker Setup · Browse the course. New lesson videos can be added to the course when published.

References

Originally published at yasiramin.dev.

Lesson 4: Laravel Scheduler & Cron Jobs with Docker

Muhammad Yasir Amin — Sun, 08 Nov 2026 16:09:37 +0000

Laravel Docker Lessons · Lesson 4

Run Laravel scheduled tasks in Docker and watch a real five-second example on a Blade page. This lesson creates one synthetic user per run, with a random test name, a timestamped unique email and a hashed password. It also carries forward the Nginx fixes needed after the Lesson 3 snapshot.

The source of truth is the lesson-4 tag. Repository access may require authorization. The recorded Urdu walkthrough is now available: watch Lesson 4 on YouTube.

Builds on the lesson-3 snapshot. This lesson fixes that snapshot's Nginx configuration, adds a Docker scheduler service, and displays generated users on a Blade page.

How it works

app/Console/Commands/CreateTestUser.php registers demo:create-user. One invocation creates one user, not a permanent loop.
routes/console.php schedules the command with everyFiveSeconds(). The schedule is skipped unless scheduler-demo.enabled is true. withoutOverlapping(1) uses a one-minute lock expiry to avoid overlapping command executions in the single scheduler container.
The optional Compose scheduler service runs php artisan schedule:work --no-interaction in the foreground using the same PHP 8.2 FPM image and source as web. It explicitly enables the example. The web service leaves the example disabled.
Both services connect to MySQL at db:3306. The scheduler uses the file cache for its local overlap lock; run just one scheduler replica. This setup does not claim a distributed lock across containers.
/scheduler-demo renders a paginated Blade table of users marked is_scheduler_demo = true. It shows ID, name, email and UTC creation time, with newest users first. Automatic five-second page refresh can be paused. Passwords and ordinary users are not displayed.

The name is test plus a random integer from 1 to 1000, such as test42. The email includes that name, a UTC timestamp, a ULID suffix and the reserved domain example.com. For example, the format is test42.YYYYMMDDHHMMSS.ulid@example.com. The suffix avoids collisions if two invocations have the same name and second. Passwords are random and hashed through the existing User model. No email is sent.

Why a scheduler worker instead of a five-second crontab

Ordinary five-field cron expressions run at minute granularity. Laravel handles sub-minute repetition through everyFiveSeconds(). This Compose setup uses a persistent schedule:work process, so it does not install an OS cron daemon or add a host crontab. The worker waits for the next minute boundary before starting its first schedule:run; that run continues until the minute ends to handle five-second tasks.

On a separate server that already runs the Laravel scheduler from cron, the conventional trigger is:

* * * * * cd /path/to/application && php artisan schedule:run >> /dev/null 2>&1

That line is an explanation of the alternative, not a file installed by this repository. Do not also run that trigger against this demo while its Compose scheduler is running, or you can create duplicate executions.

Start the application

Use PHP 8.2+ and Docker Compose. Composer dependencies and frontend assets are prepared on the host, as in earlier lessons; the Dockerfile does not install Composer or Node.js.

The PHP services mount an anonymous vendor volume populated from the built image. This keeps Composer's thousands of files on the Docker filesystem, avoiding slow Windows bind-mount reads on each five-second command. Run composer install before building. If Composer dependencies change later, stop this stack with docker compose --profile scheduler down (without -v), then rebuild and start it again; newly created anonymous vendor volumes receive the rebuilt dependencies. The named MySQL volume is retained. Anonymous storage/cache volumes also belong to the local containers, so retain any needed local uploads/logs separately before recreating the entire stack.

For a fresh checkout:

cp .env.example .env
composer install
php artisan key:generate
npm ci
npm run build
docker compose config --quiet
docker compose up -d --build db web nginx
docker compose exec web php artisan config:clear
docker compose exec web php artisan migrate --force
docker compose exec nginx nginx -t

In PowerShell, use Copy-Item .env.example .env instead of cp if preferred. Do not overwrite an existing .env or regenerate an existing application key. When updating an existing checkout, install changed dependencies if needed, rebuild/recreate services, clear the container config and run migrations. The new migration adds an indexed boolean is_scheduler_demo, defaulting to false; existing users remain ordinary users.

Compose explicitly supplies Laravel's MySQL connection, including clearing DB_URL and DB_SOCKET, so the host's SQLite example does not accidentally direct container writes elsewhere. For host-side Artisan commands the original .env still applies; run migrations and this example inside Docker to use the Docker database.

Nginx defaults to http://localhost:8080; MySQL is reachable by a host client at 127.0.0.1:3308. Inside Docker use db:3306. If host ports are occupied, set APP_PORT and DB_FORWARD_PORT in your private .env, for example APP_PORT=8082 and DB_FORWARD_PORT=3309, then recreate the affected services. The dbdata volume is retained. Example root credentials are for this local tutorial; existing MySQL volumes retain their original initialization credentials.

If you recreate web while Nginx remains running and see a 502 response, run docker compose restart nginx so Nginx resolves the current PHP-FPM container address again.

Run and record the demo

# Optional: create exactly one user before starting the repeating schedule.
docker compose run --rm -e SCHEDULER_DEMO_ENABLED=true web php artisan demo:create-user

# Show the registered five-second task, then start the dedicated scheduler.
docker compose --profile scheduler run --rm scheduler php artisan schedule:list
docker compose --profile scheduler up -d scheduler
docker compose logs -f scheduler

Open http://localhost:8080/scheduler-demo (or your configured HTTP port). Wait for the next minute boundary after starting the worker, then rows should appear approximately every five seconds. This is not a hard real-time guarantee: execution time, machine load and refresh timing affect what appears on screen. The table shows 15 users per page and only rows created by this demo.

Command output is appended to the scheduler container's storage/logs/scheduler-demo.log:

docker compose exec scheduler tail -n 20 storage/logs/scheduler-demo.log

The table may contain repeated names because the random range is deliberately only 1–1000. Emails remain distinct. A direct demo:create-user invocation in web without the explicit environment opt-in fails without inserting a record.

Stop after recording

docker compose stop scheduler
docker compose --profile scheduler ps

Refresh the page manually to confirm the count stays stable. The scheduler creates roughly 12 users per minute while active, so stop it after the example. It is behind the scheduler profile and is not started by a normal docker compose up -d.

To stop the entire local stack while preserving MySQL data:

docker compose --profile scheduler down

Do not add -v if you want to retain the lesson's database. Recreate the scheduler after changing its code or environment; its restart: unless-stopped policy restarts a failed worker but respects an explicit stop.

Corrections carried forward from Lesson 3

Replaced the invalid listen 80. with listen 80;.
Restored $query_string in the front-controller fallback.
Added missing semicolons to FastCGI directives and deny all.
Restored a Docker build definition shared by web and scheduler.
Added MySQL readiness checking and explicit Laravel container DB settings.
Added an image-populated anonymous vendor volume for responsive PHP execution on Docker Desktop with a Windows source bind mount.
Removed the unused MYSQL_PASSWORD setting, which had no accompanying MYSQL_USER.
Added .dockerignore so local .env, Git history, generated publishing/video files and host Node dependencies are not copied into the image. Runtime source remains a bind mount, matching this local development architecture.
Used COPY --chown=www-data:www-data instead of recursively changing ownership of the entire copied project in later image layers; Laravel's writable directories retain mode 775.

The old lesson tags are immutable snapshots; these fixes belong to lesson-4, rather than rewriting lesson-3.

Checks

php vendor/bin/pest
php vendor/bin/pint --test
docker compose --profile scheduler config --quiet
docker compose exec nginx nginx -t

The feature tests use an in-memory SQLite database and cover command output data, password hashing, unique emails, opt-in behavior, the five-second schedule, demo-only visibility and pagination. Container smoke verification separately checks MySQL inserts and the actual scheduler timing.

The implemented command, schedule and database marker

These are the actual lesson files. The command performs one insert; Laravel supplies the repetition. The boolean marker lets the demo page list only these synthetic records without mixing in ordinary users.

app/Console/Commands/CreateTestUser.php

<?php

namespace App\Console\Commands;

use App\Models\User;
use Illuminate\Console\Command;
use Illuminate\Support\Str;

class CreateTestUser extends Command
{
    protected $signature = 'demo:create-user';

    protected $description = 'Create one test user for the Lesson 4 scheduler demo';

    public function handle(): int
    {
        if (! config('scheduler-demo.enabled')) {
            $this->warn('Scheduler demo is disabled. Set SCHEDULER_DEMO_ENABLED=true to enable it.');

            return self::FAILURE;
        }

        $name = 'test'.random_int(1, 1000);
        $email = $name.'.'.now()->utc()->format('YmdHis').'.'.strtolower((string) Str::ulid()).'@example.com';

        $user = User::create([
            'name' => $name,
            'email' => $email,
            'password' => Str::random(40),
            'is_scheduler_demo' => true,
        ]);

        $this->info("Created user #{$user->id}: {$user->name} <{$user->email}>");

        return self::SUCCESS;
    }
}

config/scheduler-demo.php

<?php

return [
    'enabled' => env('SCHEDULER_DEMO_ENABLED', false),
];

routes/console.php

<?php

use Illuminate\Foundation\Inspiring;
use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\Schedule;

Artisan::command('inspire', function () {
    $this->comment(Inspiring::quote());
})->purpose('Display an inspiring quote');

Schedule::command('demo:create-user')
    ->everyFiveSeconds()
    ->withoutOverlapping(1)
    ->when(fn () => config('scheduler-demo.enabled'))
    ->appendOutputTo(storage_path('logs/scheduler-demo.log'));

database/migrations/2026_10_16_000001_add_is_scheduler_demo_to_users_table.php

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::table('users', function (Blueprint $table) {
            $table->boolean('is_scheduler_demo')->default(false)->index();
        });
    }

    public function down(): void
    {
        Schema::table('users', function (Blueprint $table) {
            $table->dropColumn('is_scheduler_demo');
        });
    }
};

The existing User model hashes the password through its hashed cast. It now also includes is_scheduler_demo in $fillable and casts the marker to boolean.

Docker Compose: share PHP, separate the scheduler process

docker-compose.yaml

x-laravel-environment: &laravel-environment
  DB_URL: ""
  DB_SOCKET: ""
  DB_CONNECTION: mysql
  DB_HOST: db
  DB_PORT: 3306
  DB_DATABASE: laravel_app
  DB_USERNAME: root
  DB_PASSWORD: root

x-laravel-service: &laravel-service
  build:
    context: .
    dockerfile: Dockerfile
  image: my-laravel-app
  working_dir: /var/www/html
  user: "www-data"
  volumes:
    - .:/var/www/html
    - /var/www/html/vendor
    - /var/www/html/storage
    - /var/www/html/bootstrap/cache
  environment:
    <<: *laravel-environment
    SCHEDULER_DEMO_ENABLED: "false"
  depends_on:
    db:
      condition: service_healthy

services:
  web:
    <<: *laravel-service

  scheduler:
    <<: *laravel-service
    profiles: ["scheduler"]
    init: true
    command: ["php", "artisan", "schedule:work", "--no-interaction"]
    restart: unless-stopped
    environment:
      <<: *laravel-environment
      CACHE_STORE: file
      SCHEDULER_DEMO_ENABLED: "true"

  nginx:
    image: nginx:latest
    ports:
      - "${APP_PORT:-8080}:80"
    volumes:
      - .:/var/www/html:ro
      - ./.docker/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - web

  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: laravel_app
    ports:
      - "${DB_FORWARD_PORT:-3308}:3306"
    volumes:
      - dbdata:/var/lib/mysql
    healthcheck:
      test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -p\"$${MYSQL_ROOT_PASSWORD}\" --silent"]
      interval: 5s
      timeout: 5s
      retries: 20
      start_period: 20s

volumes:
  dbdata:

Dockerfile

FROM php:8.2-fpm

WORKDIR /var/www/html

RUN apt-get update && apt-get install -y \
    libzip-dev \
    unzip \
    && docker-php-ext-install zip pdo_mysql \
    && rm -rf /var/lib/apt/lists/*

COPY --chown=www-data:www-data . /var/www/html

RUN chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache

The corrected Nginx file

.docker/nginx/default.conf

server {
    listen 80;
    index index.php index.html;
    root /var/www/html/public;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass web:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
        fastcgi_buffers 16 16k;
        fastcgi_buffer_size 32k;
    }

    location ~ /\.ht {
        deny all;
    }
}

A Blade page to see users appear

app/Http/Controllers/SchedulerDemoController.php

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\View\View;

class SchedulerDemoController extends Controller
{
    public function __invoke(): View
    {
        $users = User::query()
            ->where('is_scheduler_demo', true)
            ->orderByDesc('id')
            ->paginate(15, ['id', 'name', 'email', 'created_at']);

        return view('scheduler-demo', compact('users'));
    }
}

The named GET route /scheduler-demo calls this controller. The resources/views/scheduler-demo.blade.php template escapes displayed values with Blade interpolation, renders the paginated rows and includes a five-second refresh checkbox plus a manual refresh button. It displays neither passwords nor regular user accounts.

Register the users view route: routes/web.php

This is the Lesson 4 route file. The named /scheduler-demo route calls the controller shown above and passes its paginated demo users to the Blade template.

<?php

use App\Http\Controllers\SchedulerDemoController;
use Illuminate\Support\Facades\Route;

Route::get('/', function () {
    return view('welcome');
});

Route::get('/scheduler-demo', SchedulerDemoController::class)->name('scheduler-demo');

resources/views/scheduler-demo.blade.php

Create this Blade file with the complete Lesson 4 implementation below. It includes the demo-user count, ID/name/email/UTC columns, an empty state, pagination, manual refresh, and an optional five-second auto-refresh setting remembered for this browser session. Blade escapes the displayed user values.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Lesson 4 · Laravel Docker Scheduler</title>
    <style>
        :root { color-scheme: light; font-family: ui-sans-serif, system-ui, sans-serif; color: #142c40; background: #f5f7fa; }
        * { box-sizing: border-box; }
        body { margin: 0; }
        main { max-width: 1160px; margin: 64px auto; padding: 0 24px; }
        .eyebrow { color: #db3026; font-size: .8rem; font-weight: 750; letter-spacing: .14em; text-transform: uppercase; }
        h1 { font-size: clamp(2rem, 5vw, 3.1rem); line-height: 1.15; margin: 14px 0; letter-spacing: -.04em; }
        .intro { max-width: 720px; color: #526477; line-height: 1.7; }
        .summary { display: flex; flex-wrap: wrap; align-items: center; gap: 20px; margin: 28px 0; }
        .count { background: #fff; border: 1px solid #dce4ed; border-radius: 14px; padding: 18px 24px; }
        .count strong { font-size: 2rem; margin-right: 8px; }
        .refresh { margin-left: auto; display: flex; align-items: center; flex-wrap: wrap; gap: 16px; font-size: .9rem; }
        button, .pagination a { color: #fff; background: #142c40; border: 0; border-radius: 8px; padding: 11px 16px; font: inherit; cursor: pointer; text-decoration: none; }
        .table-wrap { overflow-x: auto; border: 1px solid #dce4ed; border-radius: 14px; background: #fff; }
        table { border-collapse: collapse; width: 100%; text-align: left; font-size: .92rem; }
        th { background: #edf2f7; padding: 15px 20px; font-size: .75rem; letter-spacing: .06em; text-transform: uppercase; white-space: nowrap; }
        td { padding: 17px 20px; border-top: 1px solid #edf2f7; }
        td:first-child { color: #6a7b8b; }
        .name { font-weight: 700; }
        .email { overflow-wrap: anywhere; min-width: 270px; }
        .time { white-space: nowrap; color: #526477; }
        .empty { padding: 40px 24px; text-align: center; color: #526477; line-height: 1.8; }
        code { background: #edf2f7; padding: 3px 6px; border-radius: 4px; font-size: .85em; }
        .pagination { margin-top: 22px; display: flex; align-items: center; justify-content: space-between; gap: 20px; }
        .pagination span, footer { color: #526477; font-size: .85rem; }
        footer { margin-top: 30px; line-height: 1.7; }
        a:focus-visible, button:focus-visible, input:focus-visible { outline: 3px solid #2188d5; outline-offset: 4px; }
        @media (max-width: 640px) { main { margin-top: 32px; padding: 0 16px; } .refresh { margin-left: 0; } }
    </style>
</head>
<body>
<main>
    <div class="eyebrow">Laravel + Docker · Lesson 4</div>
    <h1>Watch the scheduler at work.</h1>
    <p class="intro">Each scheduled run creates one test user. Start the Docker scheduler service to see a new row approximately every five seconds. This page shows only users marked as part of this demo.</p>

    <section class="summary" aria-label="Demo summary">
        <div class="count"><strong>{{ number_format($users->total()) }}</strong> demo users</div>
        <div class="refresh">
            <label><input type="checkbox" id="auto-refresh" checked> Refresh every 5 seconds</label>
            <button type="button" id="refresh-now">Refresh now</button>
        </div>
    </section>

    <div class="table-wrap">
        <table aria-label="Users created by the Lesson 4 scheduler">
            <thead><tr><th scope="col">ID</th><th scope="col">Name</th><th scope="col">Email</th><th scope="col">Created (UTC)</th></tr></thead>
            <tbody>
            @forelse ($users as $user)
                <tr>
                    <td>{{ $user->id }}</td>
                    <td class="name">{{ $user->name }}</td>
                    <td class="email">{{ $user->email }}</td>
                    <td class="time"><time datetime="{{ $user->created_at->toIso8601String() }}">{{ $user->created_at->utc()->format('Y-m-d H:i:s') }}</time></td>
                </tr>
            @empty
                <tr><td colspan="4" class="empty">No demo users yet.<br>After running migrations, start <code>docker compose --profile scheduler up -d scheduler</code>.<br>The worker starts its first scheduled minute at the next minute boundary.</td></tr>
            @endforelse
            </tbody>
        </table>
    </div>

    <nav class="pagination" aria-label="Demo user pages">
        <div>@if ($users->previousPageUrl())<a href="{{ $users->previousPageUrl() }}">← Newer users</a>@endif</div>
        <span>Page {{ $users->currentPage() }} of {{ $users->lastPage() }}</span>
        <div>@if ($users->nextPageUrl())<a href="{{ $users->nextPageUrl() }}">Older users →</a>@endif</div>
    </nav>
    <footer>Stop the demo when finished: <code>docker compose stop scheduler</code>.<br>These are synthetic addresses at example.com. The command does not send email.</footer>
</main>
<script>
    const refreshPreference = sessionStorage.getItem('scheduler-demo-auto-refresh') !== 'off';
    const autoRefresh = document.getElementById('auto-refresh');
    autoRefresh.checked = refreshPreference;
    autoRefresh.addEventListener('change', () => {
        sessionStorage.setItem('scheduler-demo-auto-refresh', autoRefresh.checked ? 'on' : 'off');
    });
    document.getElementById('refresh-now').addEventListener('click', () => window.location.reload());
    window.setInterval(() => {
        if (autoRefresh.checked && !document.hidden) window.location.reload();
    }, 5000);
</script>
</body>
</html>

Open http://localhost:8080/scheduler-demo, using your configured APP_PORT if different. Start the optional scheduler to create rows and pause auto-refresh when inspecting users or navigating pages. Stop user creation after the demonstration with docker compose stop scheduler.

The verified local demo after six users were created. The scheduler is stopped; refresh can be paused while inspecting the rows.

What was verified

The PHP image built successfully and Docker Compose accepted the configuration.
MySQL migrations completed in an isolated local Docker project.
Nginx passed nginx -t and the Blade endpoint returned HTTP 200.
Eight tests passed with 31 assertions, including command behavior, unique emails, disabled runs, scheduler registration, demo-only visibility and pagination.
Four additional users were observed during the timed verification window. Their successive insert intervals were 4.0, 5.0, 5.0 seconds; the median was five seconds.
The scheduler was stopped and the user count stayed stable. No production user database was used for the example.

References

Originally published at yasiramin.dev.

Lesson 5: Laravel Queue Jobs & Mailtrap with Docker

Muhammad Yasir Amin — Sun, 08 Nov 2026 16:08:54 +0000

Laravel Docker Lessons · Lesson 5

Learn Laravel queue jobs step by step with a practical email example. Queue a message in MySQL, process it in a separate Docker worker, render HTML and plain-text Blade templates, and configure Mailtrap Email Sandbox for safe email testing.

This article documents the actual lesson-5 source snapshot. It builds on Lesson 4: Laravel Scheduler and Cron Jobs with Docker. The recorded Urdu walkthrough is now available: watch Lesson 5 on YouTube.

Builds on lesson-4. This lesson demonstrates a database queue with one email: an Artisan command dispatches a job, a separate Docker worker handles it, and a Mailable renders HTML/text Blade views for the Mailtrap Email Sandbox.

The files and their responsibilities

File	Responsibility
`app/Console/Commands/QueueDemoEmail.php`	Validate the recipient/name and queue one job. Print a reference, without claiming delivery.
`app/Jobs/SendDemoEmail.php`	Implement `ShouldQueue`, select the database connection and `emails` queue, and send the Mailable when handled.
`app/Mail/QueueDemoMail.php`	Define the email subject and Blade views. It is not another queued job.
`resources/views/emails/queue-demo.blade.php`	Render the HTML email using escaped Blade values and inline email styles.
`resources/views/emails/queue-demo-text.blade.php`	Render the plain-text alternative.
`config/mail.php`	Configure the named `mailtrap` SMTP mailer.
`routes/web.php`	Register the read-only Blade email preview route. Queue dispatch stays in the Artisan command.
`docker-compose.yaml`	Run the optional `worker` service separately from Nginx, PHP-FPM and the scheduler.
`Dockerfile`	Include `pcntl` for the Linux queue worker's process signals and timeouts.

The existing Laravel migration already creates jobs, job_batches and failed_jobs. No duplicate queue-table migration is necessary.

Understand the flow before running it

demo:queue-email
      |
      v
MySQL jobs table (queue = emails)
      |
      v
Docker worker: queue:work database --queue=emails
      |
      v
SendDemoEmail::handle()
      |
      v
QueueDemoMail + Blade views
      |
      v
Mailtrap Email Sandbox SMTP

The producer does not wait for SMTP. It stores the job and returns. Without a worker, the email remains queued. The job explicitly uses the database connection, so a private .env setting of QUEUE_CONNECTION=sync cannot accidentally turn this particular example into an inline send.

afterCommit() defers dispatch until an enclosing database transaction commits. If there is no enclosing transaction, dispatch proceeds immediately. The worker calls send() on the Mailable because the enclosing job is already queued; queueing the Mailable again would add a second queue hop.

1. Prepare the Laravel Docker stack

Use PHP 8.2+ on the host for Composer and the Laravel setup. For a fresh checkout, follow Lesson 4's setup to prepare .env, dependencies and the application key. Do not overwrite an existing .env or regenerate an existing key.

composer install
docker compose --profile queue config --quiet
docker compose up -d --build db web nginx
docker compose exec web php artisan config:clear
docker compose exec web php artisan migrate --force
docker compose restart nginx

The PHP image now installs zip, pdo_mysql and pcntl. The existing MySQL connection, named dbdata volume and configurable host ports are retained. The Compose environment explicitly selects the database queue and a 90-second database retry interval. No Redis service is introduced.

Composer files are copied into the built image and then used to populate each PHP service's anonymous vendor volume, as in Lesson 4. If dependencies change, rebuild and recreate the stack as described in that lesson so the volume does not retain an old dependency tree.

2. Add your Mailtrap Email Sandbox credentials

In Mailtrap, open Email Sandbox, choose your sandbox/inbox, then view its Integration SMTP settings. Use the sandbox SMTP username and password. These are not the Email Sending credentials, an account login password, or an API token.

Put these values only in your private .env:

MAIL_MAILER=log
MAIL_SCHEME=null
MAIL_HOST=sandbox.smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=your_sandbox_smtp_username
MAIL_PASSWORD=your_sandbox_smtp_password
MAIL_FROM_ADDRESS=hello@example.com
MAIL_FROM_NAME="Laravel Docker Lessons"

Existing environment keys: use the existing MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD and MAIL_SCHEME keys. Set MAIL_HOST=sandbox.smtp.mailtrap.io instead of the generic localhost default. Copy only your own Sandbox SMTP username/password into your private environment file. The corrected named mailtrap mailer reads these same keys; its complete configuration is shown below. MAIL_MAILER=log can stay as the default because the job explicitly selects Mail::mailer('mailtrap'). No private credential values are published here.

The committed .env.example leaves credentials empty. The mailtrap mailer uses sandbox.smtp.mailtrap.io, a ten-second SMTP timeout and required TLS. Port 2525 is the documented default; use the port shown in your Mailtrap integration settings if needed. Do not disable certificate checks.

The default MAIL_MAILER=log is left unchanged. This example explicitly selects Mail::mailer('mailtrap'), so changing the default mailer is not necessary. The command refuses to enqueue if sandbox credentials are missing. The job checks again before processing, rather than reporting a log-file write as successful Mailtrap delivery.

After editing .env:

docker compose exec web php artisan config:clear

If the worker was already running, restart it after the environment/code change:

docker compose restart worker

The web and worker containers have separate anonymous cache/storage volumes. Restarting the worker is the explicit reload step in this example; clearing only the web container's config does not reload a running worker process. A fresh worker container starts with the current image's uncached configuration. If you previously cached config inside the worker, clear that worker cache as well before restarting it.

3. Preview the Blade email

The HTTP preview is registered in routes/web.php. Add the QueueDemoMail import and the route below to your existing file; import Route only once. The full route file is included in the implementation section. This route only renders the email. Queue dispatch uses demo:queue-email from the terminal; there is no HTTP send endpoint in this lesson.

use App\Mail\QueueDemoMail;
use Illuminate\Support\Facades\Route;

Route::get('/queue-demo/mail-preview', fn () => new QueueDemoMail('Laravel Developer', 'preview-only'))
    ->name('queue-demo.mail-preview');

Open http://localhost:8080/queue-demo/mail-preview, using your configured APP_PORT if different. This route renders the real Mailable with a fixed greeting and a preview-only reference. It neither queues a job nor connects to SMTP.

The message explains the three queue steps, displays the recipient's name, and includes a reference for matching the queued command to the captured sandbox message. Recipient names and references are escaped in both Blade templates. Previewing the HTML is not evidence of Mailtrap delivery.

4. Queue one email while the worker is stopped

docker compose stop worker
docker compose exec web php artisan demo:queue-email student@example.com --name="Laravel Student"

The command prints a reference and states that queued does not mean delivered. student@example.com is a synthetic test recipient: the sandbox captures the SMTP message for inspection rather than sending it to a real student inbox.

For a recording, inspect the pending row in MySQL:

docker compose exec db mysql -uroot -proot laravel_app -e "SELECT id, queue, attempts, reserved_at FROM jobs WHERE queue = 'emails';"

These root credentials belong to the existing local tutorial stack; they are not production credentials. The payload contains the recipient, greeting and reference required to process the job. It does not contain the Mailtrap SMTP password.

5. Start the Docker queue worker

docker compose --profile queue up -d --build worker
docker compose logs -f worker

The service inherits the application image, source/vendor mounts, database environment and MySQL health dependency. Its command is:

php artisan queue:work database --queue=emails --sleep=1 --tries=3 --timeout=30 --max-time=3600 --no-interaction

--queue=emails matches the job's queue; a worker listening only to default would not consume it. The worker runs in the foreground as www-data, uses an init process, has a 45-second graceful-stop allowance and restarts unless explicitly stopped. A periodic one-hour exit lets Docker restart the long-running process.

After a successful send, Laravel removes the job from the pending table. Open the selected Mailtrap sandbox and inspect the subject, HTML and text parts and command reference. A worker's successful SMTP submission means Mailtrap accepted the message; it is not proof of delivery to an external person's inbox.

The worker is behind the queue profile. Normal docker compose up -d does not start it. It is independent of Lesson 4's optional scheduler service; no scheduled email loop is added.

6. Retries, failures and worker restarts

The job allows three attempts, with ten seconds before the second attempt and thirty seconds before the third. Its timeout is 30 seconds, below the database reservation retry interval of 90 seconds, so an active worker is not normally overtaken by an expired reservation. The SMTP connection timeout is ten seconds. The Linux image includes pcntl so worker process signals/timeouts are supported.

docker compose exec web php artisan queue:failed

If a test job ultimately fails, fix its SMTP configuration, restart the worker, then retry that specific failed job with php artisan queue:retry and the failed job's UUID inside the web container. Do not retry every job blindly. SMTP queues provide at-least-once processing: if SMTP accepts a message and the process fails before acknowledging the job, a retry can produce another copy. This demo does not claim exactly-once email delivery.

When changing application code, restart the worker so it loads the new code. The source bind mount alone does not replace classes already loaded by a long-running process.

Stop after the demonstration

docker compose stop worker
docker compose --profile queue --profile scheduler ps -a

Stop the optional scheduler too if you started it during Lesson 4. To stop the entire stack while retaining MySQL data:

docker compose --profile queue --profile scheduler down

Do not append -v when you want to keep the database. Pending jobs remain in MySQL while the worker is stopped and can be processed on the next deliberate worker start.

Verification and limits

php vendor/bin/pest
php vendor/bin/pint --test
docker compose --profile queue --profile scheduler config --quiet

The feature tests cover dispatch, the explicit database/emails destination, missing credentials, invalid input, Mailable rendering/escaping, the worker handler's named mailer, preview behavior and timeout/retry settings. Tests use faked mail delivery and do not contact Mailtrap.

Actual Mailtrap inbox delivery requires the owner's private sandbox credentials. Until that verification is performed, the setup is a configured integration, not a claim of a captured live Mailtrap message. Local database/worker verification can use an explicitly substituted in-memory test transport; that substitution is a test fixture, not the committed Mailtrap configuration.

Lesson 5 correction: the original lesson-5 tag used separate Mailtrap-prefixed environment variables. The route and mail examples below include the follow-up correction in commit 199f6d7, which reuses the project's existing MAIL_* keys. The original tag is retained as its historical snapshot.

The actual Lesson 5 implementation

routes/web.php

<?php

use App\Http\Controllers\SchedulerDemoController;
use App\Mail\QueueDemoMail;
use Illuminate\Support\Facades\Route;

Route::get('/', function () {
    return view('welcome');
});

Route::get('/scheduler-demo', SchedulerDemoController::class)->name('scheduler-demo');

Route::get('/queue-demo/mail-preview', fn () => new QueueDemoMail('Laravel Developer', 'preview-only'))
    ->name('queue-demo.mail-preview');

config/mail.php

<?php

return [

    /*
    |--------------------------------------------------------------------------
    | Default Mailer
    |--------------------------------------------------------------------------
    |
    | This option controls the default mailer that is used to send all email
    | messages unless another mailer is explicitly specified when sending
    | the message. All additional mailers can be configured within the
    | "mailers" array. Examples of each type of mailer are provided.
    |
    */

    'default' => env('MAIL_MAILER', 'log'),

    /*
    |--------------------------------------------------------------------------
    | Mailer Configurations
    |--------------------------------------------------------------------------
    |
    | Here you may configure all of the mailers used by your application plus
    | their respective settings. Several examples have been configured for
    | you and you are free to add your own as your application requires.
    |
    | Laravel supports a variety of mail "transport" drivers that can be used
    | when delivering an email. You may specify which one you're using for
    | your mailers below. You may also add additional mailers if needed.
    |
    | Supported: "smtp", "sendmail", "mailgun", "ses", "ses-v2",
    |            "postmark", "resend", "log", "array",
    |            "failover", "roundrobin"
    |
    */

    'mailers' => [

        'mailtrap' => [
            'transport' => 'smtp',
            'scheme' => env('MAIL_SCHEME'),
            'host' => env('MAIL_HOST', 'sandbox.smtp.mailtrap.io'),
            'port' => (int) env('MAIL_PORT', 2525),
            'username' => env('MAIL_USERNAME'),
            'password' => env('MAIL_PASSWORD'),
            'timeout' => 10,
            'require_tls' => true,
        ],

        'smtp' => [
            'transport' => 'smtp',
            'scheme' => env('MAIL_SCHEME'),
            'url' => env('MAIL_URL'),
            'host' => env('MAIL_HOST', '127.0.0.1'),
            'port' => env('MAIL_PORT', 2525),
            'username' => env('MAIL_USERNAME'),
            'password' => env('MAIL_PASSWORD'),
            'timeout' => null,
            'local_domain' => env('MAIL_EHLO_DOMAIN', parse_url((string) env('APP_URL', 'http://localhost'), PHP_URL_HOST)),
        ],

        'ses' => [
            'transport' => 'ses',
        ],

        'postmark' => [
            'transport' => 'postmark',
            // 'message_stream_id' => env('POSTMARK_MESSAGE_STREAM_ID'),
            // 'client' => [
            //     'timeout' => 5,
            // ],
        ],

        'resend' => [
            'transport' => 'resend',
        ],

        'sendmail' => [
            'transport' => 'sendmail',
            'path' => env('MAIL_SENDMAIL_PATH', '/usr/sbin/sendmail -bs -i'),
        ],

        'log' => [
            'transport' => 'log',
            'channel' => env('MAIL_LOG_CHANNEL'),
        ],

        'array' => [
            'transport' => 'array',
        ],

        'failover' => [
            'transport' => 'failover',
            'mailers' => [
                'smtp',
                'log',
            ],
            'retry_after' => 60,
        ],

        'roundrobin' => [
            'transport' => 'roundrobin',
            'mailers' => [
                'ses',
                'postmark',
            ],
            'retry_after' => 60,
        ],

    ],

    /*
    |--------------------------------------------------------------------------
    | Global "From" Address
    |--------------------------------------------------------------------------
    |
    | You may wish for all emails sent by your application to be sent from
    | the same address. Here you may specify a name and address that is
    | used globally for all emails that are sent by your application.
    |
    */

    'from' => [
        'address' => env('MAIL_FROM_ADDRESS', 'hello@example.com'),
        'name' => env('MAIL_FROM_NAME', env('APP_NAME', 'Laravel')),
    ],

];

The following files include the Lesson 5 mail-key correction linked above. The command produces the job; the job owns delivery; the Mailable owns the email content.

app/Console/Commands/QueueDemoEmail.php

<?php

namespace App\Console\Commands;

use App\Jobs\SendDemoEmail;
use Illuminate\Console\Command;
use Illuminate\Support\Facades\Validator;
use Illuminate\Support\Str;

class QueueDemoEmail extends Command
{
    protected $signature = 'demo:queue-email {email=student@example.com : Test recipient captured by Mailtrap Sandbox} {--name=Laravel Developer : Name shown in the email}';

    protected $description = 'Queue one Lesson 5 email for the Mailtrap Sandbox';

    public function handle(): int
    {
        $input = ['email' => $this->argument('email'), 'name' => $this->option('name')];
        $validator = Validator::make($input, ['email' => 'required|email|max:254', 'name' => 'required|string|max:100']);

        if ($validator->fails()) {
            foreach ($validator->errors()->all() as $error) {
                $this->error($error);
            }

            return self::FAILURE;
        }

        if (blank(config('mail.mailers.mailtrap.username')) || blank(config('mail.mailers.mailtrap.password'))) {
            $this->error('Set MAIL_USERNAME and MAIL_PASSWORD to your Mailtrap Sandbox SMTP credentials in your private .env, then clear container config.');

            return self::FAILURE;
        }

        $reference = (string) Str::ulid();
        SendDemoEmail::dispatch($input['email'], $input['name'], $reference);

        $this->info("Queued email {$reference} on database / emails for {$input['email']}.");
        $this->comment('Queued does not mean delivered. Start the Docker worker and check your Mailtrap Sandbox inbox.');

        return self::SUCCESS;
    }
}

app/Jobs/SendDemoEmail.php

<?php

namespace App\Jobs;

use App\Mail\QueueDemoMail;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Support\Facades\Mail;
use RuntimeException;

class SendDemoEmail implements ShouldQueue
{
    use Queueable;

    public int $tries = 3;

    public int $timeout = 30;

    public function __construct(
        public string $recipient,
        public string $recipientName,
        public string $reference,
    ) {
        $this->onConnection('database')->onQueue('emails')->afterCommit();
    }

    public function backoff(): array
    {
        return [10, 30];
    }

    public function handle(): void
    {
        if (blank(config('mail.mailers.mailtrap.username')) || blank(config('mail.mailers.mailtrap.password'))) {
            throw new RuntimeException('Configure MAIL_USERNAME and MAIL_PASSWORD with Mailtrap Sandbox SMTP credentials before processing demo emails.');
        }

        // The job is already queued; send the mailable here instead of queuing it a second time.
        Mail::mailer('mailtrap')->to($this->recipient)
            ->send(new QueueDemoMail($this->recipientName, $this->reference));
    }
}

app/Mail/QueueDemoMail.php

<?php

namespace App\Mail;

use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;
use Illuminate\Queue\SerializesModels;

class QueueDemoMail extends Mailable
{
    use Queueable, SerializesModels;

    public function __construct(public string $recipientName, public string $reference) {}

    public function envelope(): Envelope
    {
        return new Envelope(subject: 'Lesson 5: Your queued Laravel email is ready');
    }

    public function content(): Content
    {
        return new Content(view: 'emails.queue-demo', text: 'emails.queue-demo-text');
    }
}

resources/views/emails/queue-demo.blade.php

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Lesson 5 · Queued Laravel Email</title>
</head>
<body style="margin:0;padding:0;background:#f3f6fa;color:#142c40;font-family:Arial,Helvetica,sans-serif;">
<table role="presentation" style="width:100%;border-collapse:collapse;background:#f3f6fa;">
    <tr><td style="padding:40px 16px;">
        <table role="presentation" style="width:100%;max-width:600px;margin:0 auto;border-collapse:collapse;background:#ffffff;border:1px solid #dce4ed;">
            <tr><td style="padding:32px 32px 20px;border-top:5px solid #ed352b;">
                <p style="margin:0 0 16px;color:#d72d24;font-size:12px;font-weight:bold;letter-spacing:2px;">LARAVEL + DOCKER · LESSON 5</p>
                <h1 style="margin:0;font-size:30px;line-height:1.2;">Your queue did the work.</h1>
            </td></tr>
            <tr><td style="padding:0 32px 28px;font-size:16px;line-height:1.7;">
                <p>Hello {{ $recipientName }},</p>
                <p>This message was created by a Laravel Mailable, rendered from a Blade template, and sent by a queued job running in a separate Docker worker.</p>
                <table role="presentation" style="width:100%;border-collapse:collapse;background:#edf3f8;">
                    <tr><td style="padding:18px;font-size:14px;line-height:1.8;">
                        <strong>1.</strong> Artisan dispatched the job.<br>
                        <strong>2.</strong> The database queue stored it.<br>
                        <strong>3.</strong> The worker rendered and sent this email.
                    </td></tr>
                </table>
                <p style="margin-bottom:0;">Reference:<br><span style="font-family:monospace;font-size:13px;word-break:break-all;">{{ $reference }}</span></p>
            </td></tr>
            <tr><td style="padding:20px 32px;background:#142c40;color:#e5edf5;font-size:12px;line-height:1.7;">
                Laravel Docker Lessons · Queue Jobs Step by Step<br>
                This is a test message for the Mailtrap Email Sandbox.
            </td></tr>
        </table>
    </td></tr>
</table>
</body>
</html>

resources/views/emails/queue-demo-text.blade.php

Laravel + Docker — Lesson 5

Your queue did the work.

Hello {{ $recipientName }},

This message was created by a Laravel Mailable, rendered from a Blade template, and sent by a queued job running in a separate Docker worker.

1. Artisan dispatched the job.
2. The database queue stored it.
3. The worker rendered and sent this email.

Reference: {{ $reference }}

This is a test message for the Mailtrap Email Sandbox.

docker-compose.yaml

x-laravel-environment: &laravel-environment
  DB_URL: ""
  DB_SOCKET: ""
  DB_CONNECTION: mysql
  DB_HOST: db
  DB_PORT: 3306
  DB_DATABASE: laravel_app
  DB_USERNAME: root
  DB_PASSWORD: root
  QUEUE_CONNECTION: database
  DB_QUEUE_RETRY_AFTER: 90

x-laravel-service: &laravel-service
  build:
    context: .
    dockerfile: Dockerfile
  image: my-laravel-app
  working_dir: /var/www/html
  user: "www-data"
  volumes:
    - .:/var/www/html
    - /var/www/html/vendor
    - /var/www/html/storage
    - /var/www/html/bootstrap/cache
  environment:
    <<: *laravel-environment
    SCHEDULER_DEMO_ENABLED: "false"
  depends_on:
    db:
      condition: service_healthy

services:
  web:
    <<: *laravel-service

  scheduler:
    <<: *laravel-service
    profiles: ["scheduler"]
    init: true
    command: ["php", "artisan", "schedule:work", "--no-interaction"]
    restart: unless-stopped
    environment:
      <<: *laravel-environment
      CACHE_STORE: file
      SCHEDULER_DEMO_ENABLED: "true"

  worker:
    <<: *laravel-service
    profiles: ["queue"]
    init: true
    command: ["php", "artisan", "queue:work", "database", "--queue=emails", "--sleep=1", "--tries=3", "--timeout=30", "--max-time=3600", "--no-interaction"]
    restart: unless-stopped
    stop_grace_period: 45s

  nginx:
    image: nginx:latest
    ports:
      - "${APP_PORT:-8080}:80"
    volumes:
      - .:/var/www/html:ro
      - ./.docker/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - web

  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: laravel_app
    ports:
      - "${DB_FORWARD_PORT:-3308}:3306"
    volumes:
      - dbdata:/var/lib/mysql
    healthcheck:
      test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -p\"$${MYSQL_ROOT_PASSWORD}\" --silent"]
      interval: 5s
      timeout: 5s
      retries: 20
      start_period: 20s

volumes:
  dbdata:

Dockerfile

FROM php:8.2-fpm

WORKDIR /var/www/html

RUN apt-get update && apt-get install -y \
    libzip-dev \
    unzip \
    && docker-php-ext-install zip pdo_mysql pcntl \
    && rm -rf /var/lib/apt/lists/*

COPY --chown=www-data:www-data . /var/www/html

RUN chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache

Verified email preview and queue behavior

The image below shows the real Blade preview. It is a preview, not a Mailtrap inbox screenshot and not evidence of external SMTP delivery.

The email preview renders without dispatching a job or contacting SMTP.

Seventeen automated tests passed with 58 assertions. An isolated Docker check used the real MySQL jobs table and Laravel worker with an explicitly substituted in-memory mail transport: one job waited with zero inline messages, then the worker consumed it and rendered one email. There were no new failed jobs. The PHP image built successfully with PCNTL; Compose validation and formatting checks passed. The worker and scheduler were stopped after verification.

Actual Mailtrap capture remains a separate verification step using your private Sandbox SMTP credentials. No Mailtrap password is committed, embedded in a job payload, or included in this article.

References

Originally published at yasiramin.dev.