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.
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.)
nanoboxcommands 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.
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.
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.
Configure Your Project
There are two pieces to configuring your application to run with Nanobox:
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).
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:9.5 # add a web component with a start command web.main: start: node-start mix phoenix.server
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
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. Instructions below.
Next, add a production database configuration to
# 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/test.exswith the same
hostnameevars as above.
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
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.dev # provision local dev env and drop into a console nanobox run
Generate & Add Your Secret Key Base
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.
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
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
node-startis 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.dev: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