feat: added readme, env vars for migrations and separate scheduler container

Author: juancholightit

.docker/Dockerfile

@@ -72,5 +72,10 @@ RUN chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache
 # Switch back to the non-privileged user
 USER www-data
 
+# Set environment variables, available in the README
+ENV AUTORUN_ENABLED=true
+ENV AUTORUN_LARAVEL_MIGRATION=true
+
+
 # Expose port 8080 and start php-fpm
 EXPOSE 8080

.docker/README.md

@@ -0,0 +1,100 @@
+# Laravel Docker Environment
+
+This project provides a production-ready Docker setup for a Laravel application using `serversideup/php` images. It includes a multi-stage `Dockerfile` for optimized builds and a `docker-compose.yml` file to orchestrate the application, database, and caching services.
+
+## Prerequisites
+
+- Docker
+- Docker Compose
+
+## Setup & Installation
+
+1.  **Clone the Repository:**
+    Clone this project to your local machine.
+
+2.  **Configure Environment:**
+    Create a `.env` file in the project root by copying the example file:
+    ```bash
+    cp .env.example .env
+    ```
+    Update the `.env` file with your specific application and database settings. The default database configuration is set up to work with the `docker-compose.yml` file provided.
+
+3.  **Generate Application Key:**
+    If this is a new project, you'll need to generate a Laravel application key. First, start the containers, then run the command.
+    ```bash
+    # Start containers in the background
+    docker-compose up -d --build
+
+    # Generate the key
+    docker-compose exec app php artisan key:generate
+    ```
+
+## Usage
+
+-   **Build and Start Containers:**
+    ```bash
+    docker-compose up -d --build
+    ```
+    Your application will be available at `http://localhost:8080`.
+
+-   **Stop Containers:**
+    ```bash
+    docker-compose down
+    ```
+
+-   **Stop Containers and Remove Volumes:** (Use this to start fresh)
+    ```bash
+    docker-compose down -v
+    ```
+
+## Scheduled Tasks (Cron)
+
+To run Laravel's scheduled tasks, this setup includes a dedicated `scheduler` service in the `docker-compose.yml` file.
+
+This container uses the same application image but runs a loop that executes `php artisan schedule:run` every minute. This is the standard way to handle cron jobs in a containerized Laravel application.
+
+All of your scheduled tasks are defined in the `app/Console/Kernel.php` file as usual. The `scheduler` service will automatically pick up and execute any tasks you define there.
+
+## Laravel Automations (`serversideup/php`)
+
+The `serversideup/php` image provides a powerful automation system that can run common Laravel commands for you when the container starts. This is perfect for production deployments.
+
+### Master Switch
+
+All automations are controlled by a single master switch. They will **only run** if this is enabled.
+
+-   **`AUTORUN_ENABLED`**: Set to `"true"` to enable the automation scripts. Defaults to `false`.
+
+### Automation Flags
+
+If `AUTORUN_ENABLED` is set to `"true"`, you can then toggle individual automations.
+
+| Environment Variable               | Default | Command Executed                    | Description                                                                                             |
+| ---------------------------------- | ------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `AUTORUN_LARAVEL_MIGRATION`        | `true`  | `php artisan migrate --force`       | Automatically runs your database migrations.                                                            |
+| `AUTORUN_LARAVEL_CONFIG_CACHE`     | `true`  | `php artisan config:cache`          | Caches your configuration files for a significant performance boost.                                    |
+| `AUTORUN_LARAVEL_ROUTE_CACHE`      | `true`  | `php artisan route:cache`           | Caches your route definitions.                                                                          |
+| `AUTORUN_LARAVEL_VIEW_CACHE`       | `true`  | `php artisan view:cache`            | Compiles and caches your Blade templates.                                                               |
+| `AUTORUN_LARAVEL_EVENT_CACHE`      | `true`  | `php artisan event:cache`           | Caches your application's events and listeners.                                                         |
+| `AUTORUN_LARAVEL_STORAGE_LINK`     | `true`  | `php artisan storage:link`          | Creates the symbolic link from `public/storage` to `storage/app/public`.                                |
+| `AUTORUN_LARAVEL_MIGRATION_ISOLATION` | `false` | `php artisan migrate --force --isolated` | Ensures only one container runs migrations at a time. Requires Laravel 9.38+ and a locking database. |
+| `AUTORUN_LARAVEL_MIGRATION_TIMEOUT` | `30`    | N/A                                 | The number of seconds the script will wait for the database to be available before migrating.           |
+
+## Manual Artisan Commands
+
+You can run any `artisan` command manually by executing it inside the `app` container.
+
+-   **Run Migrations:**
+    ```bash
+    docker-compose exec app php artisan migrate
+    ```
+
+-   **Access Tinker:**
+    ```bash
+    docker-compose exec app php artisan tinker
+    ```
+
+-   **Clear Cache:**
+    ```bash
+    docker-compose exec app php artisan optimize:clear
+    ```

