Drupal-specific Git reference deployment method¶

Introduction¶

This guide covers the Drupal-specific Git reference deployment method, detailing its requirements and how files and folders are synced during deployment.

For information on how to start a deployment, see the Deploying to an environment page.

Originally designed for backward compatibility, this method stems from an earlier phase when DXP supported only Drupal projects and enforced strict project structures. As the platform evolves, the long-term goal is to transition all Drupal projects to more general deployment methods, such as Git reference or Artifact.

This page explains this deployment process, its requirements, and how files and folders are synced during deployment.

What is this deployment method?¶

This deployment method uses a Git reference (e.g., a staging branch) to check out your project. It deploys specific folders and files to your application, and afterward, runs a predefined update script, if available.

To successfully deploy using this method, the Git reference must meet specific requirements regarding file structure and contents.

Requirements for successful deployment¶

When deploying via Git, the following conditions must be met:

All required files for running the application must be committed to Git.
The folder and file structure of your project must exactly match the following structure:
- docroot/ (containing the Drupal codebase)
- composer.json
- composer.lock
- private/
- vendor/
- bash/updates/update_<environment>.sh or bash/updates/update_<environment>_override.sh
- etc/drupal/settings_<environment>.php or etc/drupal/settings_<environment>_override.php
- etc/drupal/.htaccess or etc/drupal/htaccess_<environment>
- etc/drupal/robots.txt or etc/drupal/robots_<environment>.txt

Any discrepancies in this structure will cause the deployment to fail.

File and folder syncing during deployment¶

During deployment, the method syncs the following folders and files individually:

docroot folder (excluding the files directory)
composer.json file
composer.lock file
private folder (excluding the files directory)
vendor folder
bash folder
etc folder
config folder
etc/drupal/settings_<environment>.php is synced to docroot/sites/default/settings.php, unless etc/drupal/settings_<environment>_override.php exists, in which case the override file is synced.
etc/drupal/.htaccess is synced to docroot/.htaccess, unless etc/drupal/htaccess_<environment> exists, in which case the environment-specific .htaccess is synced.
etc/drupal/robots.txt is synced to docroot/robots.txt, unless etc/drupal/robots_<environment>.txt exists, in which case the environment-specific robots.txt is synced.

Running the update script¶

After the sync, the deployment process checks which update script to run, based on the environment. The following scripts are executed as the environment user:

bash/updates/update_<environment>.sh
Or, if it exists: bash/updates/update_<environment>_override.sh

The correct script ensures that environment-specific updates are applied during the deployment process.

Conclusion¶

The Drupal-specific Git reference deployment method maintains compatibility by syncing designated files and folders while executing environment-based update scripts. To ensure a smooth deployment, it's crucial that your project structure strictly adheres to the required format.

As DXP progresses, the goal is to move all Drupal projects toward more flexible and general deployment methods. If your project still relies on this method and you'd like to transition to the Git reference approach, refer to this guide for detailed instructions.