Craft CMS 3 (Beta) with Nanobox

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:

  engine: php
    runtime: php-7.1
    document_root: web
    webserver: apache
      - ctype
      - pdo
      - pdo_pgsql
      - mcrypt
      - mbstring
      - json
      - curl
      - dom
      - iconv
      - imagick
      - session
      - zip
      - zlib

    php: start-php
    apache: start-apache
      - storage
    craft[error]: storage/logs/web.log
    craft[stacktrace]: storage/logs/phperrors.log

  image: nanobox/postgresql:9.5  
  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.

Update the DB Config in config/db.php

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

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

This will create a new nanobox-craft3 project directory, cd into it, then build and provision your PHP runtime, install Craft, and start Craft. You can view the source of the bootstrap here.

Posted in PHP, Craft CMS