Craft Nitro 2 first look: How to quickly set up a local Craft CMS dev site

Introduction

We previously tried out Craft Nitro when version 1.0 was released. Due to the tool's reliance on the Multipass virtualization technology, we didn't get very far. We ended up recommending DDEV to run a local Craft site instead. However, with the release of version 2.0, Craft Nitro has become an even more viable option. Here we like to show you how to:

1. Get Craft Nitro 2 up and running on your machine.
2. Use Nitro to run existing or new Craft sites.

Nitro 2 and Craft Copy: not ready to be best friends, at least not yet 😢

We had hoped to also be able to show you how to use fortrabbit's Craft Copy tool with Nitro to sync your Craft site to your fortrabbit Apps. Unfortunately, that's not currently possible due to some limitations in the environment Nitro provides. You can read more about why at the end of this article.

The Craft Nitro 2 development tool

Made by Pixel & Tonic - the people behind Craft CMS - Craft Nitro 2 is:

• A Docker-based command-line tool for local development.

• Meant to be easy to setup and use.

• Unlike most other dev tools, Craft Nitro 2 is specifically geared towards Craft CMS development.

Installation requirements

Craft Nitro 2 sits on top of Docker and works on macOS, Linux, and Windows. The installation will be shown for macOS, using the Homebrew package manager. To install on Linux you can also use Homebrew; the steps will be almost identical. The same works for Windows, provided your system has the Windows Subsystem for Linux (WSL) installed. For this installation procedure, you will need:

1. Basic knowledge of the command line.

2. The Homebrew package manager installed.

   ↳ Install Homebrew on macOS

   ↳ Install Homebrew on Linux or Windows Subsystem for Linux

We've completed installation using the following software / package versions:

Install Craft Nitro 2 to power your local Craft CMS dev sites

The first step is to install Docker Desktop. If you already have Docker installed you can skip this bit. At the time of writing, the minimal supported Docker version is 3.0. Make sure to check the official Craft Nitro 2 installation requirements for up-to-date instructions.

1. Let's go ahead and install Docker Desktop:

   # install Docker Desktop
   brew cask install docker

2. Once we have Docker installed we need to launch the app at least once to complete the configuration.

   # make sure to run the Docker App once before proceeding!
   open /Applications/Docker.app/

3. Next, we install Craft Nitro 2:

   # install Craft Nitro 2
   brew install craftcms/nitro/nitro

If you're using a different operating system, or are uncomfortable using brew, check the official Craft Nitro 2 installation instructions to find alternative means of installing Craft Nitro 2.

Things to consider before setting up Craft Nitro 2

Having installed Docker and Craft Nitro 2, we continue by initializing Nitro. The initialization procedure is interactive; we'll be asked to make a few basic choices, such as which database(s) to use. The choices made during initialization are saved in the '.nitro/nitro.yaml' file inside the user's home directory. As such, Craft Nitro 2 settings are user account-specific.

Before we can get started, we need to answer a couple of questions:

1. Do you have another dev tool installed on your machine?

   Nitro's default settings require ports 80 and 443 to be available. If another dev tool, such as DDEV or Lando, is already installed these ports will likely be taken. In this case, we'll have to use custom ports for Nitro.

2. Are you working under an account with admin privileges?

   Nitro wants to edit the hosts file when initializing. This requires sudo privileges, so initialization needs to be run as an admin user.

   A standard macOS user account has admin privileges enabled. However, recommended best practice is to work under a non-admin account. If you're not working as an admin user, you'll need to turn off host file editing and add the hosts file entries yourself.

Initializing Craft Nitro 2

For this installation procedure, we'll assume that we're on a machine:

• with other dev tool(s) installed,
• working as a user with admin privileges.

Before starting the initialization, we'll set custom ports for Craft Nitro 2. We'll also explicitly tell Nitro to use the '.nitro' top-level-domain (TLD) for its local host names. We apply these customizations by setting a few Craft Nitro 2 environment variables to appropriate values. To do so, we copy the following commands into a terminal and run them:

# set environment variables
export NITRO_HTTP_PORT='8080'
export NITRO_HTTPS_PORT='8443'
export NITRO_DEFAULT_TLD='nitro'
# uncomment next line to turn off hosts file editing
# export NITRO_EDIT_HOSTS='false'

# initialize Craft Nitro 2
nitro init

Once the environment variables have been set, we continue to initialize Craft Nitro 2. Again we're asked to make a number of choices. These will depend on your specific setup; we've documented ours here:

Set up a local Craft CMS dev site with Craft Nitro 2

In this section we'll show how to set up a fresh Craft CMS site with Craft Nitro 2 for local development. In case you want to use Nitro to power an existing Craft CMS dev site, please refer to the section using Craft Nitro 2 with an existing Craft CMS installation below.

We'll use the 'nitro create' command to set up a local Craft CMS dev site. This command uses Composer inside the container, so there's no need to have Composer installed locally — nice! Please refer to the official Craft CMS installation guide for other means of installing. We'll kick of creation of our new Craft CMS site via the following command:

# create a new Craft CMS dev site on the Desktop
cd ~/Desktop && nitro create fortrabbit

