Drupal Enterprise: Set up a Local Environment

For some Drupal developers at UMN, no local development environment is necessary to work on their site. For others, it is crucial to their efficiency in development and maintenance of Drupal sites. The OIT Drupal development and engineering team recommends using the open source tool ddev ("dee-dev"), a flexible and powerful tool that utilizes Docker (a containerization/virtualization platform).

This guide provides a starting point for setting up your site locally with an existing installation of ddev on your macOS, Linux, or Windows device. Should your specific computer's configuration prevent you from following this guide, consider attending an in-person Drupal Lab or submitting a Drupal support request.

Note: Drupal Platform code is on Github Enterprise Cloud (GHEC), and you will need to be a member of a UMN github organization within GHEC before you can proceed to follow the instructions. For more information, see the Drupal GHEC Transition Guide.

In this article:

Components of Drupal Enterprise Sites

There are three general components to Drupal Enterprise sites (Database, Files/Assets, and Code), however, this guide only requires access to your site's GitHub code repository and (if you have an existing site) a copy of your existing site Database. If you do not have an existing Drupal site, this guide will help you get started with a new database using the OIT Drupal Platform code. 

  1. Database
    • Site content, various preferences, people/accounts, permissions, etc. 
    • Note: You can download your database from your Drupal Management site node
  2. Files
    • Images, PDFs, and other assets
    • Note: It is not recommended to manually place files in your local dev site. Use the Stage File Proxy Module, as noted in the steps below.
  3. Code
    • Platform-Provided components listed in the composer repository
    • Site-Specific Code (optional) via site GitHub repository
      • Modules not included in the Platform-Provided Modules
      • Folwell sub-theming
      • Site-specific configurations

Requirements

Git, GitHub, and Command Line Familiarity

The ddev tool requires usage of the command line and git commands. If you are not familiar with git or using a command line interface, you can learn more in this Git Tutorial from GitKraken.

Refer to the ddev system requirements for specific minimum version requirements before proceeding with this guide. Support options for ddev questions can be found at DDEV Docs's Get Started page.

Ensure you are setup to use SSH with Github

If you have not already done so, setup your Github account(s*) to use SSH, and authorize your SSH key within your GHEC account to use SSO.
*Note: If your site code is on Github Enterprise Server (GHES), you will need to complete this step on both GHES and GHEC. If your site code is on GHEC, you only need to complete this step on GHEC.
 

Installing Docker and ddev

Prior to setting up your Drupal site, install the following using the documentation provided by the ddev community:

  • Install Docker
    • Note: Docker must be launched and running in order for ddev to start properly in the next section. 
  • Install ddev

