Craft Nitro

Nitro is a command-line tool focused on making local Craft development quick and easy. Nitro’s one dependency is Multipass, which allows you to create Ubuntu virtual machines.

• What’s Included
• Installation
• Adding Sites
• Adding Mounts
• Running Multiple Machines
• Commands

---

What’s Included

Nitro installs the following on every machine:

• PHP 7.4 (+ option to use 7.3, 7.2, 7.1, 7.0)
• MySQL
• PostgreSQL
• Redis
• Xdebug
• Blackfire

Note: For a more detailed writeup on how to configure Xdebug and Nitro with PhpStorm, view this document on how to configure Xdebug and PhpStorm for both web and console debugging.

Installation

1. Install Multipass (requires 1.2.0+).

2. Run this terminal command:

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

3. Follow the prompts to create your machine.

Once complete, you will have a Multipass machine called nitro-dev, and a new configuration file for the machine stored at ~/.nitro/nitro-dev.yaml.

Adding Sites

To add a site to Nitro, three things need to happen:

• Your project files need to be mounted into the Nitro machine.
• The web server within your Nitro machine needs to be configured to serve your site.
• Your system’s hosts file needs to be updated to associate your site’s hostname with Nitro.

Add a site with nitro add

If your project files are completely contained within a single folder, then you can quickly accomplish these using the add command:

$ cd /path/to/project
$ nitro add
→ What should the hostname be? $ example.test
→ Where is the webroot? $ web
✔ example.test has been added to nitro.yaml.
→ apply nitro.yaml changes now? $ yes
✔ Applied the changes and added example.test to nitro-dev                  
Adding nitro-dev to your hosts file 
Password:
✔ example.test added successfully!

Add a site manually

If you would prefer to add a site manually, follow these steps:

1. Open your ~/.nitro/nitro-dev.yaml file in a text editor, and add a new mount and site to it:

   mounts:
    - source: /path/to/project
      dest: /nitro/sites/example.test
   sites:
    - hostname: example.test
      webroot: /nitro/sites/example.test/web 
   

2. Run nitro apply to apply your nitro.yaml changes to the machine. You will be prompted for your password so Nitro can add the new hostname to your system’s hosts file.

You should now be able to point your web browser at your new hostname.

Adding Mounts

Nitro can mount various system directories into your Nitro machine. You can either mount each of your projects’ root directories into Nitro individually (as you’d get when adding a site with nitro add), or you can mount your entire development folder, or some combination of the two.

To add a new mount, follow these steps:

1. Open your ~/.nitro/nitro.yaml file in a text editor, and add the new mount:

   mounts:
     - source: /Users/cathy/dev
       dest: /nitro/dev
   

2. Run nitro apply to apply the nitro.yaml change to the machine.

Once that’s done, yous should be able to tunnel into your machine using the ssh command, and see the newly-mounted directory in there.

Running Multiple Machines

You can have Nitro manage more than just your primary machine (nitro-dev) if you want. For example, you could create a machine for a specific dev project.

To create a new machine, run the following command:

$ nitro init -m <machine>

Replace <machine> with the name you want to give your new machine. Machine names can only include letters, numbers, underscores, and hyphen.

This command will run through the same prompts you saw when creating your primary machine after you first installed Nitro. Once it’s done, you’ll have a new Multipass machine, as well as a new configuration file for it at ~/.nitro/<machine>.yaml.

All of Nitro’s commands accept an -m option, which you can use to specify which machine the command should be run against. (nitro-dev will always be used by default.)

Commands

The following commands will help you manage your virtual server.

• apply
• add
• context
• destroy
• edit
• info
• init
• import
• logs
• remove
• redis
• restart
• self-update
• ssh
• start
• stop
• update
• version
• xdebug configure
• xdebug on
• xdebug off

apply

Ensures that the machine exists, and applies any changes in its config file to it.

nitro apply [<options>]

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

Example:

$ nitro apply
There are 2 mounted directories and 1 new mount(s) in the config file.
Applied changes from nitro.yaml.

add

Adds a new site to the machine.

nitro add [<options>]

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

--hostname

The hostname to use for accessing the site. If not passed, the command will prompt for it.

--webroot

The relative path to the site’s webroot. If not passed, the command will prompt for it.

