Happy December! As 2020 comes to a close, I decided it was time to do a totally different type of Drupal 9 post. A lot of what I’ve been focused on over the last six months since Drupal 9 came out was how to upgrade to Drupal 9. But what about those projects that are starting on Drupal 9 for the first time? What do you need to start from nothing and get up and running with Drupal 9?
This post is going to cover all those things.
Basic Requirements
As with any Drupal site, there are a few basic system requirements to install and run Drupal. My recommendation (and this tutorial) will drive you towards using a solution tailored towards running Drupal. These virtual machines come with everything you need (including the webserver, database, etc.). The most common solutions are:
Drupal VM (Vagrant based)
DDev (Docker based)
Docksal (Docker based)
Lando (Docker based)
Jeff Geerling (of Drupal VM fame) does a local environment survey every year. Here are the results from 2020.
Based on his data you can see that Lando is in the lead, but this shouldn’t dissuade you from using some of the other solutions I mentioned are very well maintained and work great. If you haven’t setup a VM before, I would suggest reviewing my post on prepping your host machine to install the requisite software.
Getting Started
To properly run a Drupal 9 site locally, there are a few steps you need to take:
setup the project structure (using composer)
provision a vm (of your choice)
install Drupal
Acquia provides an open source recommended Drupal project for getting your composer-based project formatted and ready to go. You can use this as a starting point even if you do not host with Acquia. You can start a new project with the following command:
composer create-project --no-interaction acquia/drupal-recommended-project <your project's name>This process should take a couple of minutes (depending on your internet connection and composer version).
Once completed, you should see a folder listing that looks something like this:
As of this point, we have the files that we need for a Drupal 9 site. However we do not have the necessary containers in place to actually run Drupal. So the next step is getting a VM setup!
Provisioning a VM
Choosing a VM solution is not a decision to be undertaken lightly as it can have significant consequences on your team and organization. Having said that, if you’re just doing a one-off it doesn’t really matter (and I’m going to use Lando in this example).
A friendly warning: Drupal VM requires sudo privileges every time you start and stop it. Docker Desktop requires sudo to install, but Lando / DDev / Docksal shouldn’t require sudo every time you start and stop them. So depending on your own level of access on the host machine, this administrative requirement may force you to make a decision.
There are numerous BLT plugins to make adding a VM easier. As I mentioned, I’m going to setup Lando using my blt-lando plugin. Here’s some links to the plugins in question:
Drupal VM: https://github.com/acquia/blt-vm
Whichever route you opt for, you’ll want to composer require the necessary plugin.
composer require mikemadison13/blt-lando Each of these plugins has a command for BLT to start provisioning the VM. For my lando plugin that command is:
blt recipes:vm:lando This command will:
copy the .lando.yml file into your project
automatically setup BLT’s local settings files to work properly with the multi-container model used with Docker
replace the necessary project-specific entries in the .lando.yml file
From here, review the config file and customize as needed (e.g. php version). Then run:
lando startThis command will provision the VMs and take roughly 5 minutes.
Once completed, you should see something like this:
Your app has started up correctly.
Here are some vitals:
NAME drupal9
LOCATION /Users/mike.madison/git/examples/drupal9
SERVICES appserver, database
APPSERVER URLS https://localhost:32779
http://localhost:32780
http://drupal9.lndo.site:8080/
https://drupal9.lndo.site/ All 4 of the URLs should be green. If they aren’t, try restarting Docker Desktop then doing a lando restart.
At this point, we have the necessary files to run Drupal and we have the VM to run it in! Onto the next step which is to actually install Drupal 9 and setup the configuration management strategy.
Installing Drupal 9
BLT sets the minimal install profile by default. You can change this by customizing the blt/blt.yml file. Simply add the following to your blt.yml file to change which profile is installed:
project:
profile:
name: <your profile>Warning: the Standard profile has a known problem right now related to shortcuts and configuration management. I do not advise using this profile.
A couple of other things I recommended at this point are:
create a common module for your project that will installed by default and enabled. This could just be called <your project>_core. It doesn’t need to have anything other than a .info.yml file at this point, but it should be enabled!
Add additional modules as needed for your Drupal 9 build. Here’s a list of the ones I use most commonly. You can just composer require each one of these to add them to the codebase.
Add additional plugins for additional functionality. I recommend adding the https://github.com/acquia/blt-phpcs and https://github.com/acquia/blt-behat plugins via composer.
Do an initial git commit. Make sure you have a gitignore file that is properly structured (BLT should do this automatically). You do not want to commit the vendor directory, any of the docroot/core, etc. files. Here’s an example from the Govcon project.
From here, feel free to do an initial install of Drupal. If everything is working properly, you should be able to just run:
lando blt setupThis initial install of Drupal should be very fast, especially if you are running minimal. Like a minute.
I usually take some time at this point to log into the site (lando drush uli) and enable modules and configure as much as I can. That way, when I setup my stock configuration I’m capturing as much as possible. Make sure to enable the project specific module you created! Again, even if there isn’t anything fancy here now, it may save your bacon in the future if you need to run database updates.
From here you should export your configuration. If you are doing a complete config management dump, this can be done just with:
lando drush cex -yThis will dump all of your configuration out into the config/sync directory (which, in BLT by default is in your repository root in config/default).
I also tend to use the Config Split module and take this opportunity to define my config splits (which also live in the config directory).
If you are doing a partial approach, the setup process will be a little more involved as you may need to create some additional modules to house your configuration.
The end goal here is to have a repository that anyone on your team can pull that has:
common VM config
common drupal configuration
the same versions of all dependencies
Next Steps
From here, you want to push everything you’ve done up to a git repository that everyone on your team can access. Ideally you would also take this opportunity to wire up continuous integration and start towards a deployment into your cloud environment.
Due to the way Drupal manages its UUIDs for configuration, it can be quite painful if you don’t have all the config in sync throughout your application. So taking this initial repo and making sure it
installs cleanly (locally, in CI, etc.)
deploys cleanly (to the cloud, etc.)
updates cleanly (both in the cloud and locally)
may potentially save you some pain!
And really, that’s it. Once you have the container(s) and file system setup and running you should have everything you need. For me, doing this over and over again I’ve gotten the process down to well under an hour. Obviously BLT and its plugins makes a significant dent in that time BUT so does reusing the same basic process and technology on each and every project. So even if you don’t use BLT (and it’s ok if you don’t!) my advice is to hammer out a standard VM solution, CI solution, project template, etc. that you and your team can use for all of your sites. That way you can document the hell out of it and keep everything in sync.
Happy Drupal 9-ing!
Related Content
Get ready for all the exciting changes in the Drupal-verse in 2022! D7 EOL, PHP 7.4 EOL, and D10 release on deck!