Base template for Drupal projects hosted on Lagoon

Warning

This template is based on the NEXT major release of Drupal, currently Drupal 11, contains dev/alpha/beta releases and should not be used in production.

This template includes everything necessary to run on Lagoon (in both the local development environments or on hosted Lagoon clusters.)

This project template should provide a kickstart for managing your site dependencies with Composer. It is based on the original Drupal Composer Template,

Included Services

This example contains the following services:

• Drupal 11 (prerelease versions)
• PHP 8.3
• NGINX
• MariaDB 10.11

To see similar projects with additional services, please visit https://github.com/lagoon-examples and to find out more about the services, please visit the documentation at https://docs.lagoon.sh/lagoon

Requirements

• docker
• pygmy

OR

• Lando

Local environment setup - pygmy

1. Checkout this project repo and confirm the path is in Docker's file sharing config - https://docs.docker.com/docker-for-mac/#file-sharing

   git clone https://github.com/lagoon-examples/drupalnext-base.git drupalnext-base && cd $_

2. Make sure you don't have anything running on port 80 on the host machine (like a web server) then run pygmy up

3. Build and start the build images:

   docker compose up -d
   docker compose exec cli composer install

4. Visit the new site @ http://drupalnext-base.docker.amazee.io

• If any steps fail, you're safe to rerun from any point. Starting again from the beginning will just reconfirm the changes.

Local environment setup - Lando

This repository is set up with a .lando.yml file, which allows you to use Lando instead of pygmy for your local development environment.

1. Install Lando.

2. Checkout the project repo and confirm the path is in Docker's file sharing config - https://docs.docker.com/docker-for-mac/#file-sharing

   git clone https://github.com/lagoon-examples/drupalnext-base.git drupalnext-base && cd $_

3. Make sure you have pygmy-go stopped. Run pygmy stop to be sure.

4. We already have a Lando file in this repository, so we just need to run the following command to get Lando up:

lando start

5. Install your Drupal site with Drush:

lando drush si -y

6. Visit the new site @ http://drupalnext-base.lndo.site

7. For more information on how to configure your site, check out the documentation.

What does the template do?

When installing the given composer.json some tasks are taken care of:

• Drupal will be installed in the web-directory.
• Autoloader is implemented to use the generated composer autoloader in vendor/autoload.php, instead of the one provided by Drupal (web/vendor/autoload.php).
• Modules (packages of type drupal-module) will be placed in web/modules/contrib/
• Themes (packages of type drupal-theme) will be placed in web/themes/contrib/
• Profiles (packages of type drupal-profile) will be placed in web/profiles/contrib/
• Creates the web/sites/default/files-directory.
• Latest version of Drush is installed locally for use at vendor/bin/drush.
• Latest version of Drupal Console is installed locally for use at vendor/bin/drupal.
• The correct scaffolding for your Drupal core version is installed, along with Lagoon-specific scaffolding from amazeeio/drupal-integrations project and the assets/ directory in this repo. For more information see drupal/core-composer-scaffold

Updating Drupal Core

Follow the steps below to update your core files. Scaffolding is managed by Drupal core. See the assets/ directory for more information.

1. Run composer update drupal/core-recommended drupal/core-dev-pinned --with-dependencies

FAQ

Should I commit the contrib modules I download?

Composer recommends no. They provide argumentation against but also workarounds if a project decides to do it anyway.

How can I apply patches to downloaded modules?

If you need to apply patches (depending on the project being modified, a pull request is often a better solution), you can do so with the composer-patches plugin.

To add a patch to drupal module foobar insert the patches section in the extra section of composer.json:

"extra": {
    "patches": {
        "drupal/foobar": {
            "Patch description": "URL to patch"
        }
    }
}

What are the "TESTING" files in this repo?

These files are used by Github actions to run a basic suite of tests specific to this template. They utilise the excellent Leia tool to generate a set of mocha-compatible tests. Have a look through the markdown for both files, and you will see what they do. These tests can also be generated and run locally.