lakedrops / docker4drupal
Composer Plugin to prepare local Drupal development environment for Docker.
Requires
- php: >=8.1
- composer-plugin-api: ^2
- ext-json: *
- henrywhitaker3/healthchecks-io: ^1.0
- lakedrops/ahoy: ^1.8||dev-develop
- lakedrops/composer-json-utils: ^2.5||dev-develop
- lakedrops/docker-traefik: ^3.3||dev-develop
Requires (Dev)
- composer/composer: ^2
- lakedrops/drupal-environment: ^3.2||dev-develop
- roave/security-advisories: dev-latest
- dev-main
- v3.10.35
- v3.10.34
- v3.10.33
- v3.10.32
- v3.10.31
- v3.10.30
- v3.10.29
- v3.10.28
- v3.10.27
- v3.10.26
- v3.10.25
- v3.10.24
- v3.10.23
- v3.10.22
- v3.10.21
- v3.10.20
- v3.10.19
- v3.10.18
- v3.10.17
- v3.10.16
- v3.10.15
- v3.10.14
- v3.10.13
- v3.10.12
- v3.10.11
- v3.10.10
- v3.10.9
- v3.10.8
- v3.10.7
- v3.10.6
- v3.10.5
- v3.10.4
- v3.10.3
- v3.10.2
- v3.10.1
- v3.10.0
- v3.9.19
- v3.9.18
- v3.9.17
- v3.9.16
- v3.9.15
- v3.9.14
- v3.9.13
- v3.9.12
- v3.9.11
- v3.9.10
- v3.9.9
- v3.9.8
- v3.9.7
- v3.9.6
- v3.9.5
- v3.9.4
- v3.9.3
- v3.9.2
- v3.9.1
- v3.9.0
- v3.8.12
- v3.8.11
- v3.8.10
- v3.8.9
- v3.8.8
- v3.8.7
- v3.8.6
- v3.8.5
- v3.8.4
- v3.8.3
- v3.8.2
- v3.8.1
- v3.8.0
- v3.7.60
- v3.7.59
- v3.7.58
- v3.7.57
- v3.7.56
- v3.7.55
- v3.7.54
- v3.7.53
- v3.7.52
- v3.7.51
- v3.7.50
- v3.7.49
- v3.7.48
- v3.7.47
- v3.7.46
- v3.7.45
- v3.7.44
- v3.7.43
- v3.7.42
- v3.7.41
- v3.7.40
- v3.7.39
- v3.7.38
- v3.7.37
- v3.7.36
- v3.7.35
- v3.7.34
- v3.7.33
- v3.7.32
- v3.7.31
- v3.7.30
- v3.7.29
- v3.7.28
- v3.7.27
- v3.7.26
- v3.7.25
- v3.7.24
- v3.7.23
- v3.7.22
- v3.7.21
- v3.7.20
- v3.7.19
- v3.7.18
- v3.7.17
- v3.7.16
- v3.7.15
- v3.7.14
- v3.7.13
- v3.7.12
- v3.7.11
- v3.7.10
- v3.7.9
- v3.7.8
- v3.7.7
- v3.7.6
- v3.7.5
- v3.7.4
- v3.7.3
- v3.7.2
- v3.7.1
- v3.7.0
- v3.6.7
- v3.6.6
- v3.6.5
- v3.6.4
- v3.6.3
- v3.6.2
- v3.6.1
- v3.6.0
- v3.5.7
- v3.5.6
- v3.5.5
- v3.5.4
- v3.5.3
- v3.5.2
- v3.5.1
- v3.5.0
- v3.4.1
- v3.4.0
- v3.3.11
- v3.3.10
- v3.3.9
- v3.3.8
- v3.3.7
- v3.3.6
- v3.3.5
- v3.3.4
- v3.3.3
- v3.3.2
- v3.3.1
- v3.3.0
- v3.2.5
- v3.2.4
- v3.2.3
- v3.2.2
- v3.2.1
- v3.2.0
- v3.1.6
- v3.1.5
- v3.1.4
- v3.1.3
- v3.1.2
- v3.1.1
- v3.1.0
- v3.0.4
- v3.0.3
- v3.0.2
- v3.0.1
- v3.0.0
- v2.1.0
- v2.0.2
- v2.0.1
- v2.0.0
- v1.17.0
- v1.16.2
- v1.16.1
- v1.16.0
- v1.15.1
- v1.15.0
- v1.14.0
- v1.13.2
- v1.13.1
- v1.13.0
- v1.12.2
- v1.12.1
- v1.12.0
- v1.11.7
- v1.11.6
- v1.11.5
- v1.11.4
- v1.11.3
- v1.11.2
- v1.11.1
- v1.11.0
- v1.10.3
- v1.10.2
- v1.10.1
- v1.10.0
- v1.9.9
- v1.9.8
- v1.9.7
- v1.9.6
- v1.9.5
- v1.9.4
- v1.9.3
- v1.9.2
- v1.9.1
- v1.9.0
- v1.8.8
- v1.8.7
- v1.8.6
- v1.8.5
- v1.8.4
- v1.8.3
- v1.8.2
- v1.8.1
- v1.8.0
- v1.7.0
- v1.6.1
- v1.6.0
- v1.5.0
- v1.4.2
- v1.4.1
- v1.4.0
- v1.3.0
- v1.2.2
- v1.2.1
- v1.2.0
- v1.1.3
- v1.1.2
- v1.1.1
- v1.1.0
- v1.0.1
- 1.0.0
- v0.9.0
- v0.8.7
- v0.8.6
- v0.8.5
- v0.8.4
- v0.8.3
- v0.8.2
- v0.8.1
- v0.8.0
- v0.7.3
- v0.7.2
- v0.7.1
- v0.7.0
- v0.6.0
- v0.5.0
- v0.4.2
- v0.4.1
- v0.4.0
- v0.3.1
- v0.3.0
- v0.2.8
- v0.2.7
- v0.2.6
- v0.2.5
- v0.2.4
- v0.2.3
- v0.2.2
- v0.2.1
- v0.2.0
- v0.1.4
- v0.1.3
- v0.1.2
- v0.1.1
- v0.1.0
- dev-develop
- dev-nginx/custom-preset
- dev-issue-60/solr-mount-volume
- dev-issue-60/solr
- dev-issue-59
This package is auto-updated.
Last update: 2024-11-08 10:42:07 UTC
README
This composer plugin prepares your local development environment for Docker using the framework from Docker4Drupal by Wodby.
Requirements
This plugin is best used inside of L3D where no further requirements need to be met.
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 either D8 Project Template or D9 Project Template, this docker4drupal plugin will be installed automatically as a dependency of the Drupal Development Environment.
In all other cases, simply install it by typing
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 service in the
~/.traefik
directory which serves as a proxy for any number of parallel running Docker4Drupal projects. This service is provided by the LakeDrops Traefik Library. - 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) .lakedrops.yml
in your projects root like this:
docker4drupal:
webroot: relative/path/to/drupal/core
After that you can call
composer require lakedrops/docker4drupal
and everything will be configured for you.
Usage
All the commands need to be called from the root of your main Drupal project.
Updating Docker-Compose configuration
# With Ahoy
ahoy update
# Directly
composer lakedrops:docker4drupal
Starting the Docker containers
# With Ahoy
ahoy up
# Directly
docker-compose up -d
Stopping the Docker containers
# With Ahoy
ahoy stop
# Directly
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:
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 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. When you're using the L3D framework, simply call drush
in your L3D container and everything else happens magically in the background.
# 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:
drush 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:
# 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.
Customization
To overwrite the default settings for the Docker environment, add the relevant parts from this array to your .lakedrops.yml
file in the root of your project:
docker4drupal:
projectname: [NAME OF CURRENT DIRECTORY]
ci_home: /home/gitlab-runner
docker0:
ip: [IP OF YOUR DOCKER HOST]
proxy: [IP OF TRAEFIK PROXY]
traefik:
domain: docker.localhost
usessl: 0
port: 8000
ports: 8443
cert: fullchain.pem
key: privkey.pem
live:
root: ''
uri: ''
host: ''
user: ''
drush:
sql:
tables:
structure:
- cache
- cache_*
- history
- search_*
- sessions
- watchdog
skip:
- migration_*
drupal:
version: 9
php:
version: '7.4'
xdebug: 1
webserver:
type: apache
varnish:
enable: 0
redis:
version: '6'
dbbrowser:
type: pma
solr:
enable: 0
version: '4.8.0'
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
Once you've changed those values, run ahoy update
(or composer lakedrops:docker4drupal
) and the environment will be re-configured. The next time you start your Docker environment those new values will be used.
Adding new Docker services or enhancing existing ones
You can add more details to you .lakedrops.yml
configuration to create additional Docker services or enhance existing ones:
docker4drupal:
docker-compose.yml:
services:
php:
environment:
MY_VAR: value
mariadbd6:
image: wodby/mariadb:10.5
environment:
MYSQL_ROOT_PASSWORD: password
MYSQL_DATABASE: drupal
MYSQL_USER: drupal
MYSQL_PASSWORD: drupal
mycustomservice:
image: mydomain/myimage
This will add another environment variable to the php container, define a second mariadb container named mariadbd6
which may be used e.g. for a migration from a separate database and also a custom service with your own image and configuration.
Please remember to update docker compose with ahoy update
and then recreate your containers with ahoy up
after changing these settings.
More configuration tweaks
Customizing the apache config
docker4drupal:
webserver:
overwriteconfig: 1
With this setting you get the apache container to include the file ./apache/vhost.conf
relative to your project root when loading up.
Adding more domain names to be routed to your apache container
docker4drupal:
extradomains:
- domain1.example.com
- domain2.example.com
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.
Working with wkhtmltox
When using the Drupal module print
then go to admin/config/user-interface/print/pdf/wkhtmltopdf
and remove the options --footer-font-size 7 --footer-right '[page]'
because they don't work in the unpatched QT version.
Links
For more details we recommend the following links:
- Docker Engine
- Docker Composer
- Docker4Drupal