From 8dbbe0331f1764c07168c306fd5ef972aa78a17b Mon Sep 17 00:00:00 2001
From: gitressa <3491208+gitressa@users.noreply.github.com>
Date: Fri, 28 Nov 2025 13:18:44 +0100
Subject: [PATCH 1/7] Update working-with-ddev.md
---
.../devs/getting-started/working-with-ddev.md | 243 ++++++++----------
1 file changed, 114 insertions(+), 129 deletions(-)
diff --git a/docs/src/devs/getting-started/working-with-ddev.md b/docs/src/devs/getting-started/working-with-ddev.md
index 4562de2..580522c 100644
--- a/docs/src/devs/getting-started/working-with-ddev.md
+++ b/docs/src/devs/getting-started/working-with-ddev.md
@@ -8,203 +8,182 @@ tags:
# Working with DDEV
-## DDEV-Prerequisites
+## DDEV Installation
-DDEV is an open-source tool for launching local web development environments in minutes. These environments can be
-extended, version controlled, and shared, so you can take advantage of a Docker workflow without Docker experience or
-bespoke configuration. Projects can be changed, powered down, or removed as easily as they’re started.
+DDEV is an Open Source tool for launching local web development environments in minutes.
+These environments can be extended, version controlled, and shared, so you can take advantage of a Docker workflow
+without Docker experience or bespoke configuration.
-The [official DDEV requirements page](https://ddev.readthedocs.io/en/latest/) offers detailed information on the
+The Drupal community selected DDEV as the [recommended local Drupal development tool](https://www.drupal.org/docs/getting-started/installing-drupal/install-drupal-using-ddev-for-local-development) in June 2024.
+
+The [DDEV requirements page](https://docs.ddev.com/en/) offers detailed information on the
prerequisites that should be in place but, generally speaking, here's a list of minimum requirements for DDEV:
- Recent OS version
- RAM: 8GB
- Storage: 256GB
-_Optional: You can delete the .lando.dist.yml file in the project’s root, as it is redundant when using DDEV
-instead of Lando._
-
-There are multiple ways of installing DDEV locally, mainly depending on your Operating System. Make sure you go through
-the [official DDEV installation page](https://ddev.readthedocs.io/en/latest/users/install/ddev-installation/) if your
-OS is not covered below.
-
-## Installing DDEV on Mac OS
-
-### DDEV on Mac OS using Homebrew
+There are multiple ways of installing DDEV locally, mainly depending on your Operating System.
-Homebrew is a popular package manager for Mac OS and Linux - it basically brings packages into your machine in an
-organised manner. It controls and manages their dependencies and versions (similar to Composer).
-To install Homebrew locally:
+Please follow the [DDEV installation instructions](https://docs.ddev.com/en/stable/users/install/) for your Operating System, whether it is macOS, Linux, or Windows.
-```bash
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-```
+## Installing LocalGov Drupal locally with Composer and DDEV
-With Homebrew in place, run the following to install DDEV:
+Composer (see [Getting Started](/devs/getting-started/)) is included in DDEV. It is not recommended to install
+[PHP or Composer on the host machine](https://docs.ddev.com/en/stable/users/usage/faq/#do-i-need-to-install-php-composer-nginx-or-nodejsnpm-on-my-workstation)
+to prevent conflicting versions.
-```bash
-brew install ddev/ddev/ddev
-```
+Now that we have all the required dependencies in place (Composer, Docker and DDEV), we can create our first
+LocalGov Drupal project locally.
-You can confirm that DDEV is in place by checking its installed version:
+Switch to an appropriate directory (for example the `~/Sites` folder on macOS) via the command line:
```bash
-ddev -v
+cd ~/Sites
```
-### DDEV on Mac OS using Curl
+### 1. Setting up DDEV
-To download and run the install script, run the following in your Terminal:
+First, we need to set up DDEV for LocalGov Drupal in a new directory, for example called `localgov`:
```bash
-curl -fsSL https://ddev.com/install.sh | bash
+mkdir localgov
+cd localgov
```
-## Installing DDEV on Windows
-You can install DDEV on Windows in three ways:
-- Using WSL2 with Docker inside
-- Using WSL2 with Docker Desktop
-- Installing directly on traditional Windows with an installer
-
-DDEV strongly recommends using WSL2. While its Linux experience may be new for some Windows users, it’s worth the
-performance benefit and common experience of working with Ubuntu and Bash. You can follow the
-[official DDEV Windows installation steps](https://ddev.readthedocs.io/en/latest/users/install/ddev-installation/#wsl2-docker-desktop-install-script)
-to install DDEV using WSL2 with Docker Desktop.
-
-## Installing DDEV on Linux
-
-You can use Homebrew or the curl install script in most instances, as described in the Mac OS installation instructions
-above. On the [official DDEV Linux installation page](https://ddev.readthedocs.io/en/latest/users/install/ddev-installation/#linux,
-there are more installation ways listed for some Linux and Ubuntu distributions.
-
-## Installing LocalGov Drupal locally with Composer and DDEV
-
-If you haven't yet installed Composer and Docker Desktop, see [Getting Started](/devs/getting-started/) for instructions
-on how to install these requirements.
-
-Now that we have all the required dependencies in place (Composer, Docker Desktop and DDEV), we can create our first
-LocalGov Drupal project locally.
-
-Open your Command Prompt/Terminal/Shell and switch to an appropriate directory (for example, on Mac OS X, the ~/Sites
-folder is usually preferred):
+Then, we need to initialise our DDEV project:
```bash
-cd ~/Sites
+ddev config --project-type=drupal10 --docroot=web
+ddev start
```
-### 1. Creating the Project
-Similarly to our Lando installation guide, we are going to use the LocalGov Drupal project template publicly available
-on [GitHub](https://github.com/localgovdrupal/localgov_project):
-
-
-
-To build the LGD project locally, we need to run the following Composer command and bring all the required packages
-together in a new LGD_DEMO directory (feel free to change the project name to anything else you might prefer):
-
-```bash
-composer create-project localgovdrupal/localgov-project LGD_DEMO --no-install
+All required resources are pulled in, and the containers start running.
+
+You can verify everything is working, and see all services with the DDEV `describe` command:
+
+```yml
+$ ddev describe
+┌──────────────────────────────────────────────────────────────────────────────────────────────────────┐
+│ Project: localgov ~/dev/localgov https://localgov.ddev.site │
+│ Docker platform: linux-docker │
+│ Router: traefik │
+│ DDEV version: v1.24.10 │
+├──────────────┬─────────┬────────────────────────────────────────────────────────┬────────────────────┤
+│ SERVICE │ STAT │ URL/PORT │ INFO │
+├──────────────┼─────────┼────────────────────────────────────────────────────────┼────────────────────┤
+│ web │ OK │ https://localgov.ddev.site │ drupal10 PHP 8.3 │
+│ │ │ InDocker -> Host: │ Server: nginx-fpm │
+│ │ │ - web:80 -> 127.0.0.1:32768 │ Docroot: 'web' │
+│ │ │ - web:443 -> 127.0.0.1:32769 │ Perf mode: none │
+│ │ │ - web:8025 -> 127.0.0.1:32770 │ Node.js: 20 │
+├──────────────┼─────────┼────────────────────────────────────────────────────────┼────────────────────┤
+│ db │ OK │ InDocker -> Host: │ mariadb:10.3 │
+│ │ │ - db:3306 -> 127.0.0.1:32772 │ User/Pass: 'db/db' │
+│ │ │ │ or 'root/root' │
+├──────────────┼─────────┼────────────────────────────────────────────────────────┼────────────────────┤
+│ xhgui │ stopped │ https://localgov.ddev.site:8142 │ │
+│ │ │ InDocker: │ │
+│ │ │ - xhgui:80 │ │
+│ │ │ Launch: ddev xhgui │ │
+├──────────────┼─────────┼────────────────────────────────────────────────────────┼────────────────────┤
+│ Mailpit │ │ Mailpit: https://localgov.ddev.site:8026 │ │
+│ │ │ Launch: ddev mailpit │ │
+├──────────────┼─────────┼────────────────────────────────────────────────────────┼────────────────────┤
+│ Project URLs │ │ https://localgov.ddev.site, https://127.0.0.1:32769, │ │
+│ │ │ http://localgov.ddev.site, http://127.0.0.1:32768 │ │
+└──────────────┴─────────┴────────────────────────────────────────────────────────┴────────────────────┘
```
-The Terminal output of this command will look something like the following:
+Every time DDEV starts, the project URLs are included in the output. In our case, we have selected _localgov_ as the
+name of our project and, as a result, https://localgov.ddev.site will be the first URL we can access our project on.
+Our machine's localhost IP (like `127.0.0.1:32768`) and an available port allocated to our DDEV
+project is also available. Both URLs can be used to access our project on our browser.
-
+**Note**: The LocalGov Drupal project will not be accessible via those URLs until you have created it, see below.
-Switch to the LGD_DEMO directory by running:
+At any point (when you're done for the day, for example), you can stop the project and remove its memory usage by running:
```bash
-cd LGD_DEMO
+ddev stop
```
-### 2. The DDEV Part
-
-Then, we need to initialise our DDEV project:
+Once DDEV has been initialised, you might also want to run:
```bash
-ddev config
+ddev auth ssh
```
-As you can see in the screenshot below, DDEV is suggesting default values for the following:
+... in order to enable your SSH keys for this project (this is useful for SSH authentication in case access to remote
+repositories is required). The output of this command lists all the SSH keys our container has been made aware of.
-- _Project name_ (suggested default: _locagov_)
-- _Docroot location_ (suggested default: _web_)
-- _Project type_ (suggested default: _drupal10_)
-We complete the initialisation by hitting 'Enter' in all three suggestions so the default value is selected. The output
-of the command should look like the following:
+### 2. Creating the Project
-
+We are going to use the LocalGov Drupal project template publicly available
+on [GitHub](https://github.com/localgovdrupal/localgov_project) and [Drupal.org](https://www.drupal.org/project/localgov).
-Then, fire up DDEV:
+To build the LocalGov Drupal project locally, we use Composer to bring all the required packages together:
```bash
-ddev start
+ddev composer create localgovdrupal/localgov-project
```
-Initially, the required resources are pulled in:
-
-
+All Composer packages for this project will be downloaded. This can take a while, as the command downloads all the
+necessary packages from their corresponding repositories.
-Following that, the containers start running:
+Below are the main phases of the process (you can read more about how Composer
+actually manages and installs dependencies on the
+[corresponding Composer documentation page](https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies)).
-
+#### 1. Locking dependencies to their defined versions
-Every time ddev starts, the project URLs are included in the output. In our case, we have selected _localgov_ as the
-name of our project and, as a result, _https://localgov.ddev.site_ will be the first URL we can access our project on.
-The second URL, _https://127.0.0.1:65175_, uses our machine's localhost IP and an available port allocated to our ddev
-project. Both URLs can be used to access our project on our browser.
+
-**Note**: The project will not be accessible via those URLs until you have run `composer install` in Step 3 below.
+#### 2. Downloading the locked dependencies
-At any point (when you're done for the day, for example), you can stop the project and remove its memory usage by running:
+
-```bash
-ddev stop
-```
+#### 3. Installing the downloaded dependencies
-Once DDEV has been initialised, you might also want to run:
-
-```bash
-ddev auth ssh
-```
+
-in order to enable your SSH keys for this project (this is useful for SSH authentication in case access to remote
-repositories is required). The output of this command lists all the SSH keys our container has been made aware of.
+#### 4. Applying patches
-The Docker dashboard, with all our LGD demo project's DDEV containers up and running, should look something like the
-following:
+(These have also been pre-defined in the LocalGov Drupal Composer template.)
-
+
-### 3. The composer install Part
+#### 5. Scaffolding files
-Now it's time to pull in all the Composer dependencies for this project:
+(Scaffolding is a fancy name for putting certain key Drupal files and their contents in place).
-```bash
-ddev composer install
-```
+
-If it's the first time running composer install, this process can take a while because all the project's dependencies
-need to be brought in from their repositories. We have already covered the various stages of this Composer command's
-output in our
-[LGD Lando installation guide](/devs/getting-started/working-with-lando.html#localgov-drupal-local-installation-with-composer-and-lando).
-Upon re-running the same command, the Terminal should naturally inform us that there is Nothing to _install, update or
-remove_.
### 4. Building the Site with Drush
-We can now finally install our site using the site install drush command (for more on drush, Drupal's popular scripting
-tool, see [https://www.drush.org](https://www.drush.org):
+We can now finally install our site using the site install drush command (for more on drush, Drupal's popular scripting
+tool, see [Drush](https://www.drush.org)):
```bash
-ddev drush si localgov -y
+ddev drush site:install localgov -y
```
The output of the command will look something like the following:

-Our new LocalGov Drupal site is now up and running locally! Remember those two project URLs returned by `ddev start`
-above? You can use either one of them, and the credentials returned from the last command, to access your Drupal
-administrator account on your brand new LGD site on your favourite browser:
+Our new LocalGov Drupal site is now up and running locally!
+
+To log in to your Drupal administrator account on your brand new LocalGov Drupal site, run this commmand
+to create a one time login link for the admin user:
+
+```bash
+ddev drush user:login
+```
+
+Alternatively, open https://localgov.ddev.site/ and manually enter the credentials returned from the
+`drush site:install` command here:

@@ -212,5 +191,11 @@ Logging into your admin account will land you on the Drupal content page:

-Your brand new LocalGov Drupal site is now up and running locally with DDEV. From here, you can explore all the unique
-features that come with LGD out of the box and start building your new Council website!
+Your brand new LocalGov Drupal site is now up and running locally with DDEV. From here, you can explore all the unique
+features that come with LocalGov Drupal out of the box and start building your new Council website!
+
+To check out all the features, you can create a demo site, by installing the LocalGov Demo module:
+
+```bash
+ddev drush install localgov_demo
+```
From ff8515380f3310925f52f6826a1f6d5edb6d7bb8 Mon Sep 17 00:00:00 2001
From: gitressa <3491208+gitressa@users.noreply.github.com>
Date: Fri, 28 Nov 2025 13:27:40 +0100
Subject: [PATCH 2/7] Update Getting started README.md
---
docs/src/devs/getting-started/README.md | 47 +++++++++++--------------
1 file changed, 20 insertions(+), 27 deletions(-)
diff --git a/docs/src/devs/getting-started/README.md b/docs/src/devs/getting-started/README.md
index c3240a6..4d20af1 100755
--- a/docs/src/devs/getting-started/README.md
+++ b/docs/src/devs/getting-started/README.md
@@ -11,22 +11,21 @@ to a web-based server environment.
There are two main approaches to local development:
-**1. Using your machine's native technologies:**
+**1. Using Docker for a containerized approach:**
-Some operating systems come with some of the required tools pre-installed out of the box and (e.g. PHP, web and database
-servers). Most of the time, you'll have to manually install the remaining ones. This approach generally requires more
-time spent on maintaining and updating every technology separately as well as making sure that all the moving parts
-continuously work well together.
+Tools such as Lando or DDEV "packages" all the required technologies (web server, PHP and database) for you using
+Docker, and simulates a server environment. This approach is more automated and requires less manual work as the
+tool takes care of every component's version updates and compatibility is guaranteed.
-**2. Using a containerized approach:**
+**2. Using your machine's native technologies:**
-i.e. a tool such as Lando or DDEV that "packages" all the required technologies for you and simulates a server environment.
-This approach is more automated and requires less manual work as the tool takes care of every component's version updates
-and compatibility is guaranteed.
+Historically, we installed a LAMP-style stack manually, e.g. PHP, Apache/Nginx and a database. This approach generally
+requires more time spent on maintaining and updating every technology separately as well as making sure that all the
+moving parts continuously work well together.
No matter the local installation approach you adopt, Composer is required.
-### Composer installation
+### Composer
Drupal's Core, modules and themes, are all "packages" and Composer manages these dependencies in a structured and
organised manner. To put a Drupal website together, all assets have to be sourced from a dedicated URL and compiled to
@@ -35,25 +34,19 @@ your local system.
There are two ways to install Composer, locally and globally. The latter is usually preferred as, with a single
executable installed once, it allows Composer to manage the dependencies of multiple projects present on your machine.
-To install Composer, follow the detailed instructions on the
-[official Composer documentation page](https://getcomposer.org/doc/00-intro.md#globally).
### Working with Lando/DDEV containerized servers
Many of us use a containerization technology locally for testing and development, such as Lando or DDEV. Both of these
-tools simplify the process of setting up and managing development environments for web projects. To use LGD locally with
-either Lando or DDEV, you'll need to have Docker Desktop installed first.
+tools simplify the process of setting up and managing development environments for web projects. To use LocalGov Drupal
+locally with either Lando or DDEV, you'll need to have Docker installed first.
-#### Docker Desktop installation
+Different Docker solutions are recommended for macOS, Linux, and Windows, so please follow the instructions:
-Docker Desktop is a one-click-install application for your Mac, Linux, or Windows environment that lets you build, share
-and run containerized applications and microservices. It provides a straightforward GUI (Graphical User Interface) that
-lets you manage your containers, applications, and images directly from your machine.
+- [Installing DDEV and Docker](https://docs.ddev.com/en/stable/users/install/)
+- [Installing Lando and Docker](https://docs.lando.dev/getting-started/requirements.html)
-To install Docker Desktop, follow the steps outlined on the
-[official Docker documentation page](https://docs.docker.com/desktop/install/mac-install/#system-requirements).
-
-With Docker Desktop (and Composer) in place, you can now move on to:
+With DDEV or Lando in place, you can now move on to:
- [Working with Lando](/devs/getting-started/working-with-lando.html) or
- [Working with DDEV](/devs/getting-started/working-with-ddev.html)
@@ -66,6 +59,7 @@ on their host machine. In that case, you will need to locally install the approp
- PHP
- Database server
- Web server
+- [Composer](https://getcomposer.org/doc/00-intro.md#globally)
You can have a more thorough look on our dedicated page for the [Drupal Requirements](/devs/getting-started/drupal-requirements.html).
@@ -84,11 +78,10 @@ centralised issue tracking of bug reports for end users.
### Coding standards resources
-* [Drupal coding standards](https://www.drupal.org/docs/develop/standards)
+* [Drupal coding standards](https://project.pages.drupalcode.org/coding_standards/)
### Testing resources
-* [PHPUnit documentation](https://phpunit.readthedocs.io/en/7.5/)
-* [Drupal 8 PHPUnit documentation](https://www.drupal.org/docs/8/testing/phpunit-in-drupal-8)
-* [Drupal 8 testing documentation](https://www.drupal.org/docs/8/testing)
-* [Workshop: Automated Testing and Test Driven Development in Drupal 8](https://github.com/opdavies/workshop-drupal-automated-testing)
+* [PHPUnit documentation](https://phpunit.readthedocs.io/en/)
+* [Drupal 8 PHPUnit documentation](https://www.drupal.org/docs/develop/automated-testing/phpunit-in-drupal)
+* [Drupal 8 testing documentation](https://www.drupal.org/docs/develop/automated-testing)
From af3500e4088794544920aa7d410242ef932ad301 Mon Sep 17 00:00:00 2001
From: gitressa <3491208+gitressa@users.noreply.github.com>
Date: Fri, 28 Nov 2025 13:30:01 +0100
Subject: [PATCH 3/7] Clarify that Composer is included in DDEV and Lando
---
docs/src/devs/getting-started/README.md | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/docs/src/devs/getting-started/README.md b/docs/src/devs/getting-started/README.md
index 4d20af1..1ee0914 100755
--- a/docs/src/devs/getting-started/README.md
+++ b/docs/src/devs/getting-started/README.md
@@ -33,7 +33,9 @@ create a fully functional build. To do that, Composer i.e. Drupal's dependency m
your local system.
There are two ways to install Composer, locally and globally. The latter is usually preferred as, with a single
-executable installed once, it allows Composer to manage the dependencies of multiple projects present on your machine.
+executable installed once, it allows Composer to manage the dependencies of multiple projects present on your machine.
+
+Composer is included in DDEV and Lando.
### Working with Lando/DDEV containerized servers
From 4fc3e44bf935bea1e306aa630b7a1272bf8014ba Mon Sep 17 00:00:00 2001
From: gitressa <3491208+gitressa@users.noreply.github.com>
Date: Fri, 28 Nov 2025 13:40:08 +0100
Subject: [PATCH 4/7] Set php version
---
docs/src/devs/getting-started/working-with-ddev.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/src/devs/getting-started/working-with-ddev.md b/docs/src/devs/getting-started/working-with-ddev.md
index 580522c..04d4407 100644
--- a/docs/src/devs/getting-started/working-with-ddev.md
+++ b/docs/src/devs/getting-started/working-with-ddev.md
@@ -53,7 +53,7 @@ cd localgov
Then, we need to initialise our DDEV project:
```bash
-ddev config --project-type=drupal10 --docroot=web
+ddev config --project-type=drupal10 --php-version=8.3 --docroot=web
ddev start
```
From a8db815dddafa12d08878368a859f1ecc5bed7f9 Mon Sep 17 00:00:00 2001
From: gitressa <3491208+gitressa@users.noreply.github.com>
Date: Mon, 8 Dec 2025 17:32:04 +0100
Subject: [PATCH 5/7] Update docs/src/devs/getting-started/working-with-ddev.md
Great suggestion.
Co-authored-by: Randy Fay
---
docs/src/devs/getting-started/working-with-ddev.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/src/devs/getting-started/working-with-ddev.md b/docs/src/devs/getting-started/working-with-ddev.md
index 04d4407..d7d99de 100644
--- a/docs/src/devs/getting-started/working-with-ddev.md
+++ b/docs/src/devs/getting-started/working-with-ddev.md
@@ -38,7 +38,7 @@ LocalGov Drupal project locally.
Switch to an appropriate directory (for example the `~/Sites` folder on macOS) via the command line:
```bash
-cd ~/Sites
+cd ~/sites
```
### 1. Setting up DDEV
From 4b6442a60cb5e1c7b538efed5d91adad10f68165 Mon Sep 17 00:00:00 2001
From: gitressa <3491208+gitressa@users.noreply.github.com>
Date: Mon, 8 Dec 2025 17:32:53 +0100
Subject: [PATCH 6/7] Update docs/src/devs/getting-started/working-with-ddev.md
Co-authored-by: Randy Fay
---
docs/src/devs/getting-started/working-with-ddev.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/src/devs/getting-started/working-with-ddev.md b/docs/src/devs/getting-started/working-with-ddev.md
index d7d99de..d1ce404 100644
--- a/docs/src/devs/getting-started/working-with-ddev.md
+++ b/docs/src/devs/getting-started/working-with-ddev.md
@@ -125,7 +125,7 @@ on [GitHub](https://github.com/localgovdrupal/localgov_project) and [Drupal.org]
To build the LocalGov Drupal project locally, we use Composer to bring all the required packages together:
```bash
-ddev composer create localgovdrupal/localgov-project
+ddev composer create-project localgovdrupal/localgov-project
```
All Composer packages for this project will be downloaded. This can take a while, as the command downloads all the
From 8b95bcc0de578aa7877629d23f701538dd609820 Mon Sep 17 00:00:00 2001
From: gitressa <3491208+gitressa@users.noreply.github.com>
Date: Mon, 8 Dec 2025 17:33:09 +0100
Subject: [PATCH 7/7] Update docs/src/devs/getting-started/working-with-ddev.md
Co-authored-by: Randy Fay
---
docs/src/devs/getting-started/working-with-ddev.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/src/devs/getting-started/working-with-ddev.md b/docs/src/devs/getting-started/working-with-ddev.md
index d1ce404..1330211 100644
--- a/docs/src/devs/getting-started/working-with-ddev.md
+++ b/docs/src/devs/getting-started/working-with-ddev.md
@@ -179,7 +179,7 @@ To log in to your Drupal administrator account on your brand new LocalGov Drupal
to create a one time login link for the admin user:
```bash
-ddev drush user:login
+ddev launch $(ddev drush user:login)
```
Alternatively, open https://localgov.ddev.site/ and manually enter the credentials returned from the