Download the PHP package systemsdk/docker-apache-php-laravel without Composer

PHP Laravel Environment

A scalable Docker-based environment required to run Laravel (based on official php and mysql docker hub repositories).

Source code

Requirements

• Docker Engine version 23.0 or later
• Docker Compose version 2.0 or later
• An editor or IDE
• MySQL Workbench

Note: We recommend using a Linux Ubuntu-based OS for the best experience.

Components

1. Apache 2.4 - Web server.
2. PHP 8.5 (Apache handler) - Main application runtime.
3. MySQL 8 - Primary relational database.
4. Laravel 13 - High-performance PHP framework.
5. Mailpit - Email testing tool (available in the development environment only).

Setting up Docker Engine & Docker Compose

To install Docker Engine and Docker Compose, please follow the official Docker Engine Installation Guide.

For Linux Users: After installation, run the following command to manage Docker as a non-root user (this allows you to run Docker without sudo):

Note: You must log out and log back in for this change to take effect.

For macOS Users: If you are using Docker Desktop for macOS 12.2 or later, we highly recommend enabling virtiofs for a significant performance boost.

Note: Enabled by default since Docker Desktop v4.22.

Setting up the DEV environment

1. You can clone this repository from GitHub or install via composer.

   Note: Delete the storage/mysql-data folder if it exists before starting.

   If you have installed composer, you can use the next cmd command:

2. Verify that your local hosts file contains the default mapping for localhost (this is usually set by default in all operating systems):

   Note: The file is located at /etc/hosts on Linux/macOS and C:\Windows\System32\drivers\etc\hosts on Windows.

3. Configure Xdebug (Optional)

   Depending on your operating system, you can customize Xdebug behavior by editing either /docker/dev/xdebug-main.ini (Linux/Windows) or /docker/dev/xdebug-osx.ini (macOS).

   • To debug every request (Default):

     This is the default setting. It will intercept and debug all incoming API requests.

   • To debug only specific requests (On-Demand):

     If you prefer to trigger the debugger manually only when making requests from a browser frontend, change the configuration to:

     Tip: Install the "Xdebug helper" extension for Chrome or Firefox and set the IDE Key to PHPSTORM in the extension settings.

4. Build and Initialize the Environment

   Run the following commands in your terminal to build the Docker images, start the containers, install PHP dependencies:

   Note 1: To change the default Docker configurations (such as WEB_PORT), open the .env file, update the required variables, then stop, rebuild, and restart the containers.

   Note 2: When modifying database variables in the .env file (like MYSQL_VERSION or MYSQL_ROOT_PASSWORD), ensure you stop the containers and delete the storage/mysql-data directory before rebuilding the images.

5. Apply Migrations and Seeds:

6. Set key for application:

7. Access Application Services

   Once the environment is successfully running, you can access the various services in your browser using the following URLs:

   • DEV page: http://localhost
   • Mailpit (Debug Email): http://localhost:8025

Setting up the STAGING environment locally

Important: This section describes how to set up the staging environment locally for debugging and verification purposes only. A real STAGING environment must be deployed on a dedicated server and should be as close to the PRODUCTION environment as possible.

Note 1: These steps assume you have already completed steps 1 through 2 of the "Setting up the DEV environment" section above.

Note 2: If you want to change default docker configurations (web_port, etc...) - create uncommitted .env file, copy data from .env.staging, edit necessary environment variables values.

1. Database Clean-up

   Delete the storage/mysql-data and vendor folder if it exists before starting.

2. Build and Initialize the Environment

   Run the following commands in your terminal to build the staging Docker images, start the containers, install PHP dependencies:

   Note: With opcache.validate_timestamps=0 (php.ini) enabled for performance, any manual file changes or code updates require a PHP-FPM restart/reload to take effect.

3. Apply Migrations:

4. Set key for application:

Setting up the PROD environment locally

Important: This section describes how to set up the production environment locally for debugging and verification purposes only. A real PROD environment must be deployed on a dedicated server.

Note 1: These steps assume you have already completed steps 1 through 2 of the "Setting up the DEV environment" section above.

Note 2: If you want to change default docker configurations (web_port, etc...) - create uncommitted .env file, copy data from .env.prod, edit necessary environment variables values.

1. Database Clean-up

   Delete the storage/mysql-data and vendor folder if it exists before starting.

2. Build and Initialize the Environment

   Run the following commands in your terminal to build the production Docker images, start the containers, install PHP dependencies:

   Note: With opcache.validate_timestamps=0 (php.ini) enabled for performance, any manual file changes or code updates require a PHP-FPM restart/reload to take effect.

3. Apply Migrations:

4. Set key for application:

Accessing Container Shells

Once the application is running (via make start), you can easily access the command line inside your containers.

To open a shell inside the main laravel container, run:

You can also access the other services using the following commands:

Tip: Type exit and press Enter to leave the container's shell and return to your local terminal.

Rebuilding Containers

If you modify any Dockerfile or environment configurations, you will need to rebuild the containers using the following commands:

Note: Use environment-specific commands if you need to rebuild the test, staging, or production environments. For a complete list of available commands, run make help.

Starting and Stopping Containers

Use the following commands to start or stop the development environment:

If you are working with the staging or production environments, use their respective commands:

• Staging: make start-staging or make stop-staging.
• Production: make start-prod or make stop-prod.

Stopping and Removing Containers

To completely stop and remove all environment containers and networks, use the following command:

Note: Use environment-specific commands if you need to tear down the test, staging, or production environments. For a complete list of available commands, run make help.

Available Makefile Commands

Here is a reference list of the primary commands available for managing the environment, databases, logs and testing:

Note: For a complete list of all available commands, please inspect the Makefile directly or run make help.

Architecture & packages

• Laravel
• phpunit
• laravel-ide-helper
• scriptsdev
• composer-bin-plugin
• ergebnis/composer-normalize
• composer-unused
• composer-require-checker
• security-advisories
• php-coveralls
• easy-coding-standard
• PhpMetrics
• phpcpd
• phpmd
• phpstan
• phpinsights
• rector

Guidelines

• Commands
• Development
• IDE PhpStorm Configuration
• Xdebug Configuration
• Code Quality Tools
• Testing

Development Workflow

1. Branching: Create a new branch from develop using one of the following patterns:
   • feature/{ticketNo}
   • bugfix/{ticketNo}
2. Commits: Commit frequently and write clear, descriptive commit messages to facilitate the review process.
3. Pull Request: Push your branch to the repository and open a Pull Request (PR) against the develop branch. Use the following naming convention for your PR: feature/{ticketNo} - Short descriptive title of the Jira task.
4. Review: Address any feedback from reviewers and iterate as needed.
5. CI/CD Checks: Ensure that all continuous integration checks (e.g., CircleCI) pass successfully and the build status is green.
6. Merge: Once approved, your PR will be squashed and merged into develop. It will later be merged into a release/{version} branch for deployment.

Note: For a detailed visual guide on this branching model, please refer to the Git Flow Cheatsheet.

License

The MIT License (MIT)