Download the PHP package systemsdk/docker-nginx-php-symfony without Composer

PHP Symfony Environment

A scalable Docker-based environment required to run Symfony (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. Nginx 1.29 - Web server and reverse proxy.
2. PHP 8.5 fpm - Main application runtime.
3. MySQL 8 - Primary relational database.
4. Symfony 7 - High-performance PHP framework.
5. RabbitMQ 4 - Robust message broker for background jobs.
6. 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.

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

2. Set a unique APP_SECRET for the application in .env.prod and .env.staging files.

   • Secret Key: You can generate a secure key by running: openssl rand -hex 16 (do not use third-party websites for generating this value).
   • Environment Files: Do not use .env.local.php on dev and test environments (delete it if it exists).
   • Custom Configs: If you want to change default web port/xdebug configurations, you can create an .env.local file and override parameters there (see .env file).
   • Database: Delete the var/mysql-data folder if it exists before starting.

3. 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.

4. 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.

5. Build and Initialize the Environment

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

6. Apply Migrations and Configurations

   Execute the following commands to set up the database structure, prepare message broker transports:

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
   • RabbitMQ Management: http://localhost:15672
   • 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: These steps assume you have already completed steps 1 through 3 of the "Setting up the DEV environment" section above.

1. Database Clean-up

   Delete the var/mysql-data 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:

   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 and Configurations

   Execute the following commands to set up the database structure, prepare message broker transports:

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: These steps assume you have already completed steps 1 through 3 of the "Setting up the DEV environment" section above.

1. Database and RabbitMQ Clean-up

   Delete the var/mysql-data, var/rabbitmq folders if they exist before starting.

2. Edit the .env.prod file and set a secure password for MySQL, as well as a username and password for RabbitMQ.

3. Build and Initialize the Environment

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

   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.

4. Apply Migrations and Configurations

   Execute the following commands to set up the database structure, prepare message broker transports:

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 Symfony 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

• Symfony
• doctrine-migrations-bundle
• doctrine-fixtures-bundle
• command-scheduler-bundle
• phpunit
• phpunit-bridge
• browser-kit
• css-selector
• security-checker
• messenger
• composer-bin-plugin
• composer-normalize
• composer-unused
• composer-require-checker
• requirements-checker
• security-advisories
• php-coveralls
• easy-coding-standard
• PhpMetrics
• phpcpd
• phpmd
• phpstan
• phpinsights
• rector

Guidelines

• Commands
• Development
• IDE PhpStorm Configuration
• Xdebug Configuration
• Messenger Component
• 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)