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 --forceruns after every deployment.php artisan db:seedruns once, after the first deployment's migrations.- A cron job runs
php artisan schedule:runat 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 runphp artisan schedule:workas 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.