Local Development of Craft CMS with Nitro

This a first look at Nitro, the new local devel­op­ment tool from Pix­el & Tonic.

A few high­lights to get us started:

• Nitro is built on top of Mul­ti­pass, a vir­tu­al­iza­tion engine for Ubun­tu instances. You can run Mul­ti­pass on any machine (Win­dows, macOS, Linux). 
• Nitro is man­aged via the com­mand line inter­face. If you’re not famil­iar with using the com­mand line you can still use Nitro but it might take a lit­tle bit of learning. 
• My video on Nitro cov­ers every­thing you need to know to get start­ed in Nitro and is a good com­pan­ion to this article.

Con­cepts to Know

• Mul­ti­pass — the vir­tu­al­iza­tion engine that run­ss Nitro.
• Machines — the vir­tu­al servers you cre­ate using Nitro.
• Sites — the indi­vid­ual projects in a machine. These are typ­i­cal­ly tied to a project (like a Craft instal­la­tion) and have map­ping asso­ci­at­ed with them to your local project direc­to­ry and a hostname.

Instal­la­tion

Installing Nitro is a 2‑step process. First, you need to install the under­ly­ing tech­nol­o­gy called Mul­ti­pass. Mul­ti­pass is a way to run lin­ux vir­tu­al machines on your Mac, Win­dows, or Lin­ux com­put­er. Nitro is built on top of Multipass.

Installing Mul­ti­pass

The eas­i­est way to install Mul­ti­pass is via the installer pack­age for MacOS or Win­dows. You can also install it with Home­brew, if you’d like. Pick your poison.

To install it using the installer pack­age for your oper­a­tion sys­tem, down­load the appro­pri­ate pack­age and run it.

• Instruc­tions to install on macOS
• Instruc­tions to install on Windows
• Instruc­tions to install on Linux

Once you’ve sucess­ful­ly installed Mul­ti­pass, you can move on to the next step. 

Stuck? Watch my video on the entire process where I cov­er installing Mul­ti­pass on MacOS.

Installing Nitro

With Mul­ti­pass app run­ning, you can now install Nitro. To do that, you need to exe­cute the fol­low­ing com­mand to build your local instal­la­tion for Nitro.

Open your ter­mi­nal appli­ca­tion and run:

curl -sLS http://installer.getnitro.sh | bash

Once Nitro is suc­cess­ful­ly installed, you should see a list of avail­able com­mands. You can always access those com­mands but just run­ning nitro on the com­mand line.

{.img-flu­id}

Cre­at­ing a Nitro Machine

Now that you have Mul­ti­pass and Nitro installed, you can cre­ate your first machine. The machine is a vir­tu­al serv­er that runs Ubun­tu Lin­ux and is how you local­ly host our web­site or web application.

In Nitro, we cre­ate a machine using the nitro inti com­mand. If you don’t pass in a name for the machine using --machine then Nitro will use the default name nitro-dev. Let’s use the default for your first machine:

nitro init

You will be entered into a wiz­ard-style set­up process. Choose the serv­er set­tings you want, includ­ing CPUs, mem­o­ry, disk space, PHP ver­sion, and data­base type. The defaults should be fine for get­ting start­ed. Just be sure to pick the data­base engine you real­ly want. You have to choic­es: MySQL and Postgresql. 

Once you com­plete the wiz­ard it kicks off a pro­vi­sion­ing process for the machine. 

The first time you run this Mul­ti­pass and Nitro need to down­load OS images and oth­er sup­port­ing soft­ware and build the machine. This can take a while, so be patient.

Once the machine is com­plete­ly done build­ing you should see some out­put with details of the machine, like IP address, and configuration.

{.img-flu­id}

Take note of the IP address because you’ll need it lat­er when you want to access the data­base serv­er to cre­ate a data­base for the project.

Adding a Site to Nitro

The next step is to add a site to Nitro. A site con­sists of a map­ping to a project direc­to­ry, its pub­lic direc­to­ry, and a host­name that is point­ed to the IP address of the machine.

Just like when you cre­at­ed the machine, you get a nice wiz­ard style process that makes it easy to con­fig­ure the site.

{.img-flu­id}

The first step is to go to the project that you want to host using Nitro. This could an exist­ing project or a new instal­la­tion of Craft.

