Laravel

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 for PHP 8.3 and later. 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 is a cache by default: it evicts any key once its memory limit is reached, and its data volume is optional. Queued jobs can be dropped silently under memory pressure, and a restart empties it when there is no volume. For a reliable queue, set VALKEY_MAXMEMORY_POLICY to noeviction and size VALKEY_MAXMEMORY on the Valkey app service.

Mailpit captures every message and delivers none of them. Its web interface is protected with basic auth. Reveal the password in Endpoints > Auths. 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.

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 Files NFS storage service has its own Files backup and Files import. See Application Backups and Application Imports.