Steve Domino

@skdomino

Phoenix Application Deployment with Nanobox

This article was originally a pull request for the Phoenix documentation, however it was ultimately rejected (for reasons with which I completely agree):

Following the advice of Chris McCord, I’ve turned this into a blog post which will hopefully benefit the Elixir/Phoenix community.

The goal of this guide is to show you how to deploy a Phoenix application to production using Nanobox.

(warning, shameless plug ahead)

Why Nanobox? Two reasons really.

I’m an engineer at Nanobox, so naturally I want to promote it. But really, it’s more than that. I truly believe that Nanobox is the easiest way to develop and deploy any application.

Nanobox allows application developers to deploy their own applications, removing the need for DevOps, or automating it, or whatever you want to call it. Nanobox does it for you so you don’t have to.

(/shameless plug)

Before we begin

To get started, you really only need three things:

  • A Phoenix application
  • Nanobox Desktop (the Nanobox CLI tool)
  • A hosting account

You technically don’t even need Erlang, Elixir, or Phoenix, but chances are you already have them installed.

Note: All `nanobox` commands are run from the root of your application.

A Phoenix Application

If you need an application to deploy, you can use one of these “quickstarts”:

  • nanobox-phoenix — A vanilla Phoenix app with a PostgreSQL database ready to go.
  • nanobox-phoenix-example — A Phoenix “Todo” app with a PostgreSQL database and basic CRUD operations.

You can also create a new application following the Nanobox from scratch guide, or the Phoenix Up and Running guide.

Nanobox Desktop

If you’re using Nanobox for the first time, create a free Nanobox account and download and install Nanobox Desktop.

A Provider Account

The last thing you’ll need is a hosting account like Amazon AWS or DigitalOcean, which you’ll link with your Nanobox account. Nanobox is frequently adding more providers to the list, so if you don’t see yours, or you don’t use one, you can also create your own integration.

Doc: Connecting your account to your host

Doc: Creating a custom provider

Getting Started

There are four steps when deploying your application with Nanobox:

Create a Nanobox Application

New applications are created through the Nanobox Dashboard. During this process, you’ll be prompted to name your application, and select a host and region where you want your application to live.

Doc: Launching a new application

Configure your project

There are two pieces to configuring your application to run with Nanobox:

The boxfile.yml

Nanobox uses a simple config file called a boxfile.yml to provision development and production environments. Create a boxfile.yml at the root of your project with the following:

run.config:
# elixir runtime
engine: elixir
# ensure inotify exists for hot-code reloading
dev_packages:
- nodejs
- inotify-tools
# cache node_modules
cache_dirs:
- node_modules
# add node_module bins to the $PATH
extra_path_dirs:
- node_modules/.bin
# enable the filesystem watcher
fs_watch: true
# deployment options
deploy.config:
# generate the static assets digest
extra_steps:
- mix phoenix.digest
# migrate the database just before the new process comes online
before_live:
web.main:
- mix ecto.create --quiet
- mix ecto.migrate
# add a postgres data component
data.db:
image: nanobox/postgresql
# add a web component with a start command
web.main:
start: node-start mix phoenix.server

At this point, if you want to, you can use nanobox run to provision a local development environment. Once started, you can either view your app at the IP given from the run command, or generate a dns alias with the dns add command:

$ nanobox dns add local nanobox-phoenix.dev

Now visit your app at nanobox-phoenix.dev

Doc: The boxfile.yml

Environment Variables

Nanobox uses environment variables (evars) to keep certain information secret. You’ll need to make a few modifications to your app to use evars.

First, you’ll load the secret key from the Nanobox evars rather than the config/prod.secret.exs by adding it to the config/prod.exs:

config :nanobox_phoenix, NanoboxPhoenix.Endpoint,
http: [port: 8080],
url: [host: "example.com", port: 80],
cache_static_manifest: "priv/static/manifest.json",
secret_key_base: System.get_env("SECRET_KEY_BASE")

Note: You can generate a secret key for your application with mix phoenix.gen.secret.

Next, add a production database configuration to config/prod.exs:

# Configure your database
config :nanobox_phoenix, NanoboxPhoenix.Repo,
adapter: Ecto.Adapters.Postgres,
username: System.get_env("DATA_DB_USER"),
password: System.get_env("DATA_DB_PASS"),
hostname: System.get_env("DATA_DB_HOST"),
database: "nanobox_phoenix",
pool_size: 20

Note: If you plan on developing or staging your application locally you’ll want to update your /config/dev.exsand your /config/test.exs with the same username, password, and hostname evars as above.

Nanobox generates DATA_DB_USER, DATA_DB_PASS, and DATA_DB_HOST evars for you, but you'll need to add a SECRET_KEY_BASE, and any others you want, manually.

Development and staging evars are added with the evar add command:

$ nanobox evar add local KEY=VALUE
$ nanobox evar add dry-run KEY=VALUE

Note: Production evars are added through the Nanobox dashboard.

Once you’ve added all your evars, comment out the line import_config “prod.secret.exs" in your /config/prod.exs:

Doc: Environment Variables

Stage your application (optional)

You can stage a production deploy locally with the dry-run command. Although this step is optional, it’s highly recommended.

$ nanobox deploy dry-run

As with nanobox run, you can visit your application at the IP given from the dry-run command, or generate a dns alias with the dns add command:

$ nanobox dns add dry-run nanobox-phoenix.stage

Now try visiting your app at nanobox-phoenix.stage

Doc: Preview your app

Link and Deploy to production

The last thing you’ll need to do is link your codebase to the application you created at the beginning of this guide.

Note: The first time you try and link the application you’ll be asked to login using your Nanobox credentials.

$ nanobox remote add [app-name]
$ nanobox deploy

That’s it!

Doc: Adding a remote

Important links

More by Steve Domino

Topics of interest

More Related Stories