README

Drupal 8 skeleton dockerized in sperate containers (Nginx, PHP-FPM, MySQL and PHPMyAdmin).

Overview

Install prerequisites

Before installing project make sure the following prerequisites have been met.
Clone the project

We’ll download the code from its repository on GitHub.
Configure Xdebug [Optional]

We'll configure Xdebug for IDE (PHPStorm or Netbeans).
Run the application

By this point we’ll have all the project pieces in place.
Use Makefile [Optional but strongly encouraged for beginner]

When developing, you can use Makefile for doing recurrent operations.
Use Docker Commands

When running, you can use docker commands for doing recurrent operations.

Install prerequisites

For now, this project has been mainly created for Unix (Linux/MacOS). Perhaps it could work on Windows.

All requisites should be available for your distribution. The most important are :

Check if docker-compose is already installed by entering the following command :

which docker-compose

Check Docker Compose compatibility :

Compose file version 3 reference

The following is optional but makes life better :

which make

Images to use

You should be careful when installing third party web servers such as MySQL or Nginx.

This project use the following ports :

Server	Port
MySQL	8989
PHPMyAdmin	8080
Nginx	8000
Nginx SSL	3000

Clone the project

To install Git, download it and install following the instructions :

git clone -b drupal8-skeleton-docker git@github.com:woprrr/drupal8-composer-template.git

Go to the project directory :

cd drupal8-composer-template

Project tree

.
├── LICENSE
├── Makefile
├── README.md
├── app
│   └── Drupal
│       └── parameters.yml.dist
├── composer.json.dist
├── composer.require.json
├── composer.required.json.dist
├── composer.suggested.json.dist
├── config
├── data
│   └── db
│       ├── dumps
│       └── mysql
├── doc
├── docker-compose.yml
├── etc
│   ├── nginx
│   │   ├── default.conf
│   │   └── default.template.conf
│   ├── php
│   │   └── php.ini
│   └── ssl
├── scripts
│   └── Composer
│       ├── DrupalExportConf.php
│       ├── DrupalHandlerBase.php
│       ├── DrupalInstall.php
│       └── DrupalUpdate.php
└── settings
    ├── development.services.yml.dist
    ├── phpunit.xml.dist
    ├── services.yml
    ├── settings.local.php.dist
    └── settings.php

Configure Xdebug

If you use another IDE than PHPStorm or Netbeans, go to the remote debugging section of Xdebug documentation.

For a better integration of Docker to PHPStorm, use the documentation.

Get your own local IP address :
```
sudo ifconfig
```
Edit php file etc/php/php.ini and comment or uncomment the configuration as needed.

Set the remote_host parameter with your IP :

xdebug.remote_host=192.168.0.1 # your IP

Run the application

Setup project environment variables :

Setup your project by editing the .env file and customize all environement variables. Specifically all Drupal_* variable are criticaly important to next steps and to customize your drupal instances.
Initialize/Install project dependencies :
```
make docker-start
```
Please wait this might take a several minutes...
```
sudo docker-compose logs -f # Follow log output
```

Install Drupal instance :

make drupal-si

Or specify name of configuration instance

make drupal-si my_configuration_name

All of configuration available are defined in your settings/settings.local.php file from

# Config directories
$config_directories = array(
  my_configuration_name => '/absolute/path/to/config'
);

Example of typical workflow with configuration

# Config directories
$config_directories = array(
  dev => getcwd() . '/../config/dev',
  preprod => getcwd() . '/../config/preprod',
  prod => getcwd() . '/../config/prod',
  stage => getcwd() . '/../config/stage',
);

Open your favorite browser :
- http://localhost:8000 (Web Front).
- https://localhost:3000 (Web Front HTTPS).
- http://localhost:8080 PHPMyAdmin (username: dev, password: dev)
Stop and clear services :
```
sudo docker-compose down -v
```
Stop and delete all traces of changes from skeleton :
```
sudo make docker-stop
```
That delete all files to reset skeleton at his initial state.

Play with Drupal Configuration workflow

Export your current configuration instance

make drupal-config-export

Or with Docker Compose

docker-compose exec -T php composer export-conf

