Skip to content

L3D and Drupal Projects

Introduction and overview

We do provide a couple of project templates for Drupal projects out of the box:

If you prefer to use your own prroject template, you'll get the most out of L3D if you add our ccomposer plugin drupal-development-environment to your required dev components:

1
composer require --dev lakedrops/drupal-development-environment

This comes with all the dependencies, that help you in local Drupal development:

You'll find the documentation for each of these tools in their own section.

In the current context, just an extra note on the drupal-environment plugin: this has been moved out of drupal-development-environment and contains all the tasks and templates to initially build the directory structure and setting files.

It is a great idea to utilize the same structure in your production environment too. To get there, you can simply add this plugin to your regular requirements:

1
composer require lakedrops/drupal-environment

In both cases, development and production, your project settings for this toolset goes into the file .lakedrops.yml in your project root and each project describes in its own documentation, what values go into this file so that you get similar (but not identical) setup on all stages. It should not be identical, because you don't want all the development tools on your production site.

Before starting with Drupal projects and L3D we recommend to create or edit an .env file in your user's home directory. For details see ~/.env

Those will be used as default values for all your projects, and you may adjust them towards your own needs. With those defaults in place, you will then get less questions when setting up new projects and the local .env file will then only contain those values that are different form your global default.

Working with multiple projects in parallel

The composer plugin Docker4Drupal in combination with the composer library Traefik automatically configures your host for zero-setup always working routing for any number of projects in parallel.

Everything is based on a project ID which has to be unique on a single host. Ideally the ID should be short and only contain characters and numbers. The ID will be part of the domain-name under which this project will be opened in the browser locally and maybe even within your LAN.

The ID will be stored in a variable called COMPOSE_PROJECT_NAME which is stored in the .env file in the root of your project. For this documentation we continue by using the sample ID project1.

Based on this ID, ...

  • L3D builds the main container called project1_l3d
  • Traefik creates a Docker network called traefik_project1
  • Docker4Drupal creates a number of containers depending on the services you require, e.g.
  • project1_apache_1
  • project1_mailpit_1
  • project1_mariadb_1
  • project1_php_1
  • project1_pma_1
  • project1_redis_1
  • Node and NPM will create a container project1_l3d_node

All those containers can communicate with each other as they all belong to the same logical network provided by Traefik. If you have a second and more projects with the same logic but a different ID, they will simply do the same for themselves and each project will be self-contained but isolated from all the other projects on the host.

Routing

The logical network for each project is also used for routing traffic, i.e. HTTP requests, from you host - or even from you LAN - to the right container for further processing. All of that routing is managed by Traefik which defaults to port 8000 for http and port 8443 for https traffic. You can change those ports to anything else by setting the following environment variables in the .env file in your users home directory:

1
2
DOCKER4DRUPAL_TRAEFIK_PORT=80
DOCKER4DRUPAL_TRAEFIK_PORTS=443

If you change those values later on, don't forget to run ahoy traefik rewrite to update existing services.

Routing also requires domain names. They help Traefik to decide which request needed to be routed into which container. Depending on the services you use, the following domain names will be used for the respective services:

  • project1.docker.localhost:8000: The Drupal website.
  • pma-project1.docker.localhost:8000: PhpMyAdmin of the project.
  • mailpit-project1.docker.localhost:8000: The Mailhog service for the project.
  • bs-project1.docker.localhost:8000: Browsersync instance when running Gulp.

In other words, the project ID plus some service identifier are used as the subdomain to your Traefik domain, which defaults to docker.localhost. You can overwrite that domain with the environment variable DOCKER4DRUPAL_TRAEFIK_DOMAIN, e.g. to username.company.dev with username being replaced by the name of the developer or their hostname.

In any event, make sure that your local DNS resolves all those domains properly to the correct host in your LAN. There are different tools around that let you do that, dnsmasq or Pi-hole are two possible tools that make it easy and are well documented.

This approach even allows your team to get access to active projects on their teammates hosts, if everything is setup accordingly, e.g.

Developer Hostname IP Domains
Lisa laptop12 192.168.1.45 *.laptop12.company.dev
Max desktopmax 192.168.1.83 *.desktopmax.company.dev
Sara laptop33 192.168.1.84 *.laptop33.company.dev
Manuel laptop01 192.168.1.87 *.laptop01.company.dev

If e.g. Lisa and Manuel are both working on project1, there will be two domains available in your LAN for that project:

  • project1.laptop12.company.dev: the current version on Lisa's laptop
  • project1.laptop01.company.dev: the current version on Manuel's laptop

Everyone in the LAN can access the current projects on all hosts of developers, if configured this way. Even for remote teams, this very same setup can be achieved over a VPN.

