Drupal 10

Wondering how to configure Tugboat for a typical Drupal 10 repository? Every Drupal site tends to have slightly different requirements, so you may need to do more customizing, but this should get you started.

The following documentation assumes you are using Composer to manage your Drupal 10 project (typically with either the drupal/recommended-project or the drupal-composer/drupal-project projects).

Configure Drupal

A common practice for managing Drupal’s settings.php is to leave sensitive information, such as database credentials, out of it and commit it to git. Then, the sensitive information is loaded from a settings.local.php file that exists only on the Drupal installation location.

This pattern works very well with Tugboat. It lets you keep a Tugboat-specific set of configurations in your repository, where you can copy it into place with a configuration file command.

Add or uncomment the following at the end of settings.php

1if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
2  include $app_root . '/' . $site_path . '/settings.local.php';
3}

Add a file to the git repository at .tugboat/settings.local.php with the following content:

 1<?php
 2$databases['default']['default'] = array (
 3  'database' => 'tugboat',
 4  'username' => 'tugboat',
 5  'password' => 'tugboat',
 6  'prefix' => '',
 7  'host' => 'database',
 8  'port' => '3306',
 9  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
10  'driver' => 'mysql',
11);
12
13// Use the TUGBOAT_REPO_ID to generate a hash salt for Tugboat sites.
14$settings['hash_salt'] = hash('sha256', getenv('TUGBOAT_REPO_ID'));
15
16// If your Drupal config directory is outside of the Drupal web root, it's
17// recommended to uncomment and adapt the following. Note: the TUGBOAT_ROOT
18// environment variable is equivalent to the git repo root.
19# $settings['config_sync_directory'] = getenv('TUGBOAT_ROOT') . '/config';
20
21// If you are using private files, and that directory is outside of the Drupal
22// web root, it's recommended to uncomment and adapt the following. Note: the
23// TUGBOAT_ROOT environment variable is equivalent to the git repo root.
24# $settings['file_private_path'] = getenv('TUGBOAT_ROOT') . '/files-private';
25
26// Prevent Drupal from making the sites/default directory unwritable.
27$settings['skip_permissions_hardening'] = TRUE;
28
29/**
30 * Trusted host configuration for Tugboat preview environments.
31 *
32 * Drupal requires you to specify which hostnames are allowed to access your
33 * site. Since Tugboat preview URLs use the tugboatqa.com domain, we add this
34 * pattern to allow Drupal to accept requests from any Tugboat preview URL.
35 *
36 * @see https://www.drupal.org/docs/installing-drupal/trusted-host-settings
37 */
38$settings['trusted_host_patterns'] = [
39  '\.tugboatqa\.com$',
40];
41
42/**
43 * Set the memory limit for the CLI.
44 */
45if (PHP_SAPI === 'cli') {
46  ini_set('memory_limit', '-1');
47}

Configure Tugboat

The Tugboat configuration is managed by a YAML file at .tugboat/config.yml in the git repository. Here’s a basic Drupal 10 configuration you can use as a starting point, with comments to explain what’s going on:

  1# Default Drupal 10 Tugboat starter config.
  2# https://docs.tugboatqa.com/starter-configs/tutorials/drupal-10/
  3services:
  4  # Define the database service.
  5  database:
  6    # Use the latest available 5.x version of MySQL
  7    image: tugboatqa/mariadb:10.5
  8
  9    # A set of commands to run while building this service
 10    commands:
 11      # Configure the server for the site to run on.
 12      init:
 13        # Increase the allowed packet size to 512MB.
 14        - mysql -e "SET GLOBAL max_allowed_packet=536870912;"
 15        # Ensure this packet size persists even if MySQL restarts.
 16        - echo "max_allowed_packet=536870912" >> /etc/mysql/conf.d/tugboat.cnf
 17
 18      # Commands that import files, databases,  or other assets. When an
 19      # existing preview is refreshed, the build workflow starts here,
 20      # skipping the init step, because the results of that step will
 21      # already be present.
 22      update:
 23        # TODO: Copy a database dump from an external server. The public
 24        # SSH key found in the Tugboat Repository configuration must be
 25        # copied to the external server in order to use scp.
 26        - scp user@example.com:database.sql.gz /tmp/database.sql.gz
 27        - zcat /tmp/database.sql.gz | mysql tugboat
 28        - rm /tmp/database.sql.gz
 29
 30      # Run any commands needed to prepare the site.  This is generally not needed
 31      # for database services.
 32      build: []
 33
 34  # Define the webserver service.
 35  webserver:
 36    # This uses PHP 8.1.x with Apache: update to match your version of PHP.
 37    image: tugboatqa/php:8.1-apache
 38
 39    # Set this as the default service. This does a few things
 40    #   1. Clones the git repository into the service container
 41    #   2. Exposes port 80 to the Tugboat HTTP proxy
 42    #   3. Routes requests to the preview URL to this service
 43    default: true
 44
 45    # Wait until the mysql service is done building.
 46    depends: database
 47
 48    # A set of commands to run while building this service
 49    commands:
 50      # The INIT command configures the webserver.
 51      init:
 52        # Install opcache and mod-rewrite.
 53        - docker-php-ext-install opcache
 54        - a2enmod headers rewrite
 55
 56        # Link the document root to the expected path. This example links /web
 57        # to the docroot.
 58        - ln -snf "${TUGBOAT_ROOT}/web" "${DOCROOT}"
 59
 60        # Create any required directories that don't exist.
 61        # - mkdir -p "${TUGBOAT_ROOT}/files-private"
 62
 63      # Commands that import files, databases,  or other assets. When an
 64      # existing preview is refreshed, the build workflow starts here,
 65      # skipping the init step, because the results of that step will
 66      # already be present.
 67      update:
 68        # Install/update packages managed by composer.
 69        - composer install --optimize-autoloader
 70
 71        # Set the tugboat-specific Drupal settings.
 72        - cp "${TUGBOAT_ROOT}/.tugboat/settings.local.php" "${DOCROOT}/sites/default/settings.local.php"
 73
 74        # Map your custom modules and themes into the Drupal structure.
 75        #- ln -snf "${TUGBOAT_ROOT}/custom/themes" "${DOCROOT}/themes/custom"
 76        #- ln -snf "${TUGBOAT_ROOT}/custom/modules" "${DOCROOT}/modules/custom"
 77
 78        # Make sure our files and translations folders exists and are writable.
 79        - mkdir -p "${DOCROOT}/sites/default/files/translations"
 80        - chgrp -R www-data "${DOCROOT}/sites/default/files"
 81        - find "${DOCROOT}/sites/default/files" -type d -exec chmod 2775 {} \;
 82        - find "${DOCROOT}/sites/default/files" -type f -exec chmod 0664 {} \;
 83
 84        # Optional: Copy Drupal's public files directory from an external server. The
 85        # public SSH key found in the Tugboat Repository configuration must be
 86        # copied to the external server in order to use rsync over SSH.  More commonly
 87        # we use Stage File Proxy, which we enable in the `build` step below.
 88        - rsync -av --delete user@example.com:/path/to/files/ "${DOCROOT}/sites/default/files/"
 89
 90      # Commands that build the site. This is where you would add things
 91      # like feature reverts or any other drush commands required to
 92      # set up or configure the site. When a preview is built from a
 93      # base preview, the build workflow starts here, skipping the init
 94      # and update steps, because the results of those are inherited
 95      # from the base preview.
 96      build:
 97        # Install/update packages managed by composer.
 98        - composer install --optimize-autoloader
 99
100        # Install new configuration and database updates.
101        - vendor/bin/drush cache:rebuild
102        - vendor/bin/drush config:import --yes
103        - vendor/bin/drush updatedb --yes
104
105        # If you are downloading your files from a remove server, you won't need
106        # to enable Stage File Proxy.
107        - vendor/bin/drush pm:enable --yes stage_file_proxy
108        - vendor/bin/drush config:set --yes stage_file_proxy.settings origin "http://www.example.com"
109        - vendor/bin/drush config:set --yes stage_file_proxy.settings origin_dir "sites/default/files"
110
111        # One last cache rebuild.
112        - vendor/bin/drush cache:rebuild

Want to know more about something mentioned in the comments of this config file? Check out these topics:

Start Building Previews!

Once the Tugboat configuration file is committed to your git repository, you can start building previews!