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 an app on Nanobox
- Configure your project
- Stage your application (optional)
- Link and Deploy to production
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.exs
and 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
:
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
Hacker Noon is how hackers start their afternoons. We’re a part of the @AMI family. We are now accepting submissions and happy to discuss advertising & sponsorship opportunities.
If you enjoyed this story, we recommend reading our latest tech stories and trending tech stories. Until next time, don’t take the realities of the world for granted!