Integration of DDEV into Lando Drupal Setup: A Complete Guide

Introduction

The regular Lando-configured Drupal setup along with DDEV can improve the workflow of your developers.  This guide details the procedure that will describe Manjaro Linux but is also suitable for other systems.

Why choose DDEV?

Choosing DDEV is because it is becoming the de facto standard among the Drupal community. This is consistent with the trend toward tools that are conducive to a modern and efficient development workflow.

It is possible to implement DDEV with Lando, which will result in a more open development space that meets the needs of the different preferences and skills of our team and the wider community. Our support for both platforms allows us to provide flexibility, ease transitions, and encourage wider collaboration, thus making it possible for contributors to work with their preferred tools.

Setup Requirements

Before integrating DDEV with a Lando-configured Drupal project,  you should meet the following requirements for a smooth setup.

Operating System

Use Manjaro Linux, updated to the latest stable release. This guide is tailored for Manjaro but can be adapted for other OS with minor tweaks.

Existing Drupal Project

Have a Drupal project already running with Lando. Here we assume it is familiar with Lando and basic Drupal setup.

Lando

Ensure Lando is installed and working, as this guide does not cover its initial setup.

Docker

The docker must be installed and properly configured. Ensure Docker can run containers without sudo privileges.

Command-Line Skills


Basic command-line proficiency is essential for executing setup commands.

Docker Familiarity

A basic understanding of Docker helps, though Lando and DDEV simplify much of the complexity.

Drupal Architecture

Understand Drupal's architecture, especially `settings.php` configurations, to manage your development setup effectively.

Once you complete these requirements, you can integrate DDEV into your Drupal development workflow.

Installation of DDEV


Let's begin by installing DDEV if it still needs to be part of your toolkit. During this process, we'll ensure that Lando's configurations, including `.lando.yml` and `settings.php`, remain intact for a smooth coexistence.

To start the process, you can access the DDEV installation documentation here.

https://ddev.readthedocs.io/en/latest/users/install/ddev-installation/#linux

 

This installation will not interfere with your Lando setup, allowing both environments to function seamlessly together.

To install DDEV on Manjaro, use the following command.

$ yay -S dev-bin

For other operating systems, the installation process may differ. Please refer to DDEV's installation instructions for your specific operating system by visiting their installation guide at.

https://ddev.readthedocs.io/en/latest/users/install/ddev-installation/

 

This will ensure you have the correct steps for a smooth setup.

This command fetches and installs the latest DDEV version that is suitable for our environment. During the installation, you can expect to see confirmations.

Package installation requests

Dependency checks and installations


Download progress and completion statuses

==> Making package: dev-bin 1.22.7-1 (Wed 13 Mar 2024 11:23:46)
...
==> Checking for packaging issues...


==> Creating package "dev-bin"...
...
==> Finished making: ddev-bin 1.22.7-1 (Wed 13 Mar 2024 11:30:42)


Configuring Your Project for Dual DDEV and Lando Compatibility


Before merging DDEV with your current Lando-configured project, it is prudent to acquaint yourself with the fundamental principles of DDEV. I suggest initiating this process by exploring the "Starting a Project'' guide provided at.

https://ddev.readthedocs.io/en/latest/users/project/


For those seeking a concise overview specific to Drupal, the Drupal Quickstart section in the DDEV documentation offers a superb resource. You can find it here.

https://ddev.readthedocs.io/en/latest/users/quickstart/

 

Tailoring the Quickstart for an Established Project

While the DDEV Quick Start manual delineates a method for a pristine setup, my venture already encompasses a .lando.yml file, a Drupal codebase instantiated via composer create drupal/recommended-project, and employs www as the document root. The DDEV Quickstart advocates for the initiation of a novel Drupal enterprise through the following directives.

mkdir my-drupal10-site

cd my-drupal10-site

dev config --project-type=drupal10 --docroot=web

dev start

dev composer create Drupal/recommended-project

dev composer requires drush/drush

dev drush site:install --account-name=admin --account-pass=admin -y

# use the one-time link (CTRL/CMD + Click) from the command below to edit your admin account details.

dev drush uli

dev launch

