How to Locally Install a New Drupal 10 Site

A fair amount of language is used in this blog post that may be confusing to the inexperienced. Before reading through this post, it’s important that you’re at least familiar with the following terms:

• Drupal
• Docker
• Local web development

When I began my Drupal development career, I was incredibly surprised at the lack of available resources to answer a relatively simple question: How do I create a fresh Drupal installation on my machine? In an effort to simplify the process of getting started in Drupal development, I’ve compiled three different ways to install Drupal on your computer: Lando, DDev, and Docker Compose. If you’re looking for the simplest, fastest way to get up and running, skip to the DDev method.

• For each of the methods listed in this blog post, you’ll need Docker installed on your device. If you haven’t already done so, go to Docker's installation page and install whichever version is compatible with your device (Docker supports virtually every operating system).
• A command line interface
  • MacOS: Terminal
  • Windows 10: PowerShell
  • Windows 11: Terminal
  • Linux: You don’t need this explained.
• Depending on which method you plan to use, you will need to install one of two container management softwares. If you were able to install Docker, you’ll be able to install each of these.
  • Lando
  • DDev

Lando and DDev don’t play nice when both are active at the same time. When switching between projects that use different container managers, make sure to stop one before changing to the other. Both container managers have a poweroff command that cleanly shuts down all projects and containers (e.g. lando poweroff).

Let’s get into the first method which leverages Lando.

Create a new folder wherever you store your workspaces on your computer. All of our project files will be contained within this folder. For the sake of this demonstration, my project folder is named drupal-lando.

Within your terminal of choice, change directories into your project folder and run lando init to create a new Lando project. Lando will prompt you to answer a series of questions that define your project’s configuration. Choose the following options by pressing enter when prompted.

• From where should we get your project’s codebase?: current working directory
• What recipe do you want to use?: drupal10 (use arrow keys to scroll up)
• Where is your webroot relative to the init destination?: drupal/web
• What do you want to call this app?: Drupal Lando (substitute your project’s name)

Notice that a new file has been created in your project folder called .lando.yml. If you open that file, you’ll find that it contains the configuration we just defined in the command line.

Now that the project has been initialized, it needs to be started up by running lando start. Lando will automatically create the Docker containers that are needed for Drupal to work properly. After lando start finishes, it will output some important information about the project including the site’s local web address. With the project started, run the following command to install Drupal’s files. If you want to use a newer version of Drupal 10, update the tag attached to drupal/recommended-project from 10 to your desired version (e.g. 10.1.6).

lando composer create-project drupal/recommended-project:10 drupal

Once Composer has finished generating Drupal’s files, you’re ready to access your new Drupal 10 site! Go to one of the URLs provided by Lando after project startup (lando info will print those URLs to the console as well) and go through Drupal’s installation process.

When you come to the “Database configuration” section of Drupal’s installation form, fill the fields in with the following values before clicking “Save and continue”.

• Database name: drupal10
• Database username: drupal10
• Database password: drupal10
• Advanced options > Host: database

Drupal will do a little more magic and present you with the site configuration form. Fill this out with your desired values, and submit it for Drupal to take you to the default homepage.

Congratulations! You have successfully installed Drupal 10 with Lando!

Arguably the simplest of the 3, this method uses DDev to install Drupal, and the process is very similar to Lando’s:

1. Create a project folder
2. Initialize the DDev project and start it
3. Generate Drupal’s files with Composer
4. access the site
5. Install Drupal through the web UI

To start, create a new folder to house your project files (drupal-ddev for me) and change directories into it. Unlike Lando, the name of your project folder determines the name of the DDev project itself. To take care of steps 2 and 3 in one fell swoop, run the following command in your command line.

ddev config --project-type=drupal10 --docroot=web --create-docroot && ddev start && ddev composer create drupal/recommended-project:10 -y

And just like that, our Drupal site is already accessible through the web UI! To get the environment’s local web address, use the ddev describe command. In the row labeled web should be a valid web address through which you can access your project (https://docker-ddev.ddev.site for me).

Once presented with the Drupal installation form, choose your language and desired installation profile before proceeding to the “Set up database” section - but wait, why did it skip that part? Unlike Lando, DDev automatically establishes a connection between the database and web servers so that you only have to configure the parts that matter to you. Neat!

From here on, the process is no different than installing with the other three methods: Configure Drupal to your liking, click “Save and continue”, and enjoy your new local Drupal 10 website!

Up to this point, we’ve been using container management software that acts as a layer of abstraction on top of Docker to simplify the process and provide us with some handy features. However, certain scenarios may require you to manually create your own Docker containers and bypass tools like Lando and DDev. Additionally, this approach provides you with a greater level of control over the container images you use, tooling, network configuration, and more. While this solution may not be for everyone, it’s great to keep in your back pocket. You never know when you’ll need it!

There are a lot of different ways to install Drupal with plain old Docker containers, but we’ll be focusing on a simple solution that leverages Docker Compose. Docker Compose is simply a tool that comes with Docker and makes it much easier to define, run, and manage multi-container applications. By nature, Drupal is a multi-container application as it requires a web server and a database server.

In an empty project folder (drupal-docker for me), create a new file called compose.yml as Docker Compose uses YAML to define app configuration. Inside that file, post this code snippet.

services:



 drupal:

   image: drupal:10-apache

   ports:

     - 8080:80

   volumes:

     - ./:/opt

   restart: always



 mysql:

   image: mysql:8

   environment:

     MYSQL_ROOT_PASSWORD: drupal10

     MYSQL_DATABASE: drupal10

   volumes:

     - mysql-data:/var/lib/mysql

   restart: always



volumes:

 mysql-data:

In your terminal, change directories to your project folder and run docker compose up -d. Docker will read the contents of compose.yml and create a new application with the provided containers (services).

This is where things can get a little confusing. To install Drupal files, we need to pass a Composer command to the web server container.

docker container exec -it -w /opt drupal-docker-drupal-1 composer create-project drupal/recommended-project:10 drupal

There’s a lot to dissect here, so let’s break this command down into two segments:

1. docker container exec -it -w /opt drupal-docker-drupal-1
2. composer create-project drupal/recommended-project:10 drupal

I first want to draw attention to segment 2 as it should look very familiar if you read through the Lando and DDev methods in this blog post: Use Composer to generate Drupal’s core files. Segment 1 is telling Docker that you want to run segment 2 within your Drupal container: docker container exec means we want to execute a command on a Docker container, -it is unimportant for the purposes of this post, -w /opt indicates the working directory,  and drupal-docker-drupal-1 is the name of the container to run the command inside of. Unless your project folder is also named drupal-docker, your Drupal container name will not be drupal-docker-drupal-1. Docker automatically determines the container’s name by piecing together the project name, service name (as defined in compose.yml), and the container’s number in case multiple Drupal services are present.

With the containers and files in place, all that remains is to install Drupal and connect it to the MySQL container. In your browser, navigate to http://localhost:8080. If you need the web server to listen on a different port, edit the ports option under the drupal service in compose.yml to <your-port>:80.

Choose your language and installation profile before proceeding to the “Set up database” form. Once you’re there, fill the fields in with the following values before clicking “Save and continue”.

• Database name: drupal10
• Database username: root
• Database password: drupal10
• Advanced options > Host: mysql

Finish installation with the site configuration form, and voila! Your Drupal 10 site is ready to go!