The 'nitro create' command runs interactively, presenting us with a set of choices. We've documented ours here:

After creation, a new container for our site should be up and running. We can test this by issuing the 'nitro ls' command. This command lists all running Nitro containers along with their status.

Let's continue by setting up Craft CMS. To do so, we'll log into the site's container and run the Craft CMS setup from there. Since we asked Craft Nitro 2 to update the site's .env file, we want to use those settings. Use the following set of commands to get your site set up.

Make sure to adapt the settings underneath ">>> provide your site settings here <<<" to suit your needs. We recommend you copy-paste each commented block of code into your terminal and run them there.

# log into the container
nitro ssh fortrabbit

# make sure we're in the correct directory
cd /app/

# load existing settings from .env file
source .env

# run Craft CMS database setup in non-interactive mode
# using settings loaded from .env
./craft setup/db --interactive=0 --driver='mysql' --server="$DB_SERVER" --port="$DB_PORT" --database="$DB_DATABASE" --user="$DB_USER" --password="$DB_PASSWORD"

# >>> provide your site settings here <<<
adminEmail='craftadmin@fortrabbit.nitro'
adminUser='craftadmin'
adminPassword=$(openssl rand -base64 32)
siteName='fortrabbit Craft Nitro'
siteUrl="http://fortrabbit.nitro:8080"

# install Craft CMS in non-interactive mode
./craft install --interactive=0 --email="$adminEmail" --username="$adminUser" --password="$adminPassword" --siteName="$siteName" --siteUrl="$siteUrl" && printf "\n- Your password for user '${adminUser}' is:\n\n${adminPassword}\n\n-Your site should be live at:\n\n${siteUrl}\n\n" && exit

A couple things to note:

• We've initialized Craft Nitro 2 using custom ports.

  We need to append the port number to the site URL: http://fortrabbit.nitro:8080/. Otherwise, our site won't load.

• We've used the settings stored in the .env file.

  For debugging, we can print out those settings while inside the container by issuing a 'cat /app/.env' command.

Our site should now load in the browser — make sure to test it works!

Use Craft Nitro 2 to power an existing Craft CMS dev site

Maybe you'd like to run an existing Craft CMS project via Craft Nitro 2. In this case, we'll use the 'nitro add' command instead of 'nitro create':

1. Go to your local Craft CMS project directory:

   cd <craft-project-dir>

2. Add the site to Craft Nitro 2:

   nitro add .

   Here, we're given a similar set of choices as for the 'nitro create' command. You may find our choices in the section on setting up a new Craft CMS site.

3. Import your local database backup:

   nitro db import <path-to-your-SQL-backup>

Craft Nitro 2 and Craft Copy

Over the years, fortrabbit has contributed to the Craft CMS ecosystem. We've published plugins, guides and blog posts. The latest exciting development is fortrabbit's own Craft Copy tool. Craft Copy syncs all components of a Craft site, up and down. This includes your custom code, as well as assets, database contents and the Craft CMS code. As an added bonus, Craft Copy supports advanced use cases, such as multiple staging environments.

We previously showed how to integrate Craft Copy with DDEV. Naturally, we attempted to do the same with Craft Nitro 2. Unfortunately, here we ran into an issue. Craft Copy uses Git and Rsync with SSH keys under the hood. To use the tool, one needs to install the SSH keys associated with your fortrabbit account within the container. To our surprise, Craft Nitro 2 lacks the capability to import SSH keys from the host machine — see this GitHub issue. It also does not have the other dependencies (ssh, rsync, zcat) available inside its container that Craft Copy needs in order to work.

At time of writing, the only way to use Craft Copy with Craft Nitro 2 is to run Craft Copy from outside the container. But this is not preferred: using the tool outside the container requires its dependencies to be installed on the user's local machine. Such an approach opens the door for version conflicts and similar headaches. Certainly not something we want to recommend.

That said, Pixel & Tonic have a great track record of responding to demand from the Craft CMS community, so it's possible they will update Nitro in future to allow better integration with other tools. If this is something you'd like to see, consider letting them know.

Conclusion

A fair share of fortrabbit's client base use our infrastructure to host their Craft CMS sites. This includes less technically-minded folks, for whom setting up a local dev sites is a real challenge. So we'd love to have a single, integrated solution to recommend. Initially, Craft Nitro 2 looks really promising in this regard.

Craft Nitro 2 ships with a handful of useful commands, including 'nitro composer', 'nitro php', 'nitro craft', and 'nitro npm'. These allow us to issue composer, php, craft, and npm commands inside the container. This absolves the user of the responsibility of installing and maintaining these tools on their own machine. Instead, the dependencies live inside the container. We love it, as that reduces the surface area for version conflicts and related confusion.

While Craft Nitro 2 does a good job at quickly getting a local Craft CMS dev site up and running, when it comes to the more sophisticated aspects of Craft CMS development, DDEV still pulls ahead.

We really hope to see Host SSH key support added to Craft Nitro 2 soon. When that happens we'll be happy to give it another shot. For now, we'll continue to recommend DDEV to our clients as the go-to solution for local Craft CMS development.

Summing up, here are some of the strong points of Craft Nitro 2 and DDEV compared: