A few weeks ago, I explained how to launch a Craft CMS site using Nanobox. In that article, I mentioned I'd be doing a walkthrough for Craft CMS 3, which is currently in beta. Craft 3 offers some really great new functionality, including built-in image editing, PostgreSQL support, multi-site functionality, Composer support, and more. In this article, I'm going to walk through installing and configuring Craft CMS 3 with Nanobox.

I should emphasize that Craft 3 is currently in beta. While it's totally possible to use it in production, Craft doesn't recommend it.

If you're not familiar with Nanobox, it's is a "micro-platform" that builds and configures your app anywhere using settings defined in your boxfile.yml . It provides fully virtualized/containerized development environments on your local machine as well as flexible, scalable infrastructures in production.

Learn More About Nanobox

Too Long? Don't Want to Read?

If you're just itching to get Craft 3 running with Nanobox and don't want to read through the process, I've created a Craft 3 / Nanobox bootstrap script just for you.

Download & Install Nanobox

If you haven't already, go ahead and create a free Nanobox account and download and run the Nanobox installer.

Create a New Project Directory

Create a new directory for your Craft project and cd in:

mkdir nanobox-craft3 && cd $_

Add a boxfile.yml

Nanobox uses the boxfile.yml to build and configure your app's runtime and environment. Since one of the new features in Craft 3 is Postgres support, let's use a Postgres database.

Create a boxfile.yml in the root of your project with the following contents:

run.config: engine: php engine.config: runtime: php-7.1 document_root: web webserver: apache extensions: - ctype - pdo - pdo_pgsql - mcrypt - mbstring - json - curl - dom - iconv - imagick - session - zip - zlib web.craft: start: php: start-php apache: start-apache network_dirs: data.storage: - storage log_watch: craft[error]: storage/logs/web.log craft[stacktrace]: storage/logs/phperrors.log data.db: image: nanobox/postgresql:9.5 data.storage: image: nanobox/unfs:0.9

This boxfile.yml includes everything necessary to run Craft 3 as outlined in their server requirements. It tells Nanobox to provision a Postgres database and a persistent storage component. Depending on what plugins and/or PHP functions are introduced, you may need to add additional extensions .

The deep explanation of the Craft CMS boxfile.yml from my previous article still applies here, so if you're interested in the details, you can read through them there.

Start the Local Dev Environment

Nanobox will use the settings in the boxfile.yml to build and provision your apps environment. I suggest adding a DNS alias, just as a convenient way to access the running app from the browser. Run the following commands to start your local development environment:

# Add a convenient way to access the app from a browser nanobox dns add local craft3.local # Start the dev environment nanobox run

Once the environment is running, you'll be dropped into an interactive console inside.

Install Craft

Being able to install Craft with Composer is great. Composer is pre-intalled in your dev environment, so you'll be able to use it right out of the box. Composer won't let you create new projects inside directories that aren't empty, so you'll need to install Craft in the /tmp directory, then copy the generated files into your project directory, /app .

# Move into the /tmp directory cd /tmp # Install Craft 3 beta composer create-project craftcms/craft craft -s beta # Enable the dotglob shell option to interact with hidden files shopt -s dotglob # Copy Craft into your project directory cp -a craft/* /app # cd back into /app, your project directory cd -

Your current working directory is mounted into the Nanobox VM, so when you copy the generated Craft files into /app , they'll be written to your working directory on your local machine. Any changes you make to the code will be reflected in your dev app.

Nanobox automatically generates connections credentials for your database and provides environment variables for each. Update the database connection in config/db.php to the following:

return [ 'driver' => 'pgsql', 'server' => $_ENV['DATA_DB_HOST'], 'user' => $_ENV['DATA_DB_USER'], 'password' => $_ENV['DATA_DB_PASS'], 'database' => 'gonano', 'schema' => 'public', 'tablePrefix' => '', 'port' => 5432 ];

I know some may take issue with my not using the env() function to pull in values from the .env file. By default, the .env file is .gitingore'd, so if somebody else wants to start the app using Nanobox, they'll have to create their own .env . With this configuration, that app will start up in Nanobox every time, without having to create or modify the .env .

Start the App

With Craft installed and your database connection updated, you're ready to start the app. Nanobox's PHP engine provides a php-server helper script that starts all the processes necessary to run the app locally based off settings in your boxfile.yml (Apache or Nginx, mod_php or phpfpm, etc.).

# Star your app php-server

Setup Craft

With the app running, visit craft3.local/admin in your browser and go through the Craft setup process.

Hack Away!

Congratulations! You should now have CraftCMS 3 running locally with Nanobox. Nanobox let's you develop and stage your apps locally, then easily deploy them into production. I already covered these processes in my previous post, so I won't repeat them here. The steps outlined still apply to Craft 3, so feel free to check them out.

Stage the App Locally

Deploy to Production

There are also important workflow changes you should be aware of.

Craft CMS 3 Nanobox Bootstrap

I've created a bootstrap script that automates the setup outlined above (everything except adding a DNS alias, but this isn't required). In order for it to work, you must dowload an install Nanobox first.

mkdir nanobox-craft3 && $_ && bash <(curl -sL https://git.io/v7Twg)