Craft CMS on Nanobox: Prelude – Craft developer's nirvana?

Configuring local development environment is a pain

If you're a Craft CMS developer, you've probably explored various ways to install and run Craft locally while developing websites. There has been a lot of talk about the various local development setups such as MAMP, XAAMP, Laravel Valet, Vagrant, Homestead, or fully manual installation of PHP, Apache/Nginx, MySql, etc. Many a developer spent more time than they care to admit googling around and troubleshooting missing or ill functioning PHP extensions, problems with connecting to a database, figuring out how to get image manipulation libraries working properly, etc.

Finally, when Craft CMS is working properly in your local development environment and your website is ready to go live, you need to go through a similar process once again to deploy the new website to staging and/or live.

Wouldn't it be great if you could spend your time actually working with Craft CMS and leave the dev-ops related issues to someone else?

Turns out, that's exactly what Nanobox is meant to do.

Hello, Nanobox!

Nanobox is a micro-platform that builds and configures your app anywhere. It is using Docker containers behind the scenes and works on any development platform including Mac, Windows and Linux.

To get started with Nanobox, you first need to create a free Nanobox account and download and install Nanobox on your development machine.

Nanobox brands itself as Platform as a Service. This means that Nanobox is all you need to develop, stage and deploy your web application live. There are clear benefits to letting Nanobox replace your complete dev-ops but it may not be a fit for everyone. It's up to you to pick and choose how much or how little Nanobox should do for you.

At minimum, Nanobox is absolutely incredible for local development!

Local development with Nanobox

Configuring and starting your web app

Nanobox will build your local development environment based on instructions specified in the boxfile.yml configuration file. It is a YAML formatted config that includes everything Nanobox needs to reliably build and rebuild the entire development setup. Here is an example of setting up a generic PHP app with MySql database backing:

run.config:
  # install php and associated runtimes
  engine: php
  # php engine configuration (php version, extensions, etc)
  engine.config:
    # sets the php version to 7.1
    runtime: php-7.1
    # specify the required php extensions
    extensions:
      - pdo
      - pdo_mysql
      - session
# ass a MySQL database
data.db:
  image: nanobox/mysql:5.6

After you save this configuration file in a directory on your local machine, you'd add a local DNS entry to simplify accessing your app in a browser. For example, something like the following:

nanobox dns add local my-php-app.test

Then, all that's left is to run the app.

nanobox run php-server

Voila! You have an entire local PHP 7.1 local development environment available with a MySQL database back-end. The best part, just share the boxfile.yml with your fellow developers and they'll have the exact same local development environment on their machine nearly instantly. No explaining or fiddling around necessary.

Coding your web app

But where do I put my application code and how do I make changes to it while running my app? I'm glad you asked.

The directory where the boxfile.yml resides becomes the root application directory of your app and it is automatically mounted into Nanobox, so any changes will be reflected in your running app. Simply open that directory in your favorite code editor and hammer away.

Managing your web app

Now, let's say you need to add some PHP packages to your application using composer. Since none of the software running your app is actually installed on your local machine, you need to drop into Nanobox console to interact with the development environment.

# drop into a Nanobox console
nanobox run

# list your installed packages
composer show

# require and install a new composer package
composer require vendor/package

# inspect the code mounted from your local machine
ls

# exit the console
exit

Of course, the above example will not be quite sufficient to get you going with Craft CMS 3. Turns out that modern web application development requires a bit more complex environment setup to work just right. However, this is not a problem and there are plenty of additional configuration options and directives to fine-tune the boxfile.yml for the ideal Craft 3 development environment setup.

The next article will explore starting a new Craft 3 project with Nanobox as well as getting an existing Craft 3 project running locally with Nanobox.