Setting up a ddev UMN Drupal Site

  1. Clone the Drupal composer repository
    Note: It can be useful to keep all of your ddev projects in the same parent folder if you have multiple sites to create locally, though this is not required. Each site will need to have a unique name, though. 
    1. Choose an appropriate site name to replace the your-site text in the command below:
      git clone [email protected]:umn-dst/drupal-composer.git your-site
    2. Change directories into your newly created site folder:
      cd your-site
    3. Determine which branch of the platform code you want to work within, 11.x-prod or 11.x-dev
      git fetch

      git checkout branchName
  2. Within the newly-created your-site repository folder, configure ddev as a PHP project-type 
    1. Start the configuration process:
      ddev config --project-type=php
    2. Hit the Enter or Return key if prompted for a Project Name
    3. Later in this guide, you will reconfigure ddev to be a Drupal project. Until then, this will be initialized as a generic PHP project.
    4. Note: Re-run this command any time you update ddev, then run ddev restart
  3. Start ddev 
    • Ensure that Docker has finished starting and is ready before running the following command:
      ddev start
  4. Authorize ddev to utilize your SSH key pair 
  5. Change the PHP version to 8.4
    ddev config --php-version 8.4

    ddev restart
  6. Build the platform code using the dependency manager for PHP, called composer, within the your-site directory 
    • Ensure that you are at the top level of your site-name directory before running the following command:
      ddev composer install
  7. Remove the default folder from your-site/docroot/sites/
    • It may be that the default folder does not appear in this directory. The default should not exist yet, so take no action if it does not appear.
      rm -rf default
  8. Clone your site-specific repo into a folder called: default
    1. This step will create a default site folder and allow you to sync all work to your GitHub repository as you develop and test your site locally.
    2. Navigate into the your-site/docroot/sites/ directory before cloning
    3. Be sure to keep the word "default" at the end of the following command:
      git clone[email protected]:YOUR_ORG/YOUR_REPOSITORY.git default
      • Note: after cloning, you may want to check out your repo's development branch if you have one (given the nature of local development). 
        1. From within the newly created 'default' folder, run git checkout branchNameHere to change your branch to the appropriate branch.
        2. You may need to run git fetch within the folder before checking out a different branch.
  9. Reconfigure ddev to be a Drupal project-type
    1. Important: Be sure to run this at the top level of your project folder (your-site) not the in any level of your docroot or sites or default folders. 
    2. Start the configuration process:
      ddev config --project-type=drupal
    3. Hit the Enter or Return key when prompted for: 
      • the Project Name
      • the Docroot Location
    4. Note: Re-run this command any time you update ddev, then run ddev restart
  10. Database setup (existing site or new site jump to appropriate sub-section of this step based on your need) 
    1. Connect an existing Drupal database 
      • Note: When importing a database into an existing ddev site, be sure to drop the database first with: ddev drush sql-drop
      • Import your site database: ddev import-db --file=/path/to/your/database
      • Rebuild your site cache: ddev drush cr
      • Uninstall modules that may cause conflicts in local development: ddev drush pm-uninstall -y samlauth memcache acquia_purge purge
    2. Set up a new database
      • Use these steps if you do not yet have a Drupal development site, or if you want a fresh/new database built from the OIT Drupal platform 
        1. Navigate to your local dev site in a web-browser of your choice using the ddev-provided local URL:
          • e.g., your-site.ddev.local or your-site.ddev.site
        2. Select Install to initiate the Drupal installation process
        3. Configure the options as needed for your site on the "Select components to install on this site" prompt. For standard options, check/uncheck the following: 
          1. Uncheck: Install site with Acquia settings
          2. Uncheck: Install as a Drupal Lite Site
          3. Check: Install Lightning Workflow Components
          4. Check: Install Lightning Layout Components
          5. Check: Install Folwell Component Modules
        4. Click the Submit button
  11. Configure the Stage File Proxy module 
    1. Skip this section if you do not have a live dev, stage, or production Drupal site from which you can remotely source your files.
    2. This module will pull in files from your live Drupal dev site from which you sourced your database in the steps above. 
    3. Run the following commands to set up Stage File Proxy:
      ddev drush pm-enable -y stage_file_proxy

      ddev drush cset -y stage_file_proxy.settings origin https://your-site.dev.umn.edu

      ddev drush cset -y stage_file_proxy.settings origin_dir sites/your-site.umn.edu/files
      • In Drupal Management, the listed alias for your dev site will be the origin URL similar in format to https://your-site.dev.umn.edu
      • The site domain within the origin_dir argument (sites/your-site.umn.edu/files) will use the Primary URL (Site folder name) from your Drupal Management page. 
      • Do not include the ".dev" subdomain in the origin_dir, but do consider sourcing your local files from the live dev URL rather than your production URL. 
  12. Change the Temporary directory:
    ddev drush cset -y system.file path.temporary /tmp
  13. Log in as an admin and reset your password: ddev drush uli
    1. This command will provide a one-time login URL that can be used to set the local account password for future local logins. 
    2. You may use this command for all logins if you do not wish to set a local account password, but no SAML/SSO/UMN accounts will allow logins. The only login options are a local account or the drush uli (user login) command. 
  14. Set up twig debugging and cache disabling:
    1. Edit the file your-site/docroot/sites/development.services.yml and add the following code:
      parameters:
      http.response.debug_cacheability_headers: true
      twig.config:
      debug: true
      auto_reload: true
      cache: false
      services:
      cache.backend.null:
      class: Drupal\Core\Cache\NullBackendFactory
  15. Edit the file your-site/docroot/sites/default/settings.php to contain the following:
    $settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';

    $settings['cache']['bins']['render'] = 'cache.backend.null';

    $settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null';

Additional Information

Last modified

TDX ID

3852