CraftQuest Articles

Tutorials, tips, and thoughts on Craft CMS, modern web development, and more.

Image

Local Development of Craft CMS with Nitro

Posted on May 05, 2020 by Ryan Irelan

Reading time: 3 minutes, 33 seconds

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.

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.

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.

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.

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. 

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:

© 2018 Mijingo, LLC