From 18cf2e57cd74b89d183afe2421addfb1e8190162 Mon Sep 17 00:00:00 2001 From: Vincent Letourneau Date: Fri, 28 Jul 2017 13:10:20 +0200 Subject: [PATCH] Update README --- README.md | 317 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 205 insertions(+), 112 deletions(-) diff --git a/README.md b/README.md index 433d252..99e1092 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,63 @@ Docker running Nginx, PHP-FPM, Composer, MySQL and PHPMyAdmin. -## Images to use +## Overview + +--- + +1. [Install prerequisites](#install-prerequisites) + + Before installing project make sure the following prerequisites have been met. + +2. [Clone the project](#clone-the-project) + + We’ll download the code from its repository on GitHub. + +5. [Configure Nginx With SSL Certificates](#configure-nginx-with-ssl-certificates) + + We'll generate and configure SSL certificate for nginx before running server. + +3. [Run the application](#run-the-application) + + By this point we’ll have all the project pieces in place. + +4. [Use Makefile](#use-makefile) `Recommended` + + When developing, you can use `Makefile` for doing recurrent operations. + +5. [Use Docker Commands](#use-docker-commands) + + When running, you can use docker commands for doing recurrent operations. + +___ + +## Install prerequisites + +All requisites should be available for your distribution. The most important are : + +* [Git](https://git-scm.com/downloads) +* [Docker](https://docs.docker.com/engine/installation/) +* [Docker Compose](https://docs.docker.com/compose/install/) + +Check if `docker-compose` is already installed by entering the following command : + +```sh +which docker-compose +``` + +The following is optional but makes life more enjoyable : + +```sh +which make +``` + +On Ubuntu and Debian these are available in the meta-package build-essential. On other distributions, you may need to install the GNU C++ compiler separately. + +```sh +sudo apt install build-essential +``` + +### Images to use * [Nginx](https://hub.docker.com/_/nginx/) * [MySQL](https://hub.docker.com/_/mysql/) @@ -11,72 +67,31 @@ Docker running Nginx, PHP-FPM, Composer, MySQL and PHPMyAdmin. * [PHPMyAdmin](https://hub.docker.com/r/phpmyadmin/phpmyadmin/) * [Generate Certificate](https://hub.docker.com/r/jacoelho/generate-certificate/) -## Start using it +You should be careful when installing third party web servers such as MySQL or Nginx. -1. Download it : +This project use the following ports : - ```sh - git clone https://github.com/nanoninja/docker-nginx-php-mysql.git +| Server | Port | +|-----------|------| +| MySQL | 3306 | +| Nginx | 8000 | +| Nginx SSL | 3000 | - cd docker-nginx-php-mysql - ``` +## Clone the project -2. Copying the composer configuration file : - - ```sh - cp web/app/composer.json.dist web/app/composer.json - ``` - -3. Start : - - ```sh - docker-compose up -d - ``` - - **Please wait this might take a several minutes...** - -4. Open your favorite browser : - - * [http://localhost:8000](http://localhost:8000/) - * [https://localhost:3000](https://localhost:3000/) ([HTTPS](https://github.com/nanoninja/docker-nginx-php-mysql#generating-ssl-certificates) not configured by default) - * [phpMyAdmin](http://localhost:8080/) (user: dev, pass: dev) - -5. Stop : - - ```sh - docker-compose stop && docker-compose kill && docker-compose rm -f - ``` - -## Makefile - -When developing, you can use the [Makefile](https://en.wikipedia.org/wiki/Make_(software)) for doing the following operations : - -| Name | Description | -|---------------|-----------------------------------------| -| apidoc | Generate documentation of API | -| clean | Clean directories for reset | -| composer-up | Update php composer | -| docker-start | Create and start containers | -| docker-stop | Stop all services | -| docker-sweep | Sweep old containers and volumes | -| gen-certs | Generate SSL certificates for **nginx** | -| mysql-dump | Create backup of whole database | -| mysql-restore | Restore backup from whole database | -| test | Test application with phpunit | - -### Example : +To install [Git](http://git-scm.com/book/en/v2/Getting-Started-Installing-Git), download it and install following the instructions : ```sh -make docker-start +git clone https://github.com/nanoninja/docker-nginx-php-mysql.git ``` -Show help +Go to the project directory : ```sh -make help +cd docker-nginx-php-mysql ``` -## Directory tree +### Project tree ```sh . @@ -108,7 +123,137 @@ make help └── index.php ``` -## Connecting from PDO +## Configure Nginx With SSL Certificates + +1. Generate SSL certificates + + ```sh + docker run --rm -v $(PWD)/etc/ssl:/certificates -e "SERVER=localhost" jacoelho/generate-certificate + ``` + +2. Configure Nginx + + Edit nginx file `etc/nginx/default.conf` and uncomment the server section : + + ```sh + # server { + # server_name localhost; + # + # listen 443 ssl; + # ... + # } + ``` + +## Run the application + +1. Copying the composer configuration file : + + ```sh + cp web/app/composer.json.dist web/app/composer.json + ``` + +2. Start the application : + + ```sh + sudo docker-compose up -d + ``` + + **Please wait this might take a several minutes...** + +3. Open your favorite browser : + + * [http://localhost:8000](http://localhost:8000/) + * [https://localhost:3000](https://localhost:3000/) ([HTTPS](#configure-nginx-with-ssl-certificates) not configured by default) + * [phpMyAdmin](http://localhost:8080/) (username: dev, password: dev) + +4. Stop and clear services + + ```sh + sudo docker-compose stop && sudo docker-compose kill && sudo docker-compose rm -f + ``` + +## Use Makefile + +When developing, you can use the [Makefile](https://en.wikipedia.org/wiki/Make_(software)) for doing the following operations : + +| Name | Description | +|---------------|-----------------------------------------| +| apidoc | Generate documentation of API | +| clean | Clean directories for reset | +| composer-up | Update php composer | +| docker-start | Create and start containers | +| docker-stop | Stop all services | +| docker-sweep | Sweep old containers and volumes | +| gen-certs | Generate SSL certificates for **nginx** | +| mysql-dump | Create backup of whole database | +| mysql-restore | Restore backup from whole database | +| test | Test application with phpunit | + +### Examples + +Start the application : + +```sh +sudo make docker-start +``` + +Show help : + +```sh +sudo make help +``` + +## Use Docker commands + +### Updating PHP dependencies with composer + +```sh +sudo docker run --rm -v $(pwd)/web/app:/app composer/composer update +``` + +### Generating PHP API documentation + +```sh +sudo docker exec -i $(sudo docker-compose ps -q php) php ./app/vendor/apigen/apigen/bin/apigen generate -s app/src -d app/doc +``` + +### Testing PHP application + +```sh +sudo docker exec -i $(sudo docker-compose ps -q php) app/vendor/bin/phpunit --colors=always --configuration app/ +``` + +### Handling database + +#### MySQL shell access + +```sh +sudo docker exec -it mysql bash +``` + +and + +```sh +mysql -u"$MYSQL_ROOT_USER" -p"$MYSQL_ROOT_PASSWORD" +``` + +#### Backup of database + +```sh +mkdir -p data/db/dumps +``` + +```sh +source .env && sudo docker exec -i mysql mysqldump --all-databases -u"$MYSQL_ROOT_USER" -p"$MYSQL_ROOT_PASSWORD" > "data/db/dumps/db.sql" +``` + +or + +```sh +source .env && sudo docker exec -i mysql mysqldump test -u"$MYSQL_ROOT_USER" -p"$MYSQL_ROOT_PASSWORD" > "data/db/dumps/test.sql" +``` + +#### Connecting MySQL from [PDO](http://php.net/manual/en/book.pdo.php) ```php ``` -## Updating composer +## Help us ! -```sh -docker run --rm -v $(PWD)/web/app:/app composer/composer update -``` +--- -## MySQL Container shell access +Any thought, feedback or (hopefully not!) -```sh -docker exec -it mysql bash -``` - -and - -```sh -mysql -uroot -proot -``` - -## Creating database dumps - -```sh -source .env && docker exec -i $(docker-compose ps -q mysqldb) mysqldump --all-databases -u"$MYSQL_ROOT_USER" -p"$MYSQL_ROOT_PASSWORD" > "$MYSQL_DUMPS_DIR/db.sql" -``` - -or - -```sh -source .env && docker exec -i $(docker-compose ps -q mysqldb) mysqldump test -u"$MYSQL_ROOT_USER" -p"$MYSQL_ROOT_PASSWORD" > "$MYSQL_DUMPS_DIR/test.sql" -``` - -## Generating SSL certificates - -1. Generate certificates - - ```sh - docker run --rm -v $(PWD)/etc/ssl:/certificates -e "SERVER=localhost" jacoelho/generate-certificate - ``` - -2. Configure Nginx - - Edit nginx file **etc/nginx/default.conf** and uncomment the server section : - - ```nginx - # server { - # ... - # } - ``` - -## Generating API Documentation - -```sh -docker exec -i $(docker-compose ps -q php) php ./app/vendor/apigen/apigen/bin/apigen generate -s app/src -d app/doc -``` - -## Cleaning project - -```sh -./bin/linux/clean.sh $(pwd) -``` +Developed by [@letvinz](https://twitter.com/letvinz) \ No newline at end of file