Laravel

Automations

serversideup/php has a "Laravel Automations" script that helps automate common tasks to maintain your Laravel application and improve it's performance. By default, the script is DISABLED. We only recommend enabling this script in production environments.

What the script does

In order for this script to run,AUTORUN_ENABLED must be set to true. Once the main part of the script is enabled, you can control the individual tasks by setting the corresponding environment variables to true or false. See our variable reference document for more details.

Environment Variable	Default	Description
`AUTORUN_ENABLED`	`false`	Enables the Laravel Automations script. ℹ️ Note: This must be set to `true` for the script to run.
`AUTORUN_DEBUG`	`false`	Enables a special debug mode, specifically for the Laravel Automations script.
`AUTORUN_LARAVEL_CONFIG_CACHE`	`true`	`php artisan config:cache`: Caches the configuration files into a single file.
`AUTORUN_LARAVEL_EVENT_CACHE`	`true`	`php artisan event:cache`: Creates a manifest of all your application's events and listeners.
`AUTORUN_LARAVEL_MIGRATION`	`true`	`php artisan migrate`: Runs migrations.
`AUTORUN_LARAVEL_MIGRATION_DATABASE`	`null`	Run migrations on a specific database. In the rare case you need to use multiple databases, you can provide a comma-delimited list of connection names (e.g., "mysql,pgsql"). If `null`, it will use the default database connection.
`AUTORUN_LARAVEL_MIGRATION_FORCE`	`true`	Force migrations to run in production without confirmation. Set to `false` to disable the `--force` flag.
`AUTORUN_LARAVEL_MIGRATION_ISOLATION`	`false`	Run your migrations with the `--isolated` flag. ℹ️ Note: Requires Laravel v9.38.0+. Only works with `default` migration mode.
`AUTORUN_LARAVEL_MIGRATION_MODE`	`default`	Migration mode: `default`, `fresh`, or `refresh`. ⚠️ Warning: `fresh` and `refresh` drop all tables.
`AUTORUN_LARAVEL_MIGRATION_SEED`	`false`	Automatically seed the database after migrations using the `--seed` flag.
`AUTORUN_LARAVEL_MIGRATION_SKIP_DB_CHECK`	`false`	Skip the database connection check before running migrations.
`AUTORUN_LARAVEL_MIGRATION_TIMEOUT`	`30`	Number of seconds to wait for database connection before timing out during migrations.
`AUTORUN_LARAVEL_OPTIMIZE`	`true`	`php artisan optimize`: Optimizes the application.
`AUTORUN_LARAVEL_ROUTE_CACHE`	`true`	`php artisan route:cache`: Caches the routes.
`AUTORUN_LARAVEL_STORAGE_LINK`	`true`	`php artisan storage:link`: Creates a symbolic link from `public/storage` to `storage/app/public`.
`AUTORUN_LARAVEL_VIEW_CACHE`	`true`	`php artisan view:cache`: Caches the views.

Database Connection Checks

Before running migrations, the automation script performs connection checks to ensure your database is ready. Understanding this process helps you configure timeouts and troubleshoot connection issues.

You can skip database connection checks entirely by setting AUTORUN_LARAVEL_MIGRATION_SKIP_DB_CHECK=true. This is useful when you're certain your database is ready or when using alternative connection verification methods.

Clear configuration cache

The script runs php artisan config:clear to ensure fresh database configuration is loaded before attempting any connections.

Attempt database connection

The script tests the database connection using a retry mechanism:

Attempts to connect every second
Continues for up to AUTORUN_LARAVEL_MIGRATION_TIMEOUT seconds (default: 30)
Shows connection progress in real-time
Logs detailed attempts every 5 seconds when AUTORUN_DEBUG=true

Verify each database connection

If you've specified multiple databases via AUTORUN_LARAVEL_MIGRATION_DATABASE, the script waits for each database connection individually before proceeding with migrations for that database.

Run migrations

Once the database connection is confirmed, the script executes the appropriate migration command based on your configuration.

Set AUTORUN_DEBUG=true to see detailed connection attempt logs, which is helpful for troubleshooting connection issues.

Laravel Artisan Commands

Below is an overview of what Laravel Artisan commands do and how they can be configured.

php artisan storage:link

Creates a symbolic link from public/storage to storage/app/public.

php artisan migrate

Before running migrations, we ensure the database is online and ready to accept connections. By default, we will wait 30 seconds before timing out.

Migration Modes

You can control how migrations run using AUTORUN_LARAVEL_MIGRATION_MODE:

Mode	Description
`default`	Runs `php artisan migrate` - standard forward migrations
`fresh`	Runs `php artisan migrate:fresh` - drops all tables and re-runs migrations
`refresh`	Runs `php artisan migrate:refresh` - rolls back and re-runs migrations

Using fresh or refresh modes will drop all tables in your database. Only use these in development or testing environments.

Force Flag

By default, migrations run with the --force flag to bypass production warnings. You can disable this by setting AUTORUN_LARAVEL_MIGRATION_FORCE to false.

Seeding

You can automatically seed your database after migrations by setting AUTORUN_LARAVEL_MIGRATION_SEED to true. This adds the --seed flag to your migration command.

Specific Database Migrations

If you need to specify the exact database connection to use for migrations, you can set AUTORUN_LARAVEL_MIGRATION_DATABASE to the name of the database connection you want to use.

Use case	Description	Value
Single database	Run migrations on the `mysql` database connection.	`AUTORUN_LARAVEL_MIGRATION_DATABASE=mysql`
Multiple databases	In the rare case you need to use multiple databases, you can provide a comma-delimited list of connection names (e.g., "mysql,pgsql").	`AUTORUN_LARAVEL_MIGRATION_DATABASE=mysql,pgsql`

Isolated Migrations

You can enable the --isolated flag by setting AUTORUN_LARAVEL_MIGRATION_ISOLATION to true, which will ensure no other containers are running a migration.

Special Notes for Isolated Migrations:

Requires Laravel v9.38.0+
Only works with default migration mode (not compatible with fresh or refresh)
Your application must be using the memcached, redis, dynamodb, database, file, or array cache driver as your application's default cache driver. In addition, all servers must be communicating with the same central cache server.

php artisan optimize

Laravel comes with an artisan command called optimize, which will optimize the application by caching the configuration, routes, views, and events all in one command.

You can disable any cache features by setting the corresponding environment variable to false (for example, AUTORUN_LARAVEL_CONFIG_CACHE would disable configuration caching).

If your application is running Laravel v11.38.0 or higher, we will utilize the optimize --except parameter to exclude any cache features you have disabled. Otherwise, we will run the individual optimizations separately.

It's possible to disable the optimize command by setting AUTORUN_LARAVEL_OPTIMIZE to false, but the major advantage of using the optimize command is other dependencies may hook into this action and run other commands.

php artisan config:cache

This command caches all configuration files into a single file, which can then be quickly loaded by Laravel. Once the configuration is cache, the .env file will no longer be loaded.

php artisan route:cache

This command caches the routes, dramatically decrease the time it takes to register all of your application's routes. After running this command, your cached routes file will be loaded on every request.

php artisan view:cache

This command caches all of the views in your application, which can greatly decrease the time it takes to render your views.

php artisan event:cache

This command creates a manifest of all your application's events and listeners, which can greatly speed up the process of registering them with Laravel.

Debugging the AUTORUN script

It's very important to understand the nature of how containerized environments work when debugging the AUTORUN script. In some cases, some users may become frustrated when they push an update but their changes are never deployed.

In most cases, this is due to a bug in their application code that causes a migration or some other process to fail.

If a failure occurs in the Laravel Automations script, it will exit with a non-zero exit code -- preventing the container from starting.

If you are experiencing issues, you can enable the AUTORUN_DEBUG environment variable to get more detailed output of what could be going wrong.

If you need even more information, you can set LOG_OUTPUT_LEVEL to debug to get A TON of output of what's exactly happening.

Preventing issues with the AUTORUN script

Ensure you are running the latest version of serversideup/php
Ensure you have dependencies installed (ie. composer install) before calling this script
Use automated testing to catch issues before deploying

Unit (Deprecated)

NGINX Unit has been archived. This guide helps you understand what happened and how to migrate to actively maintained alternatives.

Task Scheduler

Learn how to configure a Laravel Task Scheduler with Docker.