Setting up sites and working with databases after you’ve installed Nitro.
# Setting Up Sites
Nitro needs a few things in order to set up a site:
- A container needs to be added to serve your site.
- The container has to mount a local folder with your sites code.
- Your system’s
hostsfile needs to be updated to associate your site’s hostname with Nitro.
# Adding a Site with
You can navigate to an existing project folder and add a site for it using the
$ cd /path/to/project $ nitro add Adding site… Enter the hostname [mysite.test]: ✓ setting hostname to mysite.test ✓ adding site ~/dev/support/mysite.test Enter the web root for the site [web]: ✓ using web root web Choose a PHP version: 1. 8.0 2. 7.4 3. 7.3 4. 7.2 5. 7.1 6. 7.0 Enter your selection: 2 ✓ setting PHP version 7.4 … saving file ✓ Site added 🌍 Apply changes now [Y/n]? y Checking network… ✓ network ready Checking proxy… ✓ proxy ready Checking databases… … checking mysql-8.0-3306.nitro ✓ … checking postgres-13-5432.nitro ✓ Checking mounts… … checking ~/dev/craftcms/cms-3 ✓ Checking services… … checking mailhog service ✓ Checking sites… … checking mysite.test ✓ Checking proxy… … updating proxy ✓ Modifying hosts file (you might be prompted for your password) Adding sites to hosts file… … modifying hosts file ✓ Nitro is up and running 😃
# Creating a New Site with
By default it sets up a Craft CMS project just like you’d get running
composer create-project craftcms/craft my-project to get a fresh Craft installation.
Below we’ll install Craft in a new
tutorial/ directory with
tutorial.nitro as its hostname:
$ nitro create tutorial Downloading https://github.com/craftcms/craft/archive/HEAD.zip ... … setting up project ✓ New site downloaded 🤓 Enter the hostname [tutorial.nitro]: ✓ setting hostname to tutorial.nitro ✓ adding site ~/dev/tutorial Enter the web root for the site [web]: ✓ using web root web Choose a PHP version: 1. 8.0 2. 7.4 3. 7.3 4. 7.2 5. 7.1 6. 7.0 Enter your selection: 1 ✓ setting PHP version 8.0 Add a database for the site [Y/n] Select the database engine: 1. mysql-8.0-3306.database.nitro 2. postgres-13-5432.database.nitro Enter your selection: 2 Enter the new database name: tutorial … creating database tutorial ✓ Database added 💪 Should we update the env file? [Y/n] y .env updated! … checking /Users/oli/dev/tutorial/composer.json ✓ No lock file found. Updating dependencies instead of installing from lock file. Use composer update over composer install if you do not have a lock file. Loading composer repositories with package information Updating dependencies Lock file operations: 87 installs, 0 updates, 0 removals # removed for brevity
nitro create performs the following steps:
- Creates a project using the latest
craftcms/craft(opens new window) boilerplate from GitHub.
- Creates the
tutorialdirectory and copies the
craftcms/craftcontents into it.
- Prompts for the new Nitro site’s hostname.
- Prompts for the site’s PHP version.
- Prompts for database creation. If you choose to create a database, you’ll be prompted for its name and Nitro will offer to update the
.envdatabase settings automatically.
- Installs Composer dependencies using
- Prompts you to run
nitro applyin order to update Nitro’s settings and your hosts file.
If you’re installing Craft, don’t forget to run the setup wizard with
nitro craft setup after
nitro create has finished!
You can pass your own repository to
nitro create and use that as the scaffold:
nitro create https://github.com/craftcms/demo my-project
# Mounting Your Entire Development Folder
If you manage all your projects within a single dev folder, you can mount that folder once within Nitro and point each site’s web root to the relevant sub-directory within it.
~/.nitro/nitro.yaml file in a text editor (or run the
edit command), and add sites that each point their
path setting to your dev folder.
Pretend you use a
dev directory that lives in your home folder, with each project in a subdirectory:
~/dev ├── happy-lager │ ├── ... │ └── web ├── spoke-and-chain │ ├── ... │ └── web └── starter-blog ├── ... └── web
You can point to the dev folder for every site’s
path, with a specific
webroot for each one:
sites: - hostname: happylager.nitro path: ~/dev webroot: happy-lager/web version: "7.4" xdebug: false - hostname: spokeandchain.nitro path: ~/dev webroot: spoke-and-chain/web version: "7.4" xdebug: false - hostname: starterblog.nitro path: ~/dev webroot: starter-blog/web version: "7.4" xdebug: false
nitro apply to apply your
If you have a large number of files in the development folder, it may be more performant to mount sites individually using
If your projects contain any symlinks, such as
path Composer repositories, those symlinks must be relative (
../), not absolute (
# Adding Site Aliases
If you need a given site to have more than one domain name associated with it, as you might with a multi-site Craft install for example, you can add any number of domain aliases with the
If we wanted the project at
spokeandchain.nitro to also be available at
fr.spokeandchain.nitro, for example, we would add those domains as aliases like this:
$ nitro alias Select a site: 1. happylager.nitro 2. spokeandchain.nitro 3. starterblog.nitro Enter your selection: 2 No existing aliases are set for spokeandchain.nitro Enter the alias domain for the site (use commas to enter multiple): en.spokeandchain.nitro,fr.spokeandchain.nitro Adding aliases: en.spokeandchain.nitro fr.spokeandchain.nitro Apply changes now [Y/n] y
# Connecting to the Database
To connect to the machine from a Craft install, set the following environment variables in your
DB_USER="nitro" DB_PASSWORD="nitro" # `nitro` is the default database DB_DATABASE="nitro"
context command to get the database hostname:
$ nitro context Craft Nitro 2.0.0-alpha Configuration: /Users/oli/.nitro/nitro.yaml Sites: hostname: happylager.nitro php: 7.4 webroot: happy-lager/web path: ~/dev --- hostname: spokeandchain.nitro php: 7.4 webroot: spoke-and-chain/web path: ~/dev --- hostname: starterblog.nitro php: 7.4 webroot: starter-blog/web path: ~/dev --- Databases: engine: mysql 5.7 hostname: mysql-5.7-3306.database.nitro username: nitro password: nitro port: 3306 --- engine: postgres 12 hostname: postgres-12-5432.database.nitro username: nitro password: nitro port: 5432 ---
Then from your SQL client of choice, create a new database connection with the following settings:
- Host: hostname from
- Port: Database port. (3306 for MySQL or 5432 for PostgreSQL by default).
.env file may need different connection settings than your host machine. Use the engine’s default port in your
.env file, and any custom port on your host machine. See How Nitro Works for more.
# Adding a Database
Nitro creates its initial
nitro database for you. You can add as many databases as you’d like running the following command, which will prompt for your desired database engine and name:
$ nitro db add
# 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
edit command), and list additional databases under the
databases: - engine: mysql version: "5.7" port: "3306" - engine: mysql version: "5.6" port: "33061" - engine: postgres version: "11" port: "5432"
Each database engine needs its own unique port.
nitro apply to apply your