@@ -42,6 +42,8 @@ This will install and configure all required files so that you can launch your D
- 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
## Usage
...
...
@@ -65,12 +67,12 @@ docker-compose stop
The following services are available in your browser while the Docker containers are up and running:
Note that Solr, Node and Varnish are not enabled by default. See the customization chapter below to learn how you can enable them.
...
...
@@ -83,36 +85,83 @@ By default, PHP is configured with XDebug being enabled and you should check the
Each service (nginx, php, db, etc.) provides their own logs and it is very easy to access them:
```bash
docker logs [NAME]-f
docker-compose logs -f[SERVICENAME]
```
Each service has their own container name and to get a list of all available name you should use `docker ps`.
### Direct access to your database
Each service has their own name:
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:
- mailhog
- mariadb
- nginx
- node
- php
- pma
- redis
- solr
- varnish
```ini
[client]
host=127.0.0.1
port=8306
database=drupal
user=drupal
password=drupal
### 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
If you SSH access to the remote host is protected by a public/private key pair, then you have to configure you Docker container to be able to access the remote host. Here are the steps you need to take:
If you're using Drupal Console, just use `drupal database:connect` which will print the command with all parameters for you.
This will show you the just created public key on the console and you should copy that output and then once go to your remote host and add that key to the end of the file `~/.ssh/authorized_keys`.
### 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
If you're using Drush, just use `drush sqlc` which will launch the MySQL client automatically with all the correct parameters.
# ...or, call that command from your host:
docker-compose exec php drush site-aliases
```
### Using Drush and DrupalConsole
Even better, you can create shell aliases (see below) for your host's shell which will make that even easier:
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.
```bash
cdrush site-aliases
```
**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:
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
drush -y--create-db sql-sync @live @dev
# Pull the database
drush pull-sql
# Pull the files
drush pull-files
# Pull both
drush pull-all
```
### Further reading
...
...
@@ -127,7 +176,7 @@ To overwrite the default settings for the Docker environment, add the relevant p
{
"extra":{
"docker4drupal":{
"port":8000,
"projectname":"[NAME OF CURRENT DIRECTORY]",
"drupal":{
"version":8
},
...
...
@@ -158,9 +207,32 @@ Once you've changed those values, run `composer update` and the environment will
## 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
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.
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`:
