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