Craft Nitro

Nitro is a speedy local development environment that’s tuned for Craft CMS, powered by Multipass.

• What’s Included
• Installation
  • Uninstalling Nitro
• Adding Sites
  • Adding a site with nitro add
  • Mounting your entire dev folder at once
• Connecting to the Database
• Adding Mounts
• Running Multiple Machines
• Adding Multiple Database Engines
• Using Xdebug
• Commands
  • apply
  • add
  • context
  • destroy
  • edit
  • info
  • init
  • import
  • logs
  • remove
  • redis
  • start
  • stop
  • rename
  • restart
  • self-update
  • ssh
  • update
  • version
  • xdebug configure
  • xdebug on
  • xdebug off

---

What’s Included

Nitro installs the following on every machine:

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

Installation

⚠️ Note: Windows support is a work-in-progress.

1. Install Multipass (requires 1.2.0+).

2. Run this terminal command:

   bash <(curl -sLS http://installer.getnitro.sh)

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.

Uninstalling Nitro

To completely remove Nitro, first destroy your machine:

nitro destroy

💡 Tip: If you have multiple machines, you can destroy them all using the multipass delete command:

multipass delete --all -p

Then remove your nitro command:

sudo rm /usr/local/bin/nitro

You can optionally remove your machine configs as well:

rm -rf ~/.nitro

If you wish to uninstall Multipass as well, uninstall instructions can be found on the installation guide for your platform:

• macOS
• Windows
• Linux

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? [plugins-dev] example.test
Where is the webroot? [web]
plugins-dev has been added to config file.
Apply changes from config? [yes]
Applied changes from /Users/jasonmccallister/.nitro/nitro-dev.yaml
Editing your hosts file
Password: ******
example.test added successfully!

Mounting your entire dev folder at once

If you manage all of your projects within a single dev folder, you can mount that entire folder once within Nitro, and point your sites’ webroots to the appropriate folders within it.

To do that, open your ~/.nitro/nitro-dev.yaml file in a text editor (or run the edit command), and add a new mount for the folder that contains all of your projects, plus list out all of your sites you wish to add to Nitro within that folder:

mounts:
 - source: ~/dev
   dest: /nitro/dev
sites:
 - hostname: example1.test
   webroot: /nitro/dev/example1.test/web
 - hostname: example2.test
   webroot: /nitro/dev/example2.test/web

Then run nitro apply to apply your nitro.yaml changes to the machine.

💡 Tip: To avoid permission issues, we recommend you always mount folders into /nitro/* within the machine.

⚠️ Warning: If your projects contain any symlnks, such as path Composer repositories, those symlinks must be relative (../), not absolute (/ or ~/).

Connecting to the Database

To connect to the machine from a Craft install, set the following environment variables in your .env file:

DB_USER="nitro"
DB_PASSWORD="nitro"

To connect to the database from your host operating system, you’ll first need to get the IP address of your Nitro machine. You can find that by running the info command.

$ nitro info
Name:           nitro-dev
State:          Running
IPv4:           192.168.64.2
Release:        Ubuntu 18.04.4 LTS
Image hash:     2f6bc5e7d9ac (Ubuntu 18.04 LTS)
Load:           0.71 0.74 0.60
Disk usage:     2.7G out of 38.6G
Memory usage:   526.4M out of 3.9G

Then from your SQL client of choice, create a new database connection with the following settings:

• Host: The IPv4 value from nitro info
• Port: The port you configured your database with (3306 for MySQL or 5432 for PostgreSQL by default).
• Username: nitro
• Password: nitro

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.)

Adding Multiple Database Engines

To run multiple database engines on the same machine, open your ~/.nitro/nitro-dev.yaml file in a text editor (or run the edit command), and list additional databases under the databases key:

databases:
 - engine: mysql
   version: "5.7"
   port: "3306"
 - engine: mysql
   version: "5.6"
   port: "33061"
 - engine: postgres
   version: "11"
   port: "5432"

⚠️ Warning: Each database engine needs its own unique port.

Then run nitro apply to apply your nitro.yaml changes to the machine.

Using Xdebug

See Using Xdebug with Nitro and PhpStorm for instructions on how to configure Xdebug and PhpStorm for web/console debugging.

Commands

The following commands will help you manage your virtual server.

• apply
• add
• context
• destroy
• edit
• info
• init
• import
• logs
• remove
• redis
• rename
• 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? [plugins-dev]
Where is the webroot? [web]
plugins-dev has been added to config file.
Apply changes from config? [yes]
Applied changes from /Users/jasonmccallister/.nitro/nitro-dev.yaml
Editing your hosts file
Password: ******
plugins-dev 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.

--clean

Remove the configuration file after destroying the machine. Defaults to `false`

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

💡 Tip: If you’re running macOS or Linux, you can set an EDITOR environment variable in ~/.bash_profile to your preferred text editor of choice.

export EDITOR="/Applications/Sublime Text.app/Contents/MacOS/Sublime Text"

After adding that line, restart your terminal or run source ~/.bash_profile for the change to take effect.

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.

rename

Rename a site in a configuration file. Will prompt for which site to rename.

nitro rename [<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