Since we're setting up DDEV alongside an existing Lando configuration, we'll need to modify the instructions to suit our established project.

Moving to DDEV Configuration

To quickly switch to DDEV, I'll concentrate on the configuration steps and skip the initial setup steps that aren't relevant to an already developed site.

Configuration of DDEV for Your Drupal Project

$ ddev config --project-type=drupal10 --docroot=web

Running this command sets up DDEV for Drupal 10, designating 'web' as the document root and generating the necessary DDEV configuration files in your project directory. While DDEV doesn't officially support Drupal 11 yet, it does work, and dedicated support will be available soon.

Customization of `settings.php` for DDEV

Let's explore the practical aspects of configuring DDEV, specifically how it interacts with Drupal's `settings.php` file:

When you run `dev config`, it detects any existing `settings.php` files and sets up a mechanism to integrate them with DDEV's environment without changing your primary configuration.

DDEV adds `settings.ddev.php` conditionally, ensuring Drupal connects to the correct database when running within DDEV, leaving other environments like Lando unaffected.

Environment variables, such as `IS_DDEV_PROJECT`, are crucial in this process, indicating when to apply DDEV-specific settings.

Here's a closer look at how this works.

// Automatically generated include for settings managed by ddev.

$ddev_settings = dirname(__FILE__) . '/settings.ddev.php';

if (getenv('IS_DDEV_PROJECT') == 'true' && is_readable($ddev_settings)) {
require $ddev_settings;
}

This auto-generated snippet is added to `settings.php`, and the creation of `settings.ddev.php` allows for an efficient switch between DDEV and other environments, such as Lando, without manual intervention. If `settings.php` and/or `settings.ddev.php` don't already exist, DDEV will create them for you.

Interestingly, if you delete `settings.php` or `settings.ddev.php`, DDEV automatically reinstates them with the appropriate configurations when you start it up. This gives a strong foundation for the setup process but the question of how much developers can control and see these automated actions remains open.

Kickoff the Project Using DDEV

After the configuration of DDEV, you can start the project with the following command.

$ dev start

This command will boot up your DDEV environment. You’ll see the creation of Docker containers and network configurations needed for your Drupal site to run locally.

During your setup of DDEV, you might encounter a message about `mkcert` not being properly installed, as I did.

According to the DDEV installation guide, the notice about `mkcert` pertains to setting up a trusted HTTPS experience for local development. This led me to make a deliberate choice regarding my local development environment: instead of following the suggestion, I opted to continue without installing `mkcert`, accepting HTTP for my setup. My choice was due to my preference not to add any more complexity to my project.

As someone well-versed in using Lando for local development, I've grown accustomed to its approach to HTTPS. Lando automatically sets up an HTTPS service that is untrusted by default, prompting a browser warning that I can choose to bypass. This setup has become a familiar part of my workflow. Thus, a balance between security protocols and development convenience has been established.

It is surprising to find that DDEV, in contrast, opts to remove this decision-making process from the developer. By requiring `mkcert` for a trusted HTTPS setup, DDEV aims for a seamless, warning-free browsing experience right out of the box. While the intent is to simplify development workflows, it restricts my choice to use an untrusted HTTPS setup and introduces a deviation from what I've come to expect. This shows the necessity of comprehending the intricacies of our development tools.

Kickoff the Project Using DDEV
Integration of DDEV into Lando Drupal Setup: A Complete Guide


Installation of Drush with DDEV

Since my existing project does not have Drush installed, I need to run the following command:
dev composer requires drush/drush

Installation of Drush with Composer

To achieve the inclusion of Drush in the project, execute.

$ dev composer requires drush/drush

This command uses Composer within the DDEV environment for the installation of Drush, which is a command-line shell and scripting interface for Drupal. All of the processes will be set up by Composer, stating Drush as a part of your project.

Customization of the Project Setup

After making sure that Drush is installed via the command `dev composer require drush/drush`, let's talk about a common step you might face when setting up a Drupal project from scratch using DDEV.

Start of  Standard Project Creation

Along with a few other leading publications, DDEV also suggests starting a new project by executing the command.

dev composer create Drupal/recommended-project

Nevertheless, our situation is different because our Drupal setup is sufficient to match the structure created by the Drupal/recommended project. It could apply if your project has been running for a while or was initially set up with similar parameters.

Conversion to Drupal Install

By now you must have Drush installed, and with the knowledge that we do not need a typical DDEV composer create step in our scenario your DDEV environment should be running. Once we made sure that the site was available, then we installed Drupal in a very simple way.

Making Sure the Site Is Live and Accessible

Your project should be launched successfully after you do ddev start as indicated by the feedback. From this point, you can check if the site is available to proceed with an installation of Drupal.

Successfully started core-drupal

The project can be reached at http://core-drupal.ddev.site http://127.0.0.1:32769

 

However, since we're working with an existing project, you can skip this step and focus on configuring DDEV for your current setup.

If you now visit http://core-drupal.ddev.site, the site should be accessible and show Drupal's installation page. It shows that the site works and confirms all is well before we start with the command-line installation steps.

With all that out the way and our basic checks complete, we are now ready to install Drupal using Drush.

Performing a Drupal install with DDEV

Go back to your command line and execute this Drupal install command.

dev drush site:install --account-name=admin --account-pass=admin -y

A detailed discussion of the command options to install Drupal with Drush:

--account-name=admin: Specifies the username for the main administrator account created during installation. In this case, the username will be "admin".

--account-pass=admin: Sets the password for the administrator account specified by --account-name. Here, the password is set to "admin".

-y: Automatically answers "yes" to any prompts that Drush might present during the operation, allowing the command to run in non-interactive mode.

You are about to:

* DROP all tables in your 'db' database.

// Do you want to continue?: yes.                                                                                      
...
[success] Installation complete.

Starting Your Project with DDEV

Once the installation is done there are a couple of ways you can access your new Drupal site.

1. Create a One-Time Login Link


With Drush uli, use this command to generate a one-time login link for the site without having to log into it normally.

2. Do a direct login

Go to the Drupal site and just go to the / user (eg. yoursite.com/user ) URL address, then you should be able to login using the admin username and password that you also configure at installation time.

dev drush uli

http://core-drupal.ddev.site/user/reset/1/1710310897/mLHP4_ziNDhJQAB0G8…

We've now added DDEV to our project that already had Lando set up.

How to Handle Lando and DDEV Environments

When you use both Lando and DDEV, keep in mind that you can't run these environments at the same time for one project. If you try to start Lando with `Lando start` while DDEV is running, or the other way around, you'll run into problems with port binding. For instance, both projects can't use ports 80 or 443 at once.

To switch between environments without issues.

Stop DDEV: Type `ddev stop` before you start Lando.

Stop Lando: Type `Lando stop` before you start DDEV.

Fixing Common Problems

Even after you stop the environments, you might still get errors about port allocation when you switch between Lando and DDEV. Here's a problem you might face.


Launching Lando while DDEV is running 

You might encounter an error related to port binding issues for port 443. The error message will look like this.

Error response from daemon: driver failed programming external connectivity on endpoint

landoproxyhyperion5000gandalfedition_proxy_1: Bind for 127.0.0.1:443 failed: port is already allocated

When you try to start DDEV while Lando is running, you'll get a warning about port 443 being occupied. This stops DDEV from starting.

Failed to start core-drupal: unable to listen on required ports, port 443 is already in use,
Troubleshooting suggestions at

https://ddev.readthedocs.io/en/stable/users/basics/troubleshooting/#unable-listen

 

To fix this issue in both scenarios, you need to shut down the conflicting environment. Use 'Lando power off' to shut down all Lando services, and 'dev power off' to do the same for DDEV. These commands help free up any ports in use paving the way for the other environment to start without problems.

 Launching Lando while DDEV is running
Integration of DDEV into Lando Drupal Setup: A Complete Guide

Summary

By expanding our Drupal project to work with both Lando and DDEV, we open up new possibilities in how we develop. This setup with two environments does more than just cater to personal likes and project needs - it also helps create a more flexible and tough development approach. Our shift from using Lando to supporting both it and DDEV on Manjaro Linux shows how we're taking charge of managing development environments. This gives developers more options and adaptability in their work.