Example:

$ cd /path/to/project
$ nitro add
→ What should the hostname be? $ example.test
→ Where is the webroot? $ web
✔ example.test has been added to nitro.yaml.
→ apply nitro.yaml changes now? $ yes
✔ Applied the changes and added example.test to nitro-dev                  
Adding nitro-dev to your hosts file 
Password:
✔ example.test added successfully!

context

Shows the machine’s configuration.

nitro contex [<options>]

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

Example:

$ nitro context
Machine: nitro-dev
------
php: "7.4"
cpus: "1"
disk: 40G
memory: 4G
mounts:
- source: ~/sites/demo-site
  dest: /nitro/sites/demo-site
databases:
- engine: mysql
  version: "5.7"
  port: "3306"
- engine: postgres
  version: "12"
  port: "5432"
sites:
- hostname: demo-site
  webroot: /nitro/sites/demo-site/web
------

destroy

Destroys a machine.

nitro destroy [<options>]

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

edit

Edit allows you to quickly open your machine configuration to make changes. However, it is recommended to use nitro commands to edit your config.

nitro edit [<options>]

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

Example:

nitro edit

info

Shows the running information for a machine like the IP address, memory, disk usage, and mounts.

nitro info [<options>]

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

Example:

$ nitro info
Name:           nitro-dev
State:          Running
IPv4:           192.168.64.48
Release:        Ubuntu 18.04.4 LTS
Image hash:     2f6bc5e7d9ac (Ubuntu 18.04 LTS)
Load:           0.09 0.15 0.22
Disk usage:     2.7G out of 38.6G
Memory usage:   379.8M out of 3.9G
Mounts:         /Users/jasonmccallister/sites/demo-site => /nitro/sites/demo-site
                    UID map: 501:default
                    GID map: 20:default

init

Initializes a machine.

nitro init [<options>]

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

--php-version

The PHP version to use. If not passed, the command will prompt for it.

--cpus

The max number of CPUs that the machine can use. If not passed, one CPU will be used by default.

--memory

The max amount of system RAM that the machine can use. If not passed, the command will prompt for it.

--disk

The max amount of disk space that the machine can use. If not passed, the command will prompt for it.

If the machine already exists, it will be reconfigured.

import

Import a SQL file into a database in the machine. You will be prompted with a list of running database engines (MySQL and PostgreSQL) to import the file into.

nitro import <file> [<options>]

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

Example:

$ nitro import mybackup.sql
Use the arrow keys to navigate: ↓ ↑ → ← 
? Select database:
  ▸ mysql_5.7_3306

logs

Views the machine’s logs. This command will prompt you for a type of logs to view, including e.g. nginx, database, or docker (for a specific container).

nitro logs [<options>]

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

remove

Removes a site from the machine.

nitro remove [<options>]

You will be prompted to select the site that should be removed. If the site has a corresponding mount at /nitro/sites/<hostname>, the mount will be removed as well.

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

redis

Starts a Redis shell.

nitro redis [<options>]

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

start

Starts the machine.

nitro start [<options>]

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

stop

Stops the machine.

nitro stop [<options>]

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

restart

Restarts a machine.

nitro restart [<options>]

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

self-update

Perform updates to the Nitro CLI.

nitro self-update

ssh

Tunnels into the machine as the default ubuntu user over SSH.

nitro ssh [<options>]

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

update

Performs system updates (e.g. sudo apt get update && sudo apt upgrade -y).

nitro update [<options>]

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

version

Checks the currently version of nitro against the releases and shows any updated versions.

nitro version

xdebug configure

Configures Xdebug for remote access and debugging with PhpStorm or other IDEs.

nitro xdebug configure [<options>]

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

--php-version

The PHP version to configure Xdebug for

xdebug on

Enables Xdebug, which is installed and disabled by default on each machine.

nitro xdebug on [<options>]

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

--php-version

The PHP version to enable Xdebug for

This ensures Xdebug is installed for PHP 7.3 and enables it:

xdebug off

Disables Xdebug on a machine.

nitro xdebug off [<options>]

Options:

-m, --machine

The name of the machine to use. Defaults to nitro-dev.

--php-version

The PHP version to disable Xdebug for