update README

Author: rw4lll

README.md

@@ -21,87 +21,114 @@
 
 ## Overview
 
-The **Laravel Docker Examples Project** provides practical examples and comprehensive guidance for Laravel developers to create modern, efficient, and flexible Docker environments for both development and production. By demonstrating best practices and offering detailed configurations, this project helps you build Docker images tailored for Laravel applications. Whether you're new to Docker or looking to optimize your deployment workflow, these examples serve as a solid foundation to understand and extend Docker functionalities in your Laravel projects.
+The **Laravel Docker Examples Project** offers practical and modular examples for Laravel developers to create efficient Docker environments for development and production. This project demonstrates modern Docker best practices, including multi-stage builds, modular configurations, and environment-specific customization. It is designed to be educational, flexible, and extendable, providing a solid foundation for Dockerizing Laravel applications.
 
 
 ## Project Structure
 
-The project is organized into the following main directories:
+The project is organized as a typical Laravel application, with the addition of a `docker` directory containing the Docker configurations and scripts. These are separated by environments and services. There are two main Docker Compose projects in the root directory:
 
-- **example-app**: Contains a sample Laravel 11 application used to test and demonstrate Docker environments.
-- **development**: Includes Docker configurations and Compose files for setting up a complete development environment.
-- **production**: Contains Dockerfiles and Compose files optimized for a production environment.
+- **compose.dev.yaml**: Orchestrates the development environment.
+- **compose.prod.yaml**: Orchestrates the production environment.
 
-### example-app
+### Directory Structure
 
-The `example-app` directory holds the sample Laravel application. It includes basic routes, a health check endpoint to test database and Redis connections, and demonstrates how to integrate Laravel with Docker. This serves as a practical example to illustrate the concepts discussed in this project.
-
-### Development Environment
+```
+project-root/ 
+├── app/ # Laravel app folder
+├── ...  # Other Laravel files and directories 
+├── docker/ 
+│   ├── common/ # Shared configurations
+│   ├── development/ # Development-specific configurations 
+│   ├── production/ # Production-specific configurations
+├── compose.dev.yaml # Docker Compose for development 
+├── compose.prod.yaml # Docker Compose for production 
+└── .env.example # Example environment configuration
+```
 
-Located in the `development` directory, this environment focuses on providing a flexible and independent setup that includes all necessary tools for typical Laravel development:
+This modular structure ensures shared logic between environments while allowing environment-specific customizations.
 
-- **Services**: PHP-FPM, Nginx, Node.js, Redis, and PostgreSQL.
-- **Hot Reloading**: Supports live reloading of code changes without rebuilding containers.
-- **Custom Dockerfiles**: Allows customization of images to include extensions and tools needed for development.
-- **Docker Compose**: Orchestrates the various services, making it easy to start and stop the entire environment.
 
 ### Production Environment
 
-The `production` directory emphasizes building a slim, secure, and efficient Docker image suitable for deploying a Laravel application in production:
+The production environment is configured using the `compose.prod.yaml` file. It is optimized for performance and security, using multi-stage builds and runtime-only dependencies. It uses a shared PHP-FPM multi-stage build with the target `production`.
 
-- **Optimized Images**: Uses multi-stage builds to keep the final image size small.
-- **Pre-Built Assets**: Assets are compiled during the build process to ensure the container is ready to serve content immediately.
+- **Optimized Images**: Multi-stage builds ensure minimal image size and enhanced security.
+- **Pre-Built Assets**: Assets are compiled during the build process, ensuring the container is ready to serve content immediately upon deployment.
+- **Health Checks**: Built-in health checks monitor service statuses and ensure smooth operation.
 - **Security Best Practices**: Minimizes the attack surface by excluding unnecessary packages and users.
-- **Docker Compose for Production**: Provides a Compose file tailored for deploying the application with services like Nginx, PHP-FPM, Redis, and PostgreSQL.
+- **Docker Compose for Production**: Tailored for deploying Laravel applications with Nginx, PHP-FPM, Redis, and PostgreSQL.
+
+This environment is designed for easy deployment to any Docker-compatible hosting platform.
+
+
+### Development Environment
+
+The development environment is configured using the `compose.dev.yaml` file and is built on top of the production version. This ensures the development environment is as close to production as possible while still supporting tools like Xdebug and writable permissions.
+
+Key features include:
+- **Close Parity with Production**: Mirrors the production environment to minimize deployment issues.
+- **Development Tools**: Includes Xdebug for debugging and writable permissions for mounted volumes.
+- **Hot Reloading**: Volume mounts enable real-time updates to the codebase without rebuilding containers.
+- **Services**: PHP-FPM, Nginx, Redis, PostgreSQL, and Node.js (via NVM).
+- **Custom Dockerfiles**: Extends shared configurations to include development-specific tools.
+
+To set up the development environment, follow the steps in the **Getting Started** section.
 
 
 ## Getting Started
 
 Follow these steps to set up and run the Laravel Docker Examples Project:
 