Working with SSL

For this documentation we work with the domain username.company.dev and this will be used as a wildcard domain, so that for each project you're working on, a sub-domain suffix will be added, e.g. shop.username.company.dev or customer14.username.company.dev.

To tell Docker, Traefik and L3D, that this domain should be used with SSL, add these environment variables to your ~/.env file:

1
2
3
4
DOCKER4DRUPAL_TRAEFIK_DOMAIN=username.company.dev
DOCKER4DRUPAL_TRAEFIK_USESSL=1
DOCKER4DRUPAL_TRAEFIK_PORT=80
DOCKER4DRUPAL_TRAEFIK_PORTS=443

Last but not least, your local DNS needs to be configured, so your browser knows, that *.username.company.dev can be found at 127.0.0.1. If you have a DNS resolver, that can handle wildcards, then that's what you should go for. If you don't have one, or if you don't know, then you need to edit /etc/hosts and add a line like this:

1
127.0.0.1 shop.username.company.dev customer14.username.company.dev

Unfortunately, for each new project you have to add the new domain to that list before the browser can find it.

Getting SSL certificates

This is the final component and there are 2 supported options: automatic or manual.

After one of the 2 methods got setup,go to one of your projects in L3D and call ahoy traefik rewrite to get everything setup once and forever.

Automatic

This is possible, if your domain registrar or DNS provider offers an API that LetsEncrypt can use. If not, then you have to gop for the manual approach below.

Define an A-record for *.username.company.dev with an IP address that probably points to the company website. Then, create an API token with the DNS provider and configure additional variables in ~/.env, here with an example for CloudFlare as the DNS provider:

1
2
3
4
5
DOCKER4DRUPAL_TRAEFIK_DNS_CHALLENGE=1
DOCKER4DRUPAL_TRAEFIK_DNS_CHALLENGE_PROVIDER=cloudflare
DOCKER4DRUPAL_TRAEFIK_DNS_CHALLENGE_RESOLVER=andy.ns.cloudflare.com:53,zoe.ns.cloudflare.com:53
DOCKER4DRUPAL_TRAEFIK_ENV_1=CF_DNS_API_TOKEN:...your token...
DOCKER4DRUPAL_TRAEFIK_ENV_2=0

With this configuration, Traefik will generate SSL certificates for all your projects automatically in the background.

Manual

For this you have to install a LetsEncrypt client. We recommend Certbot. Then you can issue a wildcard certificate with the following command:

1
2
3
certbot -d "*.username.company.dev" --server https://acme-v02.api.letsencrypt.org/directory --manual --preferred-challenges dns certonly
cp /etc/letsencrypt/live/username.company.dev/*.pem ~/.traefik/certs
sudo chmod +r ~/.traefik/certs/*.pem

You will be presented with a request to configure a TXT record on your DNS provider. Once you're done that, certbot will issue the SSL certificate for you and you're good to go. Note: you have to renew the certificate every 3 months by using the same commands again.

Add the following line to your .env file in your user's home directory:

1
2
DOCKER4DRUPAL_TRAEFIK_CERT=fullchain.pem
DOCKER4DRUPAL_TRAEFIK_KEY=privkey.pem

Note: every 2 months you will have to renew the SSL cert with LetsEncrypt by calling certbot renew and then copying the new cert files into the same directory ad described above and then restart Traefik.

Using MailPit

When using the Docker4Drupal, a MailPit service will be configured automatically by default. This captures all outgoing email so that you can view those emails in a dashboard from your browser. Should you want to release an email to see how it looks in you email client, MailPit provides a button to do that. This requires SMTP server configuration, that you can provide in your local .env files like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
MAILPIT_HOST=smtp.freesmtpservers.com
MAILPIT_PORT=25
MAILPIT_USERNAME=
MAILPIT_PASSWORD=
MAILPIT_STARTTLS=
MAILPIT_ALLOW_INSECURE=
MAILPIT_AUTH=none
MAILPIT_SECRET=
MAILPIT_RETURNPATH=
MAILPIT_RECIPIENT_ALLOW_LIST=

For more details about those parameters, please refer to SMTP relay configuration.

Using MailHog

When using the Docker4Drupal, a MailHog service can be configured. This captures all outgoing email so that you can view those emails in a dashboard from your browser. Should you want to release an email to see how it looks in you email client, MailHog provides a button to do that. This requires SMTP server configuration, that you can provide in your local .env files like this:

1
2
3
4
5
MAILHOG_HOST=smtp.freesmtpservers.com
MAILHOG_PORT=25
MAILHOG_USERNAME=
MAILHOG_PASSWORD=
MAILHOG_MECHANISM=NONE