Dockerize Local Bedrock & Sage Development with Lando

I’ve been pretty obsessed with using Docker for local development lately. I love how fast and lightweight it is and how I can run software versions that I don’t need to have installed locally — avoiding the mess that that can make of your system. Docker is awesome, however, if you’ve ever used Docker, you know that starting out it can be a bit of a challenge since there’s a bit of a learning curve — but don’t let that stop you from dockerizing your development workflow!

Meet Lando

Lando Calrissian: “Hello. What have we here?” (from Star Wars: The Empire Strikes Back)

Lando is a free, open source, cross-platform, local development environment and DevOps tool built on Docker container technology.

Lando’s goal is to enable developers to easily serve their websites locally with Docker. With a default WordPress project, including Lando is as easy as running lando init --recipe wordpress, but with Bedrock we need to add a bit of extra configuration to account for the modifications it makes to the default WordPress structure. At the same time, we’ll add what we need to allow us to use Sage as well.

Modifying Lando’s WordPress recipe to work with Bedrock

To start, we’ll create .lando.yml in the root of our Bedrock project:

name: bedrock
recipe: wordpress
  nginx:              # Optional: if you exclude this, Lando will serve it as
    - bedrock.test
  theme:              # Optional: add this if you include the Sage specific config down below
    - localhost:3000
  php: '7.2'
  via: nginx
  webroot: web
  database: mariadb
  xdebug: true

# Add the following if you plan to use Sage as a starter theme
    type: node
        - 3000:3000
    service: theme

Since we are using Lando for development, we are enabling Xdebug. Also, we use MariaDB for a database, NGINX for a web server, and PHP 7.2 in an attempt to stay close to the server environment that Trellis provides.

Add the (optional) custom hostname to your hosts file

If you’ve chosen to use a custom hostname like the config above, you will need to add the following to your hosts file:

# /etc/hosts    bedrock.test

As nice as it is to use our own hostname, this extra bit of setup can feel a bit cumbersome. Using the default domain extension may be a bit more convenient (similar to what Laravel Valet does with the .test TLD) and if you’d like, you can set the default TLD Lando uses to whatever you’d like with a bit of extra work.

Important: in order for Lando to use our custom hostname without using an alternative port (8000), we will need to make sure nothing is running on port 80. If you also have Laravel Valet installed, you will need to shut it down since it uses port 80. You can do this by running valet stop. After Valet is shutdown, you will need to make sure Lando’s proxy container is restarted as well. You can do this by running lando poweroff and then lando start when you start your project.

Set Bedrock’s environment variables for Lando

Make sure the following environment variables are set:

# .env


Make sure to remove the salts from the .env file as Lando does not know how to process them.

🔥 Tip: If you are using Lando in tandem with an existing Trellis install, you can use enveigle to template the development .env. You still will need to change the DB_* values and WP_HOME to reflect the values above, but anything extra you’ve included in your development vault (like plugin licenses) will be all ready in your new .env.

Start Lando

Once all of that is in place, we can go ahead and start Lando:

$ lando start

Now, we’ve got ourselves a lightweight, tangle-free local development environment! Here are a few commands to run a few Bedrock related tasks inside the containers:

# Install your site's dependencies/plugins
$ lando composer install

# Update your site's dependencies/plugins
$ lando composer update

# Add a new plugin
$ lando composer require wpackagist-plugin/html-forms

# Export the WordPress database
$ lando wp db export

Theme development with Sage

Since we’re already using Bedrock, we probably want to use Sage too.™ Create a new Sage project by running the following:

# @ web/app/themes
$ lando composer create-project roots/sage sage

As we run through the Sage installer, make sure to set the development URL to http://appserver_nginx.bedrock.internal (i.e. appserver_<service>.<app>.internal). Since we will be running Sage’s dev server within the container, we need to use the nginx container’s internal URL.

Once the installer completes, we will need to install Sage’s Node dependencies. For this, run:

# @ web/app/themes/sage
$ lando yarn

Now we need run an initial build of the frontend assets:

# @ web/app/themes/sage
$ lando yarn build

At this point, we’re ready to activate Sage. We can do this with WP-CLI:

$ lando wp theme activate sage/resources

Finally, we’re ready to start development:

# @ web/app/themes/sage
$ lando yarn start

Now navigate to http://localhost:3000 and you should see Sage ready for development in a Browsersync session. And that’s it: dockerized Bedrock + Sage development courtesy of Lando!

Lando Calrissian: “You look absolutely beautiful.” (from Star Wars: The Empire Strikes Back)

🎩 Thanks to @wdeer on Roots Discourse for helping make this guide compatible up to Lando 3 RC 13.

Join the discussion on Roots Discourse

Help support our open-source development efforts

Help us grow

Join over 7,800+ subscribers on our newsletter to get the latest Roots updates, along with occasional tips on building better WordPress sites.

Looking for WordPress plugin recommendations, the newest modern WordPress projects, and general web development tips and articles?

“Easily the best WordPress email I get.” Colin OBrien

Follow us on Twitter @rootswp

Ready to checkout?