README.md

# Docker for Drupal Development

This is a composer plugin which prepares your local development environment for Docker using the framework from [Docker4Drupal](https://github.com/wodby/docker4drupal) by [Wodby](https://wodby.com).

## Requirements

Your development workstation needs to be prepared once, so that Docker and its components are available for all of your future projects. The instructions here have been tested on Ubuntu 16.04:

- [Install Docker Engine](https://docs.docker.com/engine/installation)

  ```bash
  sudo apt-get install docker-engine
  ```

- [Install Docker Compose](https://docs.docker.com/compose/install/)

  ```bash
  sudo pip install docker-compose
  ```

- [Install Git Extras](https://github.com/tj/git-extras/blob/master/Installation.md)

  ```bash
  sudo apt-get install git-extras
  ```

- Name the group and add your user to it

  ```bash
  sudo groupadd -r -g 82 www-docker
  sudo usermod -a -G www-docker $(id -un)
  sudo usermod -a -G docker $(id -un)
  # logout and re-login again to make these changes effective
  ```

## Installation in your Drupal project

This is a composer plugin. It can be used both in composer based Drupal installations and also vanilla Drupal without composer.

If you're using the latest version of the [D8 Project Template](https://gitlab.lakedrops.com/lakedrops/d8-project), this docker4drupal plugin will be installed automatically as a dependency of the [Composer Plugin for Drupal 8 Project Template](https://gitlab.lakedrops.com/lakedrops/d8-project-scaffold).

In all other cases, simply install it by typing

```bash
composer require lakedrops/docker4drupal
```

This will install and configure all required files so that you can launch your Docker environment straight away without any additional settings. The actions being taken:

- Create and configure **docker-compose.yml** in your project root
- Create and configure **settings.docker.php** in your settings directory
- Modify your **settings.php** to load **settings.docker.php** if available
- Create Drush settings, aliases and shell-aliases in a `drush` subdirectory of the current directory
- Configure and (re)start a single Docker [Traefik](https://docs.traefik.io) service in the `~/.traefik` directory which serves as a proxy for any number of parallel running Docker4Drupal projects
- Add those new files to **.gitignore** as you usually don't want them to be committed

### Installation in a vanilla Drupal project

Before you get started you should create (or add to an existing) composer.json like this:

```json
{
    "extra": {
        "docker4drupal": {
            "webroot": "relative/path/to/drupal/core"
        }
    }
}
```

After that you can call

```bash
composer require lakedrops/docker4drupal
```

and everything will be configured for you.

## Usage

### Starting the Docker containers

```bash
cd /path/of/project/root
docker-compose up -d
```

### Stopping the Docker containers

```bash
cd /path/of/project/root
docker-compose stop
```

### Access the services

The following services are available in your browser while the Docker containers are up and running:

- Dashboard: http://docker.localhost:8080
- Drupal site: http://[PROJECTNAME].docker.localhost:8000
- PhpMyAdmin: http://pma.[PROJECTNAME].docker.localhost:8000
- Mailhog	http://mailhog.[PROJECTNAME].docker.localhost:8000
- Solr	http://solr.[PROJECTNAME].docker.localhost:8000
- Node	http://front.[PROJECTNAME].docker.localhost:8000
- Varnish	http://varnish.[PROJECTNAME].docker.localhost:8000

Note that Solr, Node and Varnish are not enabled by default. See the customization chapter below to learn how you can enable them.

### PHP Debugging

By default, PHP is configured with XDebug being enabled and you should check the instructions for your IDE on how to get started with a debugging session.

### Watch the logs

Each service (nginx, php, db, etc.) provides their own logs and it is very easy to access them:

```bash
docker-compose logs -f [SERVICENAME]
```

Each service has their own name:

- mailhog
- mariadb
- nginx
- node
- php
- pma
- redis
- solr
- varnish

### Configure SSH access to your live site

By default, you do **not** have to configure SSH access to your live site. However, if you want to pull the database and/or files from the live site, SSH access comes in pretty handy and the next chapter about Drush will show you how to make use of it.

For the configuration of the access, you need to do two things:

#### Configure your Drush alias

In your project root on your host you'll find a `drush` subdirectory with a file called `aliases.drushrc.php` with a `dev` and a `live` alias. THe first one is configured automatically and the second is empty by default. You have to provide the details manually:

- **root**: the full path to the Drupal root directory on the remote host
- **uri**: the domain and optional base path of the live website
- **remote-host**: a valid host name or IP address of that remote host - if you're in doubt, use the domain name from the **uri** above
- **remote-user**: the username under which you can access the remote host over SSH

There are potentially more options possible, for details please refer to the Drush documentation on this.

#### Configure SSH access from the PHP container

This feature is only available if SSH agent forwarding is enabled on your host. There is a [good tutorial](https://developer.github.com/v3/guides/using-ssh-agent-forwarding/#your-local-ssh-agent-must-be-running) available if you need any help.

Your host SSH configuration is automatically forwarded to the PHP docker container using sockets and you don't have to do anything to make it work, as long as your host is configured correctly to access your live site via SSH - in this case the PHP container can too. This works by mounting and forwarding your `SSH_AUTH_SOCK` environment variable to `/ssh-agent` inside the PHP container, so that the user inside that container can utilize your SSH settings like your user outside the contain who built them.

Typical issues that may cause trouble in this context are:

- **Permission**: the user inside the container has to have the permission to access your SSH auth socket. The best way to ensure that is to run services inside the container as root. This should be OK in a development environment.
- **SSH key should be added to the socket**: Very often, that has already been done at some point during setup of your environment but if not, you should remember to add your key by calling `ssh-add /path/to/your/key` from the host.

### Using Drush

This plugin configures Drush with several settings, aliases and shell-aliases that make your developer life much easier. You can either enter the PHP container and execute Drush there or you can call every Drush command from your host:

```bash
# Entering PHP Container
docker-compose exec php sh
# Call Drush command
drush site-aliases

# ...or, call that command from your host:
docker-compose exec php drush site-aliases
```

Even better, you can create shell aliases (see below) for your host's shell which will make that even easier:

```bash
cdrush site-aliases
```

If you have configured SSH access to your live site (see above) then you can easily pull the database and/or the files from your live site into your development environment easily:

```bash
# Pull the database
drush pull-sql

# Pull the files
drush pull-files

# Pull both
drush pull-all
```

### Further reading

What else can be done with the Docker environment is best described in the [Docker4Drupal Documentation](http://docs.docker4drupal.org/en/latest/).

## Customization

To overwrite the default settings for the Docker environment, add the relevant parts from this array to your composer.json file in the root of your project:

```json
{
  "extra": {
    "docker4drupal": {
      "projectname": "[NAME OF CURRENT DIRECTORY]",
      "live": {
        "root": "",
        "uri": "",
        "host": "",
        "user": ""
      },
      "drush": {
        "sql": {
          "tables": {
            "structure": ["cache", "cache_*", "history", "search_*", "sessions", "watchdog"],
            "skip": ["migration_*"]
          }
        }
      },
      "drupal": {
        "version": 8
      },
      "php": {
        "version": "7.0",
        "xdebug": 1
      },
      "webserver": {
        "type": "apache"
      },
      "varnish": {
        "enable": 0
      },
      "redis": {
        "version": "4.0"
      },
      "dbbrowser": {
        "type": "pma"
      },
      "solr": {
        "enable": 0,
        "version": "6.6"
      },
      "node": {
        "enable": 0,
        "key": "",
        "path": ""
      },
      "memcached": {
        "enable": 0
      },
      "rsyslog": {
        "enable": 0
      },
      "athenapdf": {
        "enable": 0,
        "key": ""
      },
      "blackfire": {
        "enable": 0,
        "id": "",
        "token": ""
      },
      "webgrind": {
        "enable": 0
      },
      "wkhtmltox": {
        "enable": 0
      }
    }
  }
}
```

Other supported values for the PHP version are `5.3`, `5.6` and `7.1`.

Other supported value for the webserver type is `nginx`.

Supported versions for `nginx`: `1.15`, `1.14`, `1.13`. 

Other supported value for the Redis version is `3.2`.

Other supported value for the dbbrowser type is `adminer`. In that case you should also add a version element with either `4.6`, `4.3` or `4.2`.

Other supported values for the Solr version are `6.5`, `6.4`, `6.3`, `5.5` and `5.4`.

Once you've changed those values, run `composer update` and the environment will be re-configured. The next time you start your Docker environment those new values will be used.

### Individually updating docker4drupal

You can add this to your composer.json:

```json
{
    "scripts": {
        "d4d": "LakeDrops\\Docker4Drupal\\Plugin::config"
    }
}
```

That allows you to simply call the following command to only update docker4drupal settings:

```bash
composer d4d
``` 

Note, that docker4drupal configuration **does overwrite** existing setting files when you run this script.

Therefore, you can add custom content to the settings files by adding another key to the `extra/docker4drupal` section with the file name as the key and additional settings underneath. Example: 

```json
{
  "extra": {
    "docker4drupal": {
      "docker-compose.yml": {
        "services": {
          "php": {
            "environment": {
              "MY_VAR": "value"
            }
          },
          "mariadbd6": {
            "image": "wodby/mariadb:10.1",
            "environment": {
              "MYSQL_ROOT_PASSWORD": "password",
              "MYSQL_DATABASE": "drupal",
              "MYSQL_USER": "drupal",
              "MYSQL_PASSWORD": "drupal"
            }
          }
        }
      }
    }
  }
}
```

This will add another environment variable to the php container and define a second mariadb container named `mariadbd6` which may be used e.g. for a migration from a separate database.

## Tipps & Tricks

### Some notes about localhost subdomains

The domain `localhost` is always defined to be resolved by the IP address 127.0.0.1 which is exactly what we need to work with local installations like this. Using subdomains of localhost to tell Docker and Traefik which of the containers to route the requests to, is what makes this environment really powerful. So, you can use `http://project1.docker.localhost:8000` for the development website and `http://pma.project1.docker.localhost:8000` for the PhpMyAdmin portal of that site which is served by a different service in a different container.

There is some debate whether such subdomains are legitimate or not and Chrome/Google is of the opinion that it is perfectly OK and according to the RFA which defines that stuff. That means, all this works just fine in Chrome. Unfortunately, Firefox/Mozilla has not implemented that standard (yet) and hence it won't work in that browser without tweaking your local hosts file. Should you want to use Firefox, add a line `127.0.0.1 project1.docker.localhost pma.project1.docker.localhost ...` to your `/etc/hosts` file on your host with a space limited list of all possible domains you're going to use.

### Running multiple sites in parallel

This plugin configures the Docker containers such that any number of them can be launched in parallel. And as each of them get individual project names which will then be part of the domain name(s), you can use them all at the same time. To make this possible, a separat Docker service container will be created and launched, which operates as a proxy to route your local traffic to the always correct docker container with the correct development website.

### Defining shell aliases on your host

When you're using `docker-compose` a lot, you'll get tired quickly by typing such long commands over and over again. To simplify your shel life here even more, we recommend to define a number of shell aliases. How to do that depends on the shell you're using. For the famous Fish shell we would write the following lines in a file called `/etc/fish/conf.d/docker-compose.fish`:

```text
alias c "docker-compose"
alias cb "docker-compose build"
alias cup "docker-compose up -d"
alias cr "docker-compose run --service-ports --rm"
alias crl "docker-compose run --service-ports --rm local"
alias crd "docker-compose run --service-ports --rm develop"
alias crt "docker-compose run --rm test"
alias crp "docker-compose run --rm provision"
alias crci "docker-compose run --rm ci"
alias crwt "docker-compose run --rm watchtest"
alias cps "docker-compose ps"
alias clogs "docker-compose logs"
alias cstop "docker-compose stop"
alias cstart "docker-compose start"
alias cshell "docker-compose exec --user root php sh"
alias cdrush "docker-compose exec --user root php drush"
alias cdrush-pull "cdrush-pull-sql; and cdrush-pull-files"
alias cdrush-pull-sql "cdrush sql:sync --create-db @default.live @default.dev; and cdrush @default.dev cr; and cdrush @default.dev dev on"
alias cdrush-pull-files "cdrush rsync @default.live:%files/ @default.dev:%files -- --chown=www-data:www-data --safe-links --max-size=20M"
```

Do that once, it will pay back in a magnitude.

## Links

For more details we recommend the following links:

- Docker Engine
  - [Home](https://www.docker.com)
  - [Documentation](https://docs.docker.com/engine)
- Docker Composer
  - [Home](https://github.com/docker/compose)
  - [Documentation](https://docs.docker.com/compose)
- Docker4Drupal
  - [Home](https://github.com/wodby/docker4drupal)
  - [Documentation](https://wodby.com/stacks/drupal/docs/local)
  - [Wodby](https://wodby.com)