Full Docker Support - Kicking the Doors Open

A Short-Term Diversion for a Long-Term Gain

Over the last few weeks, a trend has appeared that we as a company cannot ignore. As we've engaged with large companies and potential customers looking to use Nanobox to ease some of their production pain points, time after time, the same show-stopping issue has come up – "We have our own Docker images and we need to use them."

Nanobox is built on top of Docker and is designed to abstract away most of the knowledge required to run a fully "Dockerized" stack. However this abstraction depends on a proprietary "framework" of engines and Docker images built specifically for use with Nanobox.


From the very beginning, one of our primary goals has been to help developers and companies be flexible and do more with less. In many ways, we do this really well. For example, cloud providers – it doesn't really matter who you're using under the hood, Nanobox takes care of all the provisioning, setup, and management for you. Want to change providers? No problem! You don't even have to learn their API or setup process.

However, the underlying framework of engines and custom-built Docker images isn't as flexible as we would like. In many ways, it limits what one can do with Nanobox. Anything outside of "the norm" often requires significant expertise and help from our team. Being able to support any Docker image, not just those we provide, will allow you to customize literally everything about your environment.

I should note that a major benefit of Nanobox is being able to use Docker without having to know Docker. That's not going to change. It will still be really easy to use and customize without much Docker knowledge. But if you're familiar with and are comfortable building your own Docker images, the sky is the limit.

A Short Term Diversion

To layer in this functionality, we are diverting much of our team's efforts over the coming weeks to removing and/or minimizing the dependence on Nanobox-specific Docker images. Not only will this make Nanobox more flexible, but it will essentially make your entire infrastructure "ejectable" and portable.

Full Docker Support?

Nanobox already uses Docker images to build your app's infrastructure, so what does "full Docker support" mean? Currently, all environment configuration is specified in your boxfile.yml. As code components are provisioned, they each use a base Nanobox image which imports and runs engine scripts that install necessary packages for your application and apply the config settings defined in your boxfile.yml.

This, admittedly, is not the "Docker way." It allows you to centralize architecture and configuration in a single file, but is very rigid. For example, say you want to customize the way a certain package is configured. It's only possible if the engine or image you're using exposes those options in the boxfile.yml.

In order to truly support any Docker image, a few changes have to be made:

Image-Based Runtime Configuration

Runtime configuration will no longer be handled in the boxfile.yml. In fact, the boxfile.yml is going to be replaced by something new (more on that later). Instead, configuration will be handled in the actual Docker image used for each code component. By doing this, you can completely customize everything in your runtime.

No Need for Engines

Since runtime configuration is going to be handled in the Docker image itself, there will no longer be a need for engines. Just Dockerfiles and Docker images.

New Deployment Process

Currently, when you deploy code with Nanobox, we package up your code, compress it, and rsync it to your app's warehouse where it is then distributed to new nodes. In the future, warehouses will be replaced by a "registry" platform component. This is a Docker registry to which Docker images are published, then distributed to application nodes. Deploys will involve building Docker images for each component in your application, publishing them to your app's registry, then distributing the updated image(s) to new nodes.

New Tools & Functionality

This change is big enough that it merits is own set of new tools.


We are working on a brand new CLI called nbx. It's still in active development, so I won't say much regarding commands and functionality, but it will leverage native Docker functionality much more than the nanobox CLI does. We'll provide more details soon.


The boxfile.yml is going to be replaced by the nbx.yml. Since runtime configuration is handled in Docker images, nbx.yml will be used for defining your app's architecture – what components are needed, what Docker images should be used for each component, how processes should be started, etc.

I won't say too much more since the nbx.yml structure, nomenclature, and even the filename are still very much in flux, but more information will be coming soon.

Components & Images

With this new approach, every component in your app will use its own Docker Image. This kicks the door wide open for micro-service architectures and "Hydra" apps. Have a Phoenix/Elixir API and an Express front-end? No problem. Your API can use an Elixir Docker image and your front-end can use a Node.js Docker image.

Docker Options

nbx will allow you to use Docker images in a couple of different ways:

Nanobox Docker Images

Open source Docker images provided by Nanobox with self-contained configuration, reasonable defaults, helper scripts to customize defaults, and other niceties.

Hosted Docker Images

The truth of the matter is that you'll be able to use any Docker image as long as it is publicly accessible and/or can be downloaded using some method of authentication.

Custom Dockerfile Support

nbx will also support straight Dockerfiles and will build your image for you.

To the Future

We're already heads down working on all the pieces required to bring full Docker support to Nanobox users. Once everything is ready, there will be a transition period where the "legacy" toolset (nanobox as it currently stands) and the new toolset (nbx, the nbx.yml, and full Docker support) will both be available.

The workflow will still be simple and elegant, just as you’re used to, albeit slightly different. The inflexibility of certain aspects of Nanobox in its current state will be a thing of the past. If there's a Docker image available for "it," you'll be able to use "it."

We're excited about the possibilities these changes open up. Over the coming weeks, we look forward to releasing more information about nbx and the nbx.yml and the many pain-points and roadblocks they will address. Stay tuned!

To the future!

Posted in Docker, Nanobox