Switching from Drupal to General Deploy Flow

This page provides instructions on how to convert your current Drupal project structure into a format compatible with the general deployment system. Our ultimate goal is to have all projects follow this deployment flow for consistency. Please make sure to read the general deploy documentation page before proceeding.

 

If not all active environments are using the same deployment flow, then the creation of new environments will be blocked.

Step 1: Move environment-specific files

To begin the conversion process, follow these steps to move your environment-specific files from the etc/drupal directory to the .dropsolid/scaffold directory:

• Move etc/drupal/settings_[environment]_override.php or etc/drupal/settings_[environment].php to .dropsolid/scaffold/[environment]/docroot/sites/default/settings.php.
• Move etc/drupal/robots_[environment].txt or etc/drupal/robots.txt to .dropsolid/scaffold/[environment]/docroot/robots.txt.
• Move etc/drupal/htaccess_[environment].txt or etc/drupal/.htaccess to .dropsolid/scaffold/[environment]/docroot/.htaccess.

Optionally, you can merge the contents of additional_settings.[environment].php into the corresponding settings_[environment].php file. However, this step is not strictly required, as the settings_[environment].php file will still include additional_settings.[environment].php from its original location.

Step 2: Move update scripts

Next, move the update scripts from the bash/updates directory to the .dropsolid/scaffold directory:

• Move bash/updates/update_[environment].sh to .dropsolid/scaffold/[environment]/deploy.sh. Make sure to update any paths in the script since it will be moved to the project root and executed from there.
• Move any other scripts that you want to run during deployment to the same location within .dropsolid/scaffold/[environment].

Step 3: Create platform.deploy.yml

In each environment's scaffolding directory, create a platform.deploy.yml file (.dropsolid/scaffold/[environment]/platform.deploy.yml) and copy the following content into it:

sync:
  exclude:
    - docroot/sites/default/files
    - tmp
    - private/files
tasks:
  after_sync:
    - type: shell
      script: "deploy.sh"

If your project requires additional exclusions for syncing (e.g., private files stored in docroot/sites/default/private), add those paths to the sync.exclude section. Similarly, if you need to run extra scripts after syncing the repository, add them to the tasks.after_sync section.

If the platform.deploy.yml file is identical for all environments and does not require any token replacement, you can create a single instance of the file and place it in your application root (above the docroot directory).

Step 4: Create __templates for new environments

To ensure that any newly created environments can immediately use the new deployment flow, create a __templates directory inside the .dropsolid/scaffold directory. This directory will be copied to .dropsolid/scaffold/[environment] during environment creation and should contain at least the following files:

• .dropsolid/scaffold/__templates/docroot/sites/default/settings.php
• .dropsolid/scaffold/__templates/platform.deploy.yml
• .dropsolid/scaffold/__templates/deploy.sh

Since these files will be copied to a new environment, it's crucial to use tokens for placeholders.

In the settings.php file, replace all database credentials, hash salt, and environment references with their corresponding token strings.

For example, taking a etc/drupal/settings_[environment].php file and changing the following:

<?php
      $db_name = '[[ database_name ]]';
      $db_user = '[[ database_user ]]';
      $db_pass = '[[ database_password ]]';
      $db_host = '[[ database_host ]]';
      $db_port = '[[ database_port ]]';
      $db_driver = 'mysql';
      $db_prefix = '';

[...]
      $settings['hash_salt'] = '[[ env_secret_key ]]';

[...]

      // List of trusted IPs (IP numbers of our reverse proxies)
      $settings['reverse_proxy_addresses'] = array_merge(['127.0.0.1'], explode(',','[[ proxy_ips ]]'));

      // Now that token support is in you can also use a token to determine Drupal's deployment identifier
      $settings['deployment_identifier'] = \Drupal::VERSION . '[[ unix_timestamp_at_deploy_time ]]';

      if (file_exists(DRUPAL_ROOT . '/../etc/drupal/additional_settings.[[ environment_name ]].php')) {
        include DRUPAL_ROOT . '/../etc/drupal/additional_settings.[[ environment_name ]].php';
      }
[...]

Should result in a file ready for __templates. Coincidentally, you can do the same for the settings files you've already moved to .dropsolid/scaffold/[environment]/docroot/sites/default/settings.php as these tokens get replaced during deploys.

The hash_salt value may change

The [[ env_secret_key ]] token will have a different value than the current hash salt, but this change will only invalidate existing one-time logins. The hash salt is utilized for one-time login links, cancel links, form tokens, and other related functionalities.

In the deploy.sh file, replace any environment references with the environment name token string.

For example, taking a bash/updates/update_[environment].sh file and changing the following:

#!/bin/sh
[...]
  # Ensure CMI knows about the split.
  ${DRUSH} config_import_single:single-import ../config/sync/config_split.config_split.[[ environment_name ]].yml
[...]

Please note that token replacement currently only works for files inside the .dropsolid/scaffold directory. The replacement occurs before these files are scaffolded into their final location.

Step 5: Contact Support

Once you have completed the above steps, please email us at support@dropsolid.com to inform us of the environments and projects you wish to switch to the new general deployment flow. We are always ready to assist you and can switch back to the old flow if necessary.