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
  ```

- 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)
  # logout and re-login again to make these changes effective
  ```

## Installation in your Drupal project

This is a composer plugin and therefore can be used in composer based Drupal installations only. 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
- Add those new files to **.gitignore** as you usually don't want them to be committed

## Usage

### Starting the Docker containers

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

### Stopping the Docker containers

```bash
cd /path/of/project/root
sudo 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://drupal.docker.localhost:8000
- PhpMyAdmin: http://pma.drupal.docker.localhost:8000
- Mailhog	http://mailhog.drupal.docker.localhost:8000
- Solr	http://solr.docker.localhost:8000
- Node	http://front.drupal.docker.localhost:8000
- Varnish	http://varnish.drupal.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
sudo docker logs [NAME] -f
```

Each service has their own container name and to get a list of all available name you should use `sudo coker ps`.
 
### Direct access to your database

Browser the database is always possible by using PhpMyAdmin, but sometimes you probably want to get access with other tools (e.g. from your IDE or Drush and others). This is preconfigured in the Docker containers and you should use these credentials:

```ini
[client]
host=127.0.0.1
port=8306
database=drupal
user=drupal
password=drupal
```

If you're using Drupal Console, just use `drupal database:connect` which will print the command with all parameters for you.

If you're using Drush, just use `drush sqlc` which will launch the MySQL client automatically with all the correct parameters.

### Using Drush and DrupalConsole

As already described in the previous section, all is configured for you so that you can use Drush and DrupalConsole from your host without any problems. It is able to connect to the database and therefore can execute all the commands in that context easily.

**Tipp:** To pull the live database into your development environment inside of Docker, just define the Drush aliases and test them with `drush @live status` and `drush @dev status`. If they respond with the correct details about your two sites, you can then pull the current database with this command:

```bash
drush -y --create-db sql-sync @live @dev
```

### 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": {
        "port": 8000,
        "drupal": {
          "version": 8
        },
        "php": {
          "version": "7.0",
          "xdebug": 1
        },
        "nginx": {
          "version": "1.10"
        },
        "varnish": {
          "enable": 0
        },
        "solr": {
          "enable": 0
        },
        "node": {
          "enable": 0
        }
    }
  }
}
```

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

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.

## Tipps & Tricks

### Running multiple sites in parallel

If you have to run multiple sites at once, make sure that each of them is configured with an individual port in your composer.json file before you run composer update and re-launch your Docker environment. This will make them available on the given ports and you have to use the correct ports for each of the sites in the URLs when browsing to them.

## 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](http://docs.docker4drupal.org/en/latest)
  - [Wodby](https://wodby.com)