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 runtimeengine: elixir
# ensure inotify exists for hot-code reloadingdev_packages:- nodejs- inotify-tools
# cache node_modulescache_dirs:- node_modules
# add node_module bins to the $PATHextra_path_dirs:- node_modules/.bin
# enable the filesystem watcherfs_watch: true
# deployment optionsdeploy.config:
# generate the static assets digestextra_steps:- mix phoenix.digest
# migrate the database just before the new process comes onlinebefore_live:web.main:- mix ecto.create --quiet- mix ecto.migrate
# add a postgres data componentdata.db:image: nanobox/postgresql
# add a web component with a start commandweb.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 databaseconfig :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