docker-compose.yml

@@ -1,7 +1,7 @@
-# docker-compose.yml for a Laravel application
+# docker-compose.yml for a Laravel application with PostgreSQL
 
 services:
-  # Application Service
+  # Application Service (with built-in Nginx)
   app:
     build:
       context: .
@@ -11,43 +11,61 @@ services:
     restart: unless-stopped
     tty: true
     environment:
+      # These environment variables are used by the serversideup/php image
+      # to configure the built-in Nginx and PHP-FPM.
       SERVICE_NAME: app
       SERVICE_TAGS: dev
+
+      # --- Laravel Automations ---
+      # Master switch for all automations. Set to "true" to enable.
+      AUTORUN_ENABLED: "true"
+
+      # Individual toggles for each automation.
+      # These only work if AUTORUN_ENABLED is "true".
+      AUTORUN_LARAVEL_MIGRATION: "true"
+      AUTORUN_LARAVEL_CONFIG_CACHE: "true"
+      AUTORUN_LARAVEL_ROUTE_CACHE: "true"
+      AUTORUN_LARAVEL_VIEW_CACHE: "true"
+      AUTORUN_LARAVEL_EVENT_CACHE: "true"
+      AUTORUN_LARAVEL_STORAGE_LINK: "true"
+
     working_dir: /var/www/html
     volumes:
       - ./:/var/www/html
+    ports:
+      # Expose the port from the Nginx running inside this container
+      - "8080:8080"
     networks:
       - laravel
+    depends_on:
+      - pgsql
 
-  # Nginx Service
-  nginx:
-    image: nginx:alpine
-    container_name: laravel-nginx
+  # Scheduler Service (Cron)
+  scheduler:
+    image: your-laravel-app
+    container_name: laravel-scheduler
     restart: unless-stopped
-    ports:
-      - "8080:80"
+    working_dir: /var/www/html
     volumes:
       - ./:/var/www/html
-      - ./docker/nginx/conf.d/:/etc/nginx/conf.d/
+    command: >
+      sh -c "while true; do php artisan schedule:run >> /dev/null 2>&1; sleep 60; done"
     networks:
       - laravel
 
-  # Database Service (MySQL)
-  db:
-    image: mysql:8.0
-    container_name: laravel-db
+  # Database Service (PostgreSQL)
+  pgsql:
+    image: postgres:15-alpine
+    container_name: laravel-pgsql
     restart: unless-stopped
     environment:
-      MYSQL_DATABASE: ${DB_DATABASE}
-      MYSQL_ROOT_PASSWORD: ${DB_PASSWORD}
-      MYSQL_PASSWORD: ${DB_PASSWORD}
-      MYSQL_USER: ${DB_USERNAME}
-      SERVICE_TAGS: dev
-      SERVICE_NAME: mysql
+      POSTGRES_DB: laravel
+      POSTGRES_USER: sail
+      POSTGRES_PASSWORD: password
     volumes:
-      - dbdata:/var/lib/mysql
+      - pgdata:/var/lib/postgresql/data
     ports:
-      - "3306:3306"
+      - "5432:5432"
     networks:
       - laravel
 
@@ -68,5 +86,5 @@ networks:
 
 # Volumes
 volumes:
-  dbdata:
+  pgdata:
     driver: local