Skip to content

Local development

Jump to bottom
Liam Morland edited this page Jul 11, 2023 · 7 revisions

Notice

There is a lot of work outstanding on the base build. While these instructions will get you up and running, the base build is not ready for production.

Overview

For local development, DDEV works well for Drupal. It is a Docker-based PHP development environment that is easy to use. You can develop in DDEV with no knowledge of Docker. You can use it on Mac, Windows, or Linux.

This documentation is for specific to projects that use the MFIN BC base build. How to use DDEV is well documented. See https://ddev.readthedocs.io/en/stable/.

Some projects will require additional local development configuration. Site specific configuration should be added to the wiki page for the project.

This documentation assumes:

  • you have DDEV and Docker installed in a local environment
  • you have a general understanding of how git works
  • you have permissions on your computer to install software
  • you have a basic understanding of terminal commands

Note: Unless otherwise specified, all commands run from a terminal. The syntax used is for Mac/Linux. To execute commands in the container, use the same commands you would in a Mac or Linux terminal, but precede them with ddev, for example ddev drush cr to clear caches in Drupal.

Starting a new project

There is a bcbb-template in BC's github instance to get you started. All you really need from this is the composer.json file. When you set up a project, this file will fetch the modules you need from the MFIN BC Base build and the MFIN BC theme.

Initialize the DDEV project

You need to create a local directory for your local project. Either an empty git repo or a folder will work. For this documentation, we are creating a local git project, but will not be setting up a remote.

  1. git init my-project // creates the project directory
  2. download the composer.json file from the bcbb-template and save it to the my-project directory
  3. cd my-project // go to the project directory you created
  4. ddev config // initializes the ddev project
  5. When asked for a project name, type the name of your project. This has to be a valid host name. Don't use spaces or special characters. For this documentation, we are using my-project.
  6. When asked for a docroot, use html. This is the directory the base build composer file uses. Since the build process uses an html directory, setting it here saves additional config down the road.
  7. y //let ddev create the html directory
  8. For project type, type drupal10.
  9. ddev start //starts the container

Install Drupal with base build

  1. ddev composer install // installs Drupal using the composer template. The template will get instructions from the base build and get the theme.
  2. ddev launch //this will launch a browser window where you can continue setting up Drupal. This will be familiar to anyone who has installed Drupal before.

Once you have installed Drupal, your site will be at https://my-project.ddev.site/.

Tip: DDEV comes with phpMyAdmin and MailHog. To see the addresses for this software, type ddev describe. This will give you a list of all URLs associated with the project.

┌───────────────────────────────────────────────────────────────────────────────────────────────┐
│ Project: my-project ~/websites/my-project https://my-project.ddev.site                        │
│ Docker provider: docker 24.0.2                                                                │
│ Router: traditional                                                                           │
├────────────┬──────┬────────────────────────────────────────────────────┬──────────────────────┤
│ SERVICE    │ STAT │ URL/PORT                                           │ INFO                 │
├────────────┼──────┼────────────────────────────────────────────────────┼──────────────────────┤
│ web        │ OK   │ https://my-project.ddev.site                       │ drupal10 PHP8.1      │
│            │      │ InDocker: web:443,80,8025                          │ nginx-fpm            │
│            │      │ Host: 127.0.0.1:63347,63348                        │ docroot:'html'       │
│            │      │                                                    │ Mutagen enabled (ok) │
│            │      │                                                    │ NodeJS:16            │
├────────────┼──────┼────────────────────────────────────────────────────┼──────────────────────┤
│ db         │ OK   │ InDocker: db:3306                                  │ mariadb:10.4         │
│            │      │ Host: 127.0.0.1:63351                              │ User/Pass: '*/*'     │
│            │      │                                                    │ or '*/*'             │
├────────────┼──────┼────────────────────────────────────────────────────┼──────────────────────┤
│ PHPMyAdmin │ OK   │ https://my-project.ddev.site:8037                  │                      │
│            │      │ InDocker: dba:80,80                                │                      │
│            │      │ `ddev launch -p`                                   │                      │
├────────────┼──────┼────────────────────────────────────────────────────┼──────────────────────┤
│ Mailhog    │      │ MailHog: https://my-project.ddev.site:8026         │                      │
│            │      │ `ddev launch -m`                                   │                      │
├────────────┼──────┼────────────────────────────────────────────────────┼──────────────────────┤
│ All URLs   │      │ https://my-project.ddev.site,                      │                      │
│            │      │ https://127.0.0.1:63347,                           │                      │
│            │      │ http://my-project.ddev.site,                       │                      │
│            │      │ http://127.0.0.1:63348                             │                      │
└────────────┴──────┴────────────────────────────────────────────────────┴──────────────────────┘

Set up config sync

Config sync is useful because it allows you to track configuration across environments.

Assuming you want to use cofig sync with config split, you need to make sure the following directories exist at the root of your project:

  • /config/sync
  • /config/split/dev
  • /config/split/prod

Edit settings.php. At the bottom, un-comment the code which loads settings.local.php.

In your settings.local.php file, add the following:

// config sync directory.
$settings['config_sync_directory'] = '../config/sync';

// prod environment split (commented out as we want to use dev split).
// $config['config_split.config_split.prod']['status'] = TRUE;

// dev environment split.
$config['config_split.config_split.dev']['status'] = TRUE;

Once this is set up, you can export config with ddev drush cr or import config with ddev drush cim.

Note: do not change /html/sites/default/settings.ddev.php. Let DDEV manage this file. Add customisations to /html/sites/default/settings.local.php. See the Drupal documentation on settings.local.php.

Updating a local dev environment

Bring in project updates

  1. git pull // get the latest changes to the branch
  2. composer install // bring in any new Drupal core, modules or patches.
  3. ddev drush cr // clear caches
  4. ddev drush cim // brings in any configuration changes
  5. y // agree to the import

Local dev workflow

With several people working on a project, it is best if everyone works locally and submits pull requests for their work.

  1. git pull // make sure you have the latest code and config
  2. ddev drush cim // make sure the latest config is in the DB
  3. git checkout -b my-feature // make a new branch
  4. make your code changes
  5. make any config changes using the UI for the project
  6. ddev drush cex export the config changes so they can be tracked
  7. commit and push your changes
  8. submit pull request on GitHub
Clone this wiki locally