Skip to content

Laravel stack guide

The Wodby Laravel catalog stack runs Laravel on PHP-FPM behind Nginx, with MariaDB, Valkey, shared file storage and Mailpit. A queue worker, OpenSMTPD, Gotenberg and managed databases are optional. The current services and defaults are documented in wodby/stack-laravel.

Build and deployment

Start from Laravel on Wodby, which includes .wodby/pipeline.yml, or connect your own repository. The boilerplate is offered only for the PHP versions it supports. See Application Builds.

Only the document root (Nginx docroot, public by default) goes into the Nginx image. Put front-end build output there during the build. Code, vendor and .env stay in the PHP image.

Wodby does not provide a development workspace for the Laravel PHP service.

Configuration and .env

When the container starts and /var/www/html/.env does not exist, the image writes one from the service's environment variables. Keep .env out of your repository. A committed .env is left as it is, and Wodby generates nothing.

To change a value, set the variable on the PHP service and deploy. Do not edit the generated file. It takes the app name, environment name and URL from Wodby. It takes APP_KEY, APP_DEBUG, DB_*, LOG_*, CACHE_DRIVER, SESSION_DRIVER, QUEUE_CONNECTION, MAIL_*, REDIS_*, AWS_* and PUSHER_* from variables of the same name. A name that is not in this list is not written to it.

APP_KEY is generated by Wodby. Find it in the PHP app service's Configuration > Tokens tab. APP_DEBUG is on in development environments and off elsewhere. See Environment variables.

Database, Valkey and mail

Link What the PHP service receives
DBMS DB_* variables, including DB_CONNECTION and DB_DATABASE
Redis (Valkey) REDIS_HOST, REDIS_PORT, REDIS_PASSWORD, and QUEUE_CONNECTION=redis
Mail Transfer Agent MSMTP_HOST and MSMTP_PORT, used as MAIL_HOST and MAIL_PORT unless you set those

Cache and sessions stay on files until you set CACHE_DRIVER and SESSION_DRIVER on the PHP service.

Valkey stores queued jobs, so the stack sets its policy to noeviction. Jobs are not evicted under memory pressure. When Valkey reaches its memory limit, new writes fail instead, so size VALKEY_MAXMEMORY (128m by default) for your queue on the Valkey app service.

A Valkey restart loses queued jobs

Valkey has no volume in this stack, so a restart or deployment of Valkey empties it.

To keep queued jobs across a restart, store them in MariaDB. Set QUEUE_CONNECTION to database on the PHP service and deploy. This also applies to the optional Laravel Queue service. Jobs need the jobs table, which the boilerplate includes through Laravel's default migrations. If your application does not have it, run php artisan make:queue-table and commit the migration. See Laravel's queue documentation.

Do not select Add volume on an existing Valkey app service. Kubernetes does not allow the change, so the deployment fails.

Do not use this Valkey instance for Laravel's cache. Cache pressure would block queue writes. Add a separate cache service with an LRU policy.

Mailpit captures every message and delivers none of them. Its web interface is protected with basic auth. Reveal the password in Endpoints > Basic Auth. For real delivery, enable OpenSMTPD, point the PHP service's Mail Transfer Agent link at it, and attach an SMTP provider. See the OpenSMTPD guide.

To use a Cloud MariaDB or Cloud MySQL service, see Managed Databases. Laravel connects over TLS and verifies the server certificate when the server has one.

After each deployment

  • php artisan migrate --force runs after every deployment.
  • php artisan db:seed runs once, after the first deployment's migrations.
  • A cron job runs php artisan schedule:run at minute 0 of every hour. A service schedule cannot run more often, so tasks scheduled for other minutes do not run from it. Schedule tasks on the hour, or run php artisan schedule:work as a long-running process. See Application Cron Schedules.
  • The optional Laravel Queue service runs php artisan queue:listen.

Do not add migration or queue worker commands to the build or to a start script.

Traces, metrics, and logs

The stack includes an OpenTelemetry Collector, disabled by default. When you enable it and set where it forwards data, the PHP service and the Laravel Queue service get the standard OpenTelemetry SDK variables that point to it. Add the OpenTelemetry PHP SDK with Composer; it then starts without code changes. To trace requests, queue jobs, and database queries, also add open-telemetry/opentelemetry-auto-laravel. See PHP applications and OpenTelemetry Collector in application stacks.

Files and storage

The PHP service requires a storage link and mounts a shared files volume at /mnt/files. The stack provides it as Files NFS storage. The PHP service's storage volume is 20 GB, and the NFS service's own data volume is 25 GB. See Application Persistent Storage.

On start, storage/app/public and public/storage become links to /mnt/files/public. Nginx serves those files under /storage/. This replaces php artisan storage:link, so do not run it in the build. The step fails when either directory holds anything other than a .gitignore.

Only storage/app/public is on the volume. Logs and file-based sessions and cache are in the container's file system and are lost when it restarts.

Backups

A MariaDB backup is a gzipped SQL dump of the environment's database. The stack excludes the contents of the cache and cache_locks tables by default. They keep their definition and lose their rows. You can change this with the backup's Excluded table contents option. A database import replaces the whole data volume. The Valkey service has no backups or imports.

The Files NFS storage service has its own Files backup and Files import. See Application Backups and Application Imports.