Using Tugboat previews on Drupal Core and contrib merge requests

Live deployment previews are a supported feature of Drupal Core and contrib issues. This feature is built on Tugboat, the same system that powers the community-maintained SimplyTest.me.

How is a live preview generated?

When a merge request is opened on a core issue, a live deployment preview is automatically generated from a current snapshot of the branch being developed against, with the changes from the merge request automatically applied.

For Drupal core, there is a public repository that hosts the set of Tugboat configurations for each branch. When a merge request is created, there is code at Drupal.org that loads a configuration file from that repository and requests Tugboat to build a preview.

For contributed modules, a Tugboat configuration file named .tugboat/config.yml must be added at the repository's root. You can find examples further down this page.

As additional changes are made to the merge request, the live preview is automatically updated to reflect those changes. Live previews expire five days after their last update.

Important: before you start

• The project must have a composer.json file. Tugboat needs it in order to install the project and its dependencies. For detailed information about adding a composer.json file to your project, see the documentation.
• Tugboat will only create a preview if the configuration file is present at the time the merge request is created. If you add a Tugboat configuration file to an existing merge request, close it and reopen it.

Adding live previews to a contributed module

1. Create a file at the root of the repository named .tugboat/config.yml.
2. Paste the sample configuration below from the Webform module into your new config file.
3. Search and replace webform with your module name in the config file.
4. Create an issue, then an issue fork, and finally a merge request. Creating the merge request will trigger a Tugboat live preview which will be visible after reloading the issue.

services:
  php:
    # Specify the version of Drupal you wish to use for Tugboat below.
    image: tugboatqa/drupal:10
    default: true
    http: false
    depends: mysql
    commands:
      update: |
        set -eux
        # This is an environment variable we added in the Dockerfile that
        # provides the path to Drupal composer root (not the web root).
        cd $DRUPAL_COMPOSER_ROOT
        # We need to change the minimum stability to dev to use the path
        composer config minimum-stability dev
        # We configure the Drupal project to use the checkout of the module as a
        # Composer package repository.
        composer config repositories.tugboat path $TUGBOAT_ROOT
        # Now we can require this module
        composer require drupal/webform
        # Install Drupal on the site.
        vendor/bin/drush \
          --yes \
          --db-url=mysql://tugboat:tugboat@mysql:3306/tugboat \
          --site-name="Live preview for ${TUGBOAT_PREVIEW_NAME}" \
          --account-pass=admin \
          site:install standard
        # Add tugboat URLs to the Drupal trusted host patterns.
        echo "\$settings['trusted_host_patterns'] = ['\.tugboatqa\.com\$'];" >> $DOCROOT/sites/default/settings.php
        # Set up the files directory permissions.
        mkdir -p $DRUPAL_DOCROOT/sites/default/files
        chgrp -R www-data $DRUPAL_DOCROOT/sites/default/files
        chmod 2775 $DRUPAL_DOCROOT/sites/default/files
        chmod -R g+w $DRUPAL_DOCROOT/sites/default/files
        # Enable the module.
        vendor/bin/drush --yes pm:enable webform
      build: |
        set -eux
        cd $DRUPAL_COMPOSER_ROOT
        composer install --optimize-autoloader
        # Update this module, including all dependencies.
        composer update drupal/webform --with-all-dependencies
        vendor/bin/drush --yes updb
        vendor/bin/drush cache:rebuild
  mysql:
    image: tugboatqa/mariadb

Adding live previews to a contributed theme

1. Create a file at the root of the repository named .tugboat/config.yml.
2. Paste the sample configuration below from the Bootstrap theme into your new config file.
3. Search and replace bootstrap with your theme name in the config file.
4. Create an issue, then an issue fork, and finally a merge request. Creating the merge request will trigger a Tugboat live preview which will be visible after reloading the issue.

