Phoenix Development - Getting Started

Phoenix is rapidly becoming a very popular framework for building next-gen web applications. This guide will take you through getting a new (or existing) Phoenix application up-and-running using Nanobox.

Phoenix + Nanobox

This guide is for developers who are new to Phoenix and are just looking to get started or seasoned Phoenix developers who are looking for a better dev-to-production workflow.


If you don't have Erlang, Elixir, or Phoenix installed don't worry, you don't need them! There are actually very few requirements to get started developing Phoenix with Nanobox:

  • A Phoenix application (new or existing)
  • Nanobox Desktop (the Nanobox CLI tool)
  • Somewhere to host your application (AWS, DO, etc.)

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

A Phoenix Application

If you don't have an existing Phoenix application on hand, either of these “quickstarts” are already configured for running with Nanobox:

  • 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 Phoenix from Scratch guide, or the Phoenix Up and Running guide.

Nanobox Desktop

If this is your first time using Nanobox, create a free Nanobox account, then download and install Nanobox Desktop.

A Provider Account

You’ll need an account with a cloud host of your choice (something like Amazon AWS or Digital Ocean). Before deploying your application to production you'll link this account to your Nanobox account.

If you don't see your provider available, Nanobox is frequently adding more providers to the list. If you happen to have your own infrastructure, you can also create your own integration.

Doc: Connecting Your Account to Your Host
Doc: Creating a Custom Provider

Getting Started

The dev-to-production workflow with Nanobox is very simple:

  • Create an app on Nanobox
  • Configure your project
  • Stage your application (optional)
  • Link and deploy to production

Create a Nanobox Application

When I say "application" in the context of the Nanobox Dashboard, I'm talking about the servers that are being created on your host. The "app" itself doesn't really do anything until you link it to your local codebase.

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 app 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 yaml config file, called a boxfile.yml, to describe your application's environment. The boxfile is used when provisioning your application in all its environments (development, staging, and production).

Create a boxfile.yml at the root of your project with the following:

  # elixir runtime
  engine: elixir
  # ensure inotify exists for hot-code reloading
    - nodejs
    - inotify-tools
  # cache node_modules
    - node_modules
  # add node_module bins to the $PATH
    - node_modules/.bin
  # enable the filesystem watcher
  fs_watch: true

# deployment options
  # generate the static assets digest
    - mix phoenix.digest
  # migrate the database just before the new process comes online
      - mix ecto.create --quiet
      - mix ecto.migrate

# add a postgres data component
  image: nanobox/postgresql:9.5

# add a web component with a start command
  start: node-start mix phoenix.server

Environment Variables

Nanobox uses environment variables (evars) to keep certain information secret. Modify your config/prod.exs to use a SECRET_KEY_BASE rather than the config/prod.secret/exs. Also note that your app should be listening on port 8080:

config :nanobox_phoenix, NanoboxPhoenix.Endpoint,
  http: [port: 8080],
  url: [host: "", 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. Instructions below.

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 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 can be added either through the Nanobox CLI or the 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

Run Your App Locally

With a boxfile in your codebase, use nanobox run to provision a local development environment. I recommend adding a DNS alias to provide a convenient way to access the app from a browser.

# add a convenient way to access the app from a browser
nanobox dns add local nanobox-phoenix.local

# provision local dev env and drop into a console
nanobox run

Generate & Add Your Secret Key Base

The nanobox run command will drop you into an interactive console inside your dev environment where mix is already installed. Use mix to generate a new secret key.

mix phoenix.gen.secret

In another terminal, outside of the Nanobox console, add the generated key as the SECRET_KEY_BASE environment variable. From the root of your project:

nanobox evar add local SECRET_KEY_BASE=generated-secret-key

Start Phoenix

Back in the Nanobox console, with the your boxfile.yml in place, database credentials updated, and your secret key base added, go ahead and start Phoenix:

node-start mix phoenix.server

Note: node-start is a helper script provided by the Elixir engine that ensures nodes are started with credentials sufficient to cluster and attach to after they are running.

Once started, you can either view your app at the IP address provided in the output of the run command, or at the DNS alias you added.

Visit your app at nanobox-phoenix.local:4000.

Stage Your Application (Optional)

Although staging your app is "optional", it's highly recommended. Nanobox makes application staging very easy. You can stage a production deploy locally with the deploy dry-run command:

$ nanobox deploy dry-run

You can add a DNS alias for your dry-run environment in the same way you did for your local environment:

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

You can now visit your app at nanobox-phoenix.stage

Doc: Preview your app

Link and Deploy to Production

To deploy your application to production you must first link your local codebase to your live app created on Nanobox by adding it as a remote:

Note: The first time you try to add the application as a remote, you’ll be asked to login using your Nanobox credentials.

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

And that’s it!

Doc: Adding a Remote


Posted in Elixir, Phoenix, Getting Started, Development, Nanobox