-### Clone the Repository
+### Prerequisites
+Ensure you have Docker and Docker Compose installed. You can verify by running:
 
 ```bash
-git clone https://github.com/rw4lll/laravel-docker-examples.git
-cd laravel-docker-examples
+docker --version
+docker compose version
 ```
 
-### Setting Up the Development Environment
+If these commands do not return the versions, install Docker and Docker Compose using the official documentation: [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/).
 
-1. Navigate to the specific example in Development Directory:
+### Clone the Repository
 
 ```bash
-cd development/nginx-fpm
+git clone https://github.com/rw4lll/laravel-docker-examples.git
+cd laravel-docker-examples
 ```
 
-2. Copy the .env.example file to .env and adjust any necessary environment variables:
+### Setting Up the Development Environment
+
+1. Copy the .env.example file to .env and adjust any necessary environment variables:
 
 ```bash
 cp .env.example .env
 ```
 
-3. Start the Docker Compose Services:
+Hint: adjust the `UID` and `GID` variables in the `.env` file to match your user ID and group ID. You can find these by running `id -u` and `id -g` in the terminal.
+
+2. Start the Docker Compose Services:
 
 ```bash
-docker compose up -d
+docker compose -f compose.dev.yaml up -d
 ```
 
-4. Install Laravel Dependencies:
+3. Install Laravel Dependencies:
 
 ```bash
-docker compose exec workspace bash
+docker compose -f compose.dev.yaml exec workspace bash
 composer install
 npm install
 npm run dev
 ```
 
-5. Run Migrations:
+4. Run Migrations:
 
 ```bash
-docker compose exec workspace php artisan migrate
+docker compose -f compose.dev.yaml exec workspace php artisan migrate
 ```
 
-6. Access the Application:
+5. Access the Application:
 
 Open your browser and navigate to [http://localhost](http://localhost).
 
@@ -111,40 +138,40 @@ Here are some common commands and tips for using the development environment:
 
 ### Accessing the Workspace Container
 
-The workspace container includes Composer, Node.js, NPM, and other tools necessary for development.
+The workspace sidecar container includes Composer, Node.js, NPM, and other tools necessary for Laravel development (e.g. assets building).
 
 ```bash
-docker compose exec workspace bash
+docker compose -f compose.dev.yaml exec workspace bash
 ```
 
 ### Run Artisan Commands:
 
 ```bash
-docker compose exec workspace php artisan migrate
+docker compose -f compose.dev.yaml exec workspace php artisan migrate
 ```
 
 ### Rebuild Containers:
 
 ```bash
-docker compose up -d --build
+docker compose -f compose.dev.yaml up -d --build
 ```
 
 ### Stop Containers:
 
 ```bash
-docker compose down
+docker compose -f compose.dev.yaml down
 ```
 
 ### View Logs:
 
 ```bash
-docker compose logs -f
+docker compose -f compose.dev.yaml logs -f
 ```
 
 For specific services, you can use:
 
 ```bash
-docker compose logs -f web
+docker compose -f compose.dev.yaml logs -f web
 ```
 
 ## Production Environment
@@ -158,26 +185,6 @@ The production environment is designed with security and efficiency in mind:
 - **HTTPS Setup**: While not included in this example, it's recommended to configure SSL certificates and use HTTPS in a production environment.
 
 
-### Building and Running the Production Environment
-
-1. **Navigate to the specific example in Production Directory :**
-
-```bash
-cd production/nginx-fpm/
-```
-
-2. Copy the .env.example file to .env (compose env, not the laravel env file) and adjust any necessary environment variables:
-
-```bash
-cp .env.example .env
-```
-
-3. Start the Docker Compose Services:
-
-```bash
-docker compose up -d
-```
-
 ### Deploying
 
 The production image can be deployed to any Docker-compatible hosting environment, such as AWS ECS, Kubernetes, or a traditional VPS.