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.

Install Multipass (requires 1.2.0+).

Run this terminal command:

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

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:

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:

Open your ~/.nitro/nitro.yaml file in a text editor, and add the new mount:
```
mounts:
  - source: /Users/cathy/dev
    dest: /nitro/dev
```
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

thegodshatetexas / nitro

Craft Nitro

What’s Included

Installation

Uninstalling Nitro

Adding Sites

Add 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`

About

Languages

Craft Nitro

What’s Included

Installation

Uninstalling Nitro

Adding Sites

Add 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

About

Languages

Add a site with `nitro add`

`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`