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.

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@UMN 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. 

Note: The OIT Drupal platform does not currently support site owners storing their site repositories on the UMN Github Cloud instance. We will send an announcement to our Drupal Enterprise Platform Google Group when that option becomes available. Presently, site owners must store their site repositories in the University On-Premise instance Github.umn.edu.

  1. Database
    • Site content, various preferences, people/accounts, permissions, etc. 
    • How to get a copy of existing site database: Self-Service downloads via Drupal Management
  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
    1. Platform-Provided components listed in the composer repository
    2. Site-Specific Code (optional)
      • 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 https://ddev.readthedocs.io/en/stable/#support.

Installation of 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

Set 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]:drupalplatform/d8-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
      1. For Drupal 9, reference 9.x-prod or 9.x-dev
      2. For Drupal 10, reference 10.x-prod or 10.x-dev

git fetch

git checkout branchName

  1. 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 specific Drupal 9 or Drupal 10 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
  2. Start ddev
    • Ensure that Docker has finished starting and is ready before running the following command:
      ddev start
  3. Authorize ddev to utilize your SSH key pair
    • Ensure that you have uploaded your public SSH key to GitHub@UMN (you can upload keys at https://github.umn.edu/settings/keys) before running the following command:
      ddev auth ssh
  4. Change the PHP version to 8.2
    1. ddev config --php-version 8.2
    2. ddev restart
  5. 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
  6. 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
  7. 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 GitHub@UMN 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
    4. Note: after cloning, you may want to check out your repo's development branch if you have one (given the nature of local development).
      • From within the newly created 'default' folder, run git checkout branchNameHere to change your branch to the appropriate branch.
      • You may need to run git fetch within the folder before checking out a different branch.
  8. Reconfigure ddev to be a Drupal 9 or Drupal 10 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:
      1. Drupal 9:
        • ddev config --project-type=drupal9
      2. Drupal 10:
        • ddev config --project-type=drupal10
    3. Hit the Enter or Return key when prompted for:
      1. the Project Name
      2. the Docroot Location
    4. Note: Re-run this command any time you update ddev, then run ddev restart
  9. Database setup (existing site or new site jump to appropriate sub-section of this step based on your need)
    • Connect an existing Drupal database
      1. Note: When importing a database into an existing ddev site, be sure to drop the database first with: ddev drush sql-drop
      2. Import your site database: ddev import-db --src=/path/to/your/database
      3. Rebuild your site cache: ddev drush cr
      4. Uninstall modules that may cause conflicts in local development
        1. Drupal 9
          1. ddev drush pm-uninstall -y simplesamlphp_auth memcache acquia_purge purge
        2. Drupal 10
          1. ddev drush pm-uninstall -y samlauth memcache acquia_purge purge
    • Set up a new database 
      1. 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: 
          1. 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"
            The "Select components to install on this site" page is shown with the standard options checked.
        4. Select Submit
  10. 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. 
         
  11. Change the Temporary directory: ddev drush cset -y system.file path.temporary /tmp
  12. Log in as an admin and reset your password: ddev drush uli
    • This command will provide a one-time login URL that can be used to set the local account password for future local logins. 
    • 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. 
  13. Setting 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
       
    2. 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

Drupal Overview 

Drupal Enterprise 9 Admin Guide

Drupal 9 Modules 

Sub-theming Folwell

Enable Folwell Theme and Modules on an existing Drupal 9 Site

Drupal Learning Opportunities 

 

 

 

Last modified

TDX ID

3852