systemsdk/docker-nginx-php-laravel

systemsdk/docker-nginx-php-laravel repository overview

⁠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

Nginx 1.29 - Web server and reverse proxy.
PHP 8.5 fpm - Main application runtime.
MySQL 8 - Primary relational database.
Laravel 13 - High-performance PHP framework.
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):

sudo usermod -aG docker $USER

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

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:
```
composer create-project systemsdk/docker-nginx-php-laravel example-app
```
Verify that your local hosts file contains the default mapping for localhost (this is usually set by default in all operating systems):
```
127.0.0.1    localhost
```
Note: The file is located at /etc/hosts on Linux/macOS and C:\Windows\System32\drivers\etc\hosts on Windows.
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.
  xdebug.start_with_request = yes
- 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:
  xdebug.start_with_request = no
  Tip: Install the "Xdebug helper" extension for Chrome or Firefox and set the IDE Key to PHPSTORM in the extension settings.
Build and Initialize the Environment

Run the following commands in your terminal to build the Docker images, start the containers, install PHP dependencies:
```
make build
make start
make composer-install
make env-dev
```
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.
Apply Migrations and Seeds:
```
make migrate
make seed
```
Set key for application:
```
make key-generate
```
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.

Database Clean-up

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

Run the following commands in your terminal to build the staging Docker images, start the containers, install PHP dependencies:
```
make build-staging
make start-staging
```
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.
Apply Migrations:
```
make migrate-no-test
```
Set key for application:
```
make key-generate
```

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

Database Clean-up

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

Run the following commands in your terminal to build the production Docker images, start the containers, install PHP dependencies:
```
make build-prod
make start-prod
```
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.
Apply Migrations:
```
make migrate-no-test
```
Set key for application:
```
make key-generate
```

⁠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:

make ssh

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

make ssh-nginx
make ssh-supervisord
make ssh-mysql

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:

make down
make build
make start

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:

make start
make stop

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:

make down

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:

make build
make build-test
make build-staging
make build-prod

make start
make start-test
make start-staging
make start-prod

make stop
make stop-test
make stop-staging
make stop-prod

make down
make down-test
make down-staging
make down-prod

make restart
make restart-test
make restart-staging
make restart-prod

make env-dev
make env-test-ci

make ssh
make ssh-root
make fish
make ssh-nginx
make ssh-supervisord
make ssh-mysql

make composer-install-no-dev
make composer-install
make composer-update
make composer-audit

make key-generate

make info
make help

make logs
make logs-nginx
make logs-supervisord
make logs-mysql

make drop-migrate
make migrate-no-test
make migrate

make seed

make phpunit
make report-code-coverage

make phpcs
make ecs
make ecs-fix
make phpmetrics
make phpcpd
make phpcpd-html-report
make phpmd
make phpstan
make phpinsights

# ... and many more

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

⁠Architecture & packages

⁠Guidelines

⁠Development Workflow

Branching: Create a new branch from develop using one of the following patterns:
- feature/{ticketNo}
- bugfix/{ticketNo}
Commits: Commit frequently and write clear, descriptive commit messages to facilitate the review process.
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.
Review: Address any feedback from reviewers and iterate as needed.
CI/CD Checks: Ensure that all continuous integration checks (e.g., CircleCI) pass successfully and the build status is green.
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)⁠

Tag summary

Recent tags

Content type

Image

Digest

sha256:65c0f725d…

Size

405.5 MB

Last updated

14 days ago

docker pull systemsdk/docker-nginx-php-laravel

This week's pulls

Pulls:

333

Last week

Learn more⁠

Help

System theme

Docker Suite