After your first install of Drupal instance edit the .env file and change the following variable DRUPAL_INSTALL_PROFILE=standard to DRUPAL_INSTALL_PROFILE=config_installer. That take ability to re-install / update your drupal instance with ./config/* exported configuration states.
Re-install or update your instance from exported configuration

Re-install: With Drop of current drupal database and complete re-import of ./config sh make drupal-si

Update: With following drupal commands (up-db / ent-up ).

Every action processed by scripts switch your Drupal instance on maintenance mode and switch Online after every action automatically.
```
make drupal-update
```

In more advanced usage you can also specified a drupal configuration name

make drupal-si preprod || make drupal-update preprod

Or with Docker Compose

docker-compose exec -T php composer site-install preprod || docker-compose exec -T php composer site-update preprod

Examples of life cycle

Start the Project containers :
```
sudo make docker-start
```
Edit .env file.
Install drupal 8 instance :
```
sudo make docker-si
```

Exporting Drupal configuration files :

 ```sh
 make drupal-config-export
 ```
 **Or with a specific destination**
 ```sh
 make drupal-config-export my_configuration_name
 ```

Enable Re-install from configuration mode : Edit .env file by changing DRUPAL_INSTALL_PROFILE=standard to DRUPAL_INSTALL_PROFILE=config_installer.
Re-installation of project from exported configuration : sh make drupal-si
Update of current instance : Edit one of configuration yml in your /config folder eg: system.site.site_name. and process to updating your drupal instance from configuration by using
```
 ```sh
 make drupal-update
 ```
```
Your Site Name will change that you specified in system.site.site_name yml file.
Another tips ? Call Help ;) : Show help :
```
make help
```

Use Makefile

When developing, you can use Makefile for doing the following operations :

Name	Description
code-sniff	Check the API with PHP Code Sniffer (Drupal Standards).
clean	Clean directories for reset.
c-install	Install PHP/Drupal dependencies with composer.
c-update	Update PHP/Drupal dependencies with composer.
clean-drupal-config	Delete exported configuration from project.
docker-start	Create and start containers.
docker-stop	Stop and clear all services.
gen-certs	Generate SSL certificates.
logs	Follow log output
mysql-dump	Create backup of all databases
mysql-restore	Restore backup of all databases
test	Test all application (custom and contribution modules).
test-contrib	Test application with phpunit
test-custom-modules	Test Drupal custom modules.
drupal-si	Install new Drupal instance and drop database.
drupal-update	Update your current Drupal instance and (re)import your `/config` exported configuration.
drupal-config-export	Export your current Drupal instance from `/config` by default. That can be in sub-folder depend your custom changes.

Use Docker commands

Installing package with composer

docker-compose exec -T php composer install

Requiring package with composer

docker-compose exec -T php composer require drupal/core

Updating PHP dependencies with composer

docker-compose exec -T php composer update

Testing PHP application with PHPUnit

docker-compose exec -T php bin/phpunit -c ./web/core ./web

Fixing standard code with CODER

docker-compose exec -T php composer phpcs ./web/modules/ or specify more specific path.

Checking the standard code with CODER

sudo docker-compose exec -T php ./app/vendor/bin/phpcs -v --standard=PSR2 ./app/src

Checking installed PHP extensions

sudo docker-compose exec php php -m

Handling database

MySQL shell access

sudo docker exec -it mysql bash

and

mysql -u"$MYSQL_ROOT_USER" -p"$MYSQL_ROOT_PASSWORD"

Creating a backup of all databases

mkdir -p data/db/dumps

source .env && sudo docker exec $(sudo docker-compose ps -q mysqldb) mysqldump --all-databases -u"$MYSQL_ROOT_USER" -p"$MYSQL_ROOT_PASSWORD" > "data/db/dumps/db.sql"

Restoring a backup of all databases

source .env && sudo docker exec -i $(sudo docker-compose ps -q mysqldb) mysql -u"$MYSQL_ROOT_USER" -p"$MYSQL_ROOT_PASSWORD" < "data/db/dumps/db.sql"

Creating a backup of single database

Notice: Replace "YOUR_DB_NAME" by your custom name.

source .env && sudo docker exec $(sudo docker-compose ps -q mysqldb) mysqldump -u"$MYSQL_ROOT_USER" -p"$MYSQL_ROOT_PASSWORD" --databases YOUR_DB_NAME > "data/db/dumps/YOUR_DB_NAME_dump.sql"

Restoring a backup of single database

source .env && sudo docker exec -i $(sudo docker-compose ps -q mysqldb) mysql -u"$MYSQL_ROOT_USER" -p"$MYSQL_ROOT_PASSWORD" < "data/db/dumps/YOUR_DB_NAME_dump.sql"

Connecting MySQL from PDO

<?php
    try {
        $dsn = 'mysql:host=mysql;dbname=test;charset=utf8;port=3306';
        $pdo = new PDO($dsn, 'dev', 'dev');
    } catch (PDOException $e) {
        echo $e->getMessage();
    }
?>

Or using Drush to check if your database configuration is OK

    docker-compose exec -T php bin/drush --root="/var/www/html/web" sql-connect

Help us

Any thought, feedback or (hopefully not!)

woprrr / drupal8-composer-template

Maintainers

Details