Choose your own adventure:

Using Nitro with a New Instal­la­tion of Craft

To use Nitro with a new instal­la­tion of Craft, first cd into the project directory.

cd my-project

If you haven’t already cre­at­ed a new com­pos­er project using composer create-project then do that now.

composer create-project craftcms/craft .

This will install Craft into your cur­rent work­ing directory.

After the Com­pos­er create-project is com­plete, if you run ls you should be in the root of the project and see a bunch of files and direc­to­ries, includ­ing the web directory.

Now we can add add the site to Nitro.

nitro add

This also presents you with a wiz­ard-style set­up process. Spec­i­fy the host­name you want (I like to use project-name.test), the pub­lic direc­to­ry (the default web is what you want), and then apply those changes to the con­fig file.

This will cre­ate a map­ping between your local file sys­tem and the Nitro machine. At the end of the process Nitro will prompt you for your sys­tem admin pass­word so it can update your hosts file.

Now access the host­name in your brows­er to con­firm that it is work­ing. You’ll see a 503 error because Craft isn’t com­plete­ly set­up yet and is miss­ing a data­base con­nec­tion. Let’s fix that.

Remem­ber the IP address I sug­gest­ed you remem­ber? You’ll need that now.

Nitro doesn’t cre­ate a data­base for you, so you’ll need to do that on your own. Using your favorite data­base tool, con­nect to the Nitro serv­er using these credentials:

• 192.168.x.x (what­ev­er your Nitro machine IP address is)
• user: nitro
• pass­word: nitro

Cre­ate a data­base named some­thing you’ll remem­ber and then con­tin­ue to the next step!

Now we can run the Craft setup com­mand to fin­ish installing our new Craft project. 

./craft setup

When you’re prompt­ed for you data­base cre­den­tials then input localhost for the serv­er con­nec­tion (IP address isn’t need­ed for this), user­name nitro, pass­word nitro and the data­base name you cre­at­ed a few min­utes ago.

Now you’re run­ning Craft on Nitro! 🚀

Using Nitro with an Exist­ing Craft Project

To use Nitro with a new instal­la­tion of Craft, first cd into the project direc­to­ry that you want to move to Nitro.

cd my-project

Now we can add add the site to Nitro.

nitro add

This also presents you with a wiz­ard-style set­up process like you had before when we cre­at­ed the machine. Spec­i­fy the host­name you want (I like to use project-name.test), the pub­lic direc­to­ry (the default web is what you want), and then apply those changes to the con­fig file.

This will cre­ate a map­ping between your local file sys­tem and the Nitro machine. At the end of the process Nitro will prompt you for your sys­tem admin pass­word so it can update your hosts file.

Now access the host­name in your brows­er to con­firm that it is work­ing. You might see an error because we haven’t update the Craft i is miss­ing a data­base con­nec­tion. We’ll fix that in a minute.

Export­ing Project Database

You need to move the project data­base from the cur­rent local­host data­base serv­er to the new Nitro serv­er. Export your project data­base. This can be done through a data­base tool or via the Craft Con­trol Pan­el (Util­i­ties > Data­base Backup).

Once you have the data­base dump file, make sure it’s in your project root. Now we’ll use a handy Nitro tool to import the database:

nitro import yourdatabasefile.sql

A wiz­ard prompt will dis­play con­firm­ing the data­base engine you want to import into. If you have mul­ti­ple Nitro machines run­ning you will have to spec­i­fy the machine:

nitro import yourdatabasefile.sql --machine craftquest-dev

Fol­lowed the prompts to import the data­base dump into the data­base you just created. 

{.img-flu­id}

With your data­base import­ed, now you can update your Craft project’s data­base con­nec­tion infor­ma­tion. Go into your project’s .env file and update the data­base cre­den­tials to use:

• local­host
• user: nitro
• pass­word: nitro
• data­base­name

Access the site in the web brows­er using the host­name you set up and your site should load just as it did before! Except now it’s run­ning on Craft Nitro. 🚀

Learn­ing More About Nitro

If you want to learn more about Nitro, check out these resources:

• CraftQuest video on using Nitro for Craft local­host­ing.
• Dev​mode​.fm Episode on Nitro (with Pix­el & Tonic)
• Offi­cial Nitro Page and Documentation