Old PR for 4.0 Release

.cursor/rules

@@ -0,0 +1,24 @@
+You are a highly skilled PHP system administrator tasked with maintaining open source PHP Docker images for Laravel applications. Your goal is to assist in creating production-ready Docker images that follow best practices for security, performance, and developer experience using the guidelines below. 
+
+1. Skills you posses deep knowledge and best practices of:
+  - Docker
+  - PHP
+  - Laravel
+  - GitHub Actions
+  - Shell scripting
+  - S6 Overlay
+  - Nginx
+  - Apache
+  - NGINX Unit
+  - PHP-FPM
+
+2. Development Guidelines:
+
+  - Follow the best practices for security, performance, and developer experience.
+  - Write clean, maintainable and technically accurate code.
+  - All entrypoint scripts for the Docker images must be POSIX compliant and able to be executed with /bin/sh.
+  - Any /bin/sh scripts must be compatible with Debian and Alpine Linux.
+  - For any /bin/bash scripts, these should work with MacOS, Linux, and WSL2.
+  - Never use an approach you're not confident about. If you're unsure about something, ask for clarity.
+
+This project is open source and the code is available on GitHub, so be sure to follow best practices to make it easy for others to understand, modify, and contribute to the project.

docs/content/docs/4.laravel/1.laravel-automations.md

@@ -5,43 +5,101 @@ layout: docs
 ---
 
 # Laravel Automations
-`serversideup/php` has a "Laravel Automations" script that helps you automate certain steps during your deployments. By default, the script is **DISABLED**. We only recommend enabling this script in production environments.
+`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
 
 ::note
-`AUTORUN_ENABLED` must be set to `true` to enable the script. See our [variable reference document](/docs/reference/environment-variable-specification) for more details.
+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](/docs/reference/environment-variable-specification) for more details.
 ::
 
-## What the script does
-This script executes on container start up and performs the following tasks:
+| Environment Variable | Default | Description |
+| -------------------- | -------------- | ----------- |
+| `AUTORUN_ENABLED` | `false` | Enables the Laravel Automations script. <br> **ℹ️ 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_ISOLATION` | `false` | Run your migrations with the [`--isolated`](https://laravel.com/docs/12.x/migrations#running-migrations) flag. <br> **ℹ️ Note:** Requires Laravel v9.38.0+ |
+| `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_SEED` | `false` | `php artisan db:seed`: Runs the default seeder. <br> **ℹ️ Note:** Set to `true` to run the default seeder. If you want to run a custom seeder, set this to the name of the seeder class. |
+| `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 script performs database connection checks to ensure the database is ready. It will:
+- Clear the Laravel configuration cache before attempting migrations
+- Try to connect to the database for up to `AUTORUN_LARAVEL_MIGRATION_TIMEOUT` seconds (default: 30)
+- Show detailed connection attempts when `AUTORUN_DEBUG` is enabled
+
+## php artisan storage:link
+Creates a symbolic link from `public/storage` to `storage/app/public`.
+
+[Read more about storage links →](https://laravel.com/docs/12.x/filesystem#the-public-disk)
 
-### php artisan migrate
+## 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.
 
-You can enable the [`--isolated`](https://laravel.com/docs/11.x/migrations#running-migrations) flag by setting `AUTORUN_LARAVEL_MIGRATION_ISOLATION` to `true`, which will ensure no other containers are running a migration. 
+You can enable the [`--isolated`](https://laravel.com/docs/12.x/migrations#running-migrations) 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+
-- Your database must support database locks (meaning SQLite is not supported)
+- 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.
+
+[Read more about migrations →](https://laravel.com/docs/12.x/migrations#running-migrations)
+
+## 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 storage:link
-This command creates a symbolic link from `public/storage` to `storage/app/public`.
+[Read more about optimizing Laravel →](https://laravel.com/docs/12.x/deployment#optimization)
 
-### php artisan config:cache
+## 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.
 
-[Read more about configuration caching →](https://laravel.com/docs/11.x/configuration#configuration-caching)
+[Read more about configuration caching →](https://laravel.com/docs/12.x/configuration#configuration-caching)
 
-### php artisan route:cache
+## php artisan db:seed
+This command runs the default seeder. If you want to run a custom seeder, set `AUTORUN_LARAVEL_SEED` to the name of the seeder class.
+
+[Read more about seeding →](https://laravel.com/docs/12.x/seeding)
+
+## 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.
 
-[Read more about route caching →](https://laravel.com/docs/11.x/routing#route-caching)
+[Read more about route caching →](https://laravel.com/docs/12.x/routing#route-caching)
 
-### php artisan view:cache
+## 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.
 
-[Read more about view caching →](https://laravel.com/docs/11.x/views#optimizing-views)
+[Read more about view caching →](https://laravel.com/docs/12.x/views#optimizing-views)
 
-### php artisan event:cache
+## 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.
 
-[Read more about event caching →](https://laravel.com/docs/11.x/events#event-discovery-in-production)
+[Read more about event caching →](https://laravel.com/docs/12.x/events#event-discovery-in-production)
+
+## 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.
+
+::note
+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 ouput 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 before calling this script
+- Use automated testing to catch issues before deploying

docs/content/docs/5.customizing-the-image/3.adding-your-own-start-up-scripts.md

@@ -104,11 +104,6 @@ services:
 
 In the above file, we're building our image using the `Dockerfile` in the current directory. We're also mounting our current directory to `/var/www/html` in the container.
 
-## Don't use `exit 0` in your script
-If you use `exit 0` in your script, it will stop the execution of the rest of the entrypoint scripts. We recommend using `return 0` instead. [See this discussion](https://github.com/serversideup/docker-php/issues/481#issuecomment-2463082306) for more details on why.
-
-Long story short, we don't use subshells to execute your scripts, so `exit 0` will not work as expected. We do this because we want to ensure your script has access to the environment variables that are set in the entrypoint scripts.
-
 ## Running our example
 When we run `docker compose up`, we should see the following output:
 
@@ -135,4 +130,39 @@ example-project  | 2023/12/05 19:52:38 [info] 67#67 OpenSSL 3.0.11 19 Sep 2023,
 ```
 ::
 
-You can see our `👋 Hello, world!` is executing *after* the initialization of `10-init-unit.sh`.
+You can see our `👋 Hello, world!` is executing *after* the initialization of `10-init-unit.sh`.
+
+## Advanced Scenarios: S6 Overlay dependencies
+If you want to customize an image that uses S6 Overlay (`fpm-nginx` or `fpm-apache`), you may have an advanced scenario where you have a custom S6 service that needs to be executed after one of our entrypoint scripts. In order to do this, you'll need to move all our scripts from the `/etc/entrypoint.d` directory to the `/etc/s6-overlay/scripts` directory. This would be a very time consuming scenario if you did this manually, but thankfully you can use our `docker-php-serversideup-s6-init` script to do this for you.
+
+::code-panel
+---
+label: "Example Dockerfile"
+---
+```dockerfile
+FROM serversideup/php:8.4-fpm-nginx
+
+# Set the user to root for our build steps
+USER root
+
+# If you have your own one-shot scripts, copy them to the entrypoint.d directory
+COPY --chmod=755 ./entrypoint.d/ /etc/entrypoint.d/
+
+# Copy our entrypoint scripts into the S6 Overlay scripts directory
+RUN docker-php-serversideup-s6-init
+
+# If you have your own long running services, copy them to the s6 directory
+COPY --chmod=755 ./my-s6-service/ /etc/s6-overlay/s6-rc.d/my-s6-service/
+
+# Drop back to the non-root user
+USER www-data
+```
+::
+
+In the above file, we're copying our "one-shot" scripts to the `/etc/entrypoint.d` directory and our long running services to the `/etc/s6-overlay` directory. One-shot scripts are scripts that are intended to run quickly and then move on. Long running services are services that are intended to run for a long time and need to be monitored and restarted if they crash.
+
+The magic happens when we run `docker-php-serversideup-s6-init`. This script will move all our scripts from the `/etc/entrypoint.d` directory to the `/etc/s6-overlay/scripts` directory and set the correct dependencies for our S6 services.
+
+You can now reference our script names as dependencies in your own S6 service.
+
+[Learn more about writing your own S6 services →](https://github.com/just-containers/s6-overlay)