services:
  php:
    # Specify the version of Drupal you wish to use for Tugboat.
    image: tugboatqa/drupal:10
    default: true
    http: false
    depends: mysql
    commands:
      update: |
        set -eux
        # Increase memory limit.
        echo "memory_limit = 3G" >> /usr/local/etc/php/conf.d/my-php.ini
        # This is an environment variable we added in the Dockerfile that
        # provides the path to Drupal composer root (not the web root).
        cd $DRUPAL_COMPOSER_ROOT
        # We need to change the minimum stability to dev to use the path.
        composer config minimum-stability dev
        # We configure the Drupal project to use the checkout of the theme as a
        # Composer package repository.
        composer config repositories.tugboat path $TUGBOAT_ROOT
        # Now we can require this theme.
        composer require drupal/bootstrap

        # Install Drupal on the site.
        vendor/bin/drush \
          --yes \
          --db-url=mysql://tugboat:tugboat@mysql:3306/tugboat \
          --site-name=Bootstrap \
          --account-pass=admin \
          site:install standard

        # Add tugboat URLs to the Drupal trusted host patterns.
        echo "\$settings['trusted_host_patterns'] = ['\.tugboatqa\.com\$'];" >> $DOCROOT/sites/default/settings.php

        # Enable the theme.
        vendor/bin/drush --yes theme:enable bootstrap
        # Set the theme as default.
        vendor/bin/drush --yes config-set system.theme default bootstrap
        # Rebuild cache.
        vendor/bin/drush cache:rebuild

        # Set up the files directory permissions.
        mkdir -p $DRUPAL_DOCROOT/sites/default/files
        chgrp -R www-data $DRUPAL_DOCROOT/sites/default/files
        chmod 2775 $DRUPAL_DOCROOT/sites/default/files
        chmod -R g+w $DRUPAL_DOCROOT/sites/default/files

      build: |
        set -eux
        cd $DRUPAL_COMPOSER_ROOT
        composer install --optimize-autoloader
        # Update this theme, including all dependencies.
        composer update drupal/bootstrap --with-all-dependencies
        vendor/bin/drush --yes updb
        vendor/bin/drush cache:rebuild

  mysql:
    image: tugboatqa/mariadb

Adding live previews to general project

Tugboat previews will work with "general" projects that are not a module or theme on Drupal.org as well. For example, a general project for a NodeJS package using Storybook as a development environment. To create a live preview of the Storybook build, one could create a file at the repository's root named .tugboat/config.yml with the following content:

services:
  apache:
    image: tugboatqa/httpd:2.4
    default: true
    commands:
      init:
        - curl -fsSL https://deb.nodesource.com/setup_lts.x | bash -
        - apt-get install -y nodejs
      build:
        - npm install
        - npm run build-storybook
        - ln -snf "${TUGBOAT_ROOT}/storybook-static" "${DOCROOT}"

This is only a single example - since general projects cover a wide variety of use cases the Tugboat configuration could vary quite a bit.

Viewing a Live Preview

To view a live preview, click the 'View Live Preview' button next to the merge request. The default admin credentials for any live preview are:

• Username: admin
• Password: admin

Troubleshooting

• View Logs - The "View Logs" link will take you to the logs for the Tugboat preview's build process. This can help identify if there is a breaking issue in the merge request or some sort of infrastructure error. If the error that you see seems unrelated to your changes, you can reach out to the Tugboat folks via their Slack channel.
• Rebuild - The preview will rebuild automatically each time a new commit is added to the merge request, but you can trigger this event manually by clicking the "Rebuild" link.
• If a preview is missing from a merge request, note that live previews expire five days after their last update.
• Out of memory issues: You may or may not run out of PHP memory if you are installing large modules with multiple dependencies. If you do take a look at the following examples. 
  https://git.drupalcode.org/project/demo_design_system/-/blob/1.0.x/.tugb...
  https://git.drupalcode.org/project/demo_design_system/-/blob/1.0.x/.tugb...
• White screen of death after login: If you run into your tugboat throwing an error, and you did the step above, make sure your settings.local.php does not have an extra white line before the <?php opening tag.

Specifying a different core version

For contributed projects, you can specify different versions of Drupal core. Both [MAJOR] and [MAJOR].[MINOR] tags are available. This repository documentation contains a list of available tags.