This project will help you to start a PHP project with Docker, thanks to some useful make commands.
Install Docker (>= 1.12) for MacOSX / Linux following the official instructions: https://docs.docker.com/engine/installation
Install docker-compose (>= 1.8.0) for MacOSX / Linux following the official instructions: https://docs.docker.com/compose/install
Important: for now, we do not recommend using Windows.
Important: make sure you're not using root user. Your current user must be a sudoer and be able to run docker commands.
First, fork this project and clone it or download the tarball using:
curl -L https://github.com/thecodingmachine/kickoff-docker-php/archive/master.tar.gz > kickoff-docker-php.tar.gz
Once done, move to the root directory of this project and run:
cp .env.template .env
Now open the file located at /etc/hosts (on MacOS / Linux) and add the following line at the end of the file:
127.0.0.1 dev.yourproject.com
Good 😃? We're now done with the configuration! 🤘
Last but not least, shutdown your local Apache or anything which could use your 80 and 443 ports, and run:
make kickoff
The installation might take some time, so go for a coffee break! ☕
Once everything has been installed, open your favorite web browser and copy / paste http://dev.yourproject.com and check if everything is OK!
There are three important files:
.env.templatewhich contains environment variables with default values. These values should not be used directly, that's why you have to runcp .env.template .env.docker-compose.yml.templatewhich contains the run configuration of the Apache and MySQL containers plus some of the environment variables defined in.env.template.docker-compose-nginx.yml.templatewhich contains the run configuration of the NGINX container plus some of the environment variables defined in.env.template.
The command make kickoff will create the docker-compose.yml and docker-compose-nginx.yml files using the environment variables' values defined in the .env file.
For security concern, these three files are not versioned, because they contain sensible data like the MySQL database password and so on.
| Command | Description |
|---|---|
| prepare | Creates the docker-compose.yml and docker-compose-nginx.yml files using the environment variables specified in the .env file. |
| build | Builds the Apache container. |
| down | Stops the Apache and MySQL containers, deletes their network and cleans the docker cache. |
| up | Ups the Apache and MySQL containers. |
| nginx-down | Stops the NGINX container and deletes its network. |
| nginx-up | Ups the NGINX container. |
| kickoff | Combo of down, prepare, build, nginx-up and up commands. |
| composer cmd=yourcommand | Allows you to run a composer command. Ex: make composer cmd=install, make composer cmd=update, ... |
| npm cmd=yourcommand | Allows you to run a npm command. Ex: make npm cmd=install, make npm cmd="install --save-dev gulp", ... |
| export | This command will dump the database into two SQL files located at mysql/dumps. The files will be named as yourdatabasename.sql and yourdatabasename.Y-m-d:H:M:S.sql. |
| import | This command will drop the database, recreate it and then run the yourdatabasename.sql file. |
| shell | Connects through bash to the Apache container. |
| shell-nginx | Connects through bash to the NGINX container. |
| shell-mysql | Connects through bash to the MySQL container. |
| mysql-cli | Opens the MySQL cli. |
| tail | Displays the docker's logs of the Apache container. |
| tail-nginx | Displays the docker's logs of the NGINX container. |
| tail-mysql | Displays the docker's logs of the MySQL container. |
Open your .env file in your favorite editor, set the variable WITH_XDEBUG=1 and run make kickoff.
It will enable Xdebug on the Apache container. Use it only for your development environment!
Open your .env file in your favorite editor, set the variable WITH_SSL=1 and run make kickoff.
It will enable SSL on the NGINX container. Make sure that you have defined the correct path to your certifications in CERTS_PATH!
You will find more information on how to make SSL work here: https://github.com/jwilder/nginx-proxy#ssl-support
If you're using SSL Certificate Chains, we advise you to read the official NGINX documentation: https://www.nginx.com/resources/admin-guide/nginx-ssl-termination/#cert_chains
As you long as each PROXY_NAME variables in your .env files have the same value, you are able to run as many environments as you need.
Make sure that you have defined a different APACHE_VIRTUAL_HOST value for each of your Apache containers.
Also, use only letters (no whitespaces, special characters and so on) for the PROXY_NAME variables value!
- Use Xdebug with PhpStorm
- Use MySQL Workbench to manage your database
- Install a Postfix container
- Install Gulp
- Install Mouf framework
A make command failed to run entirely
Sometimes, you need to re-run a make command, especially the commands make build, make kickoff, make composer cmd=install, make import.
docker-compose failed to parse my yaml file
Make sure that your file's indents are corrects!
I've added a make command, but it's not working
Make sure that your Makefile uses tab indents! In PhpStorm, click on Edit > Convert Indents > To Tabs.
My web application is not really fast while developing on MacOS
Yep, this seems to be a current limitation of Docker on MacOS. But don't worry, it will be way faster on a Linux distribution (like your production server).