How to deploy a Phoenix Umbrella project?

Questions / Help Build debugging
4

After some attempts I’ve succeeded in deploying the umbrella. Unlike a plain Phoenix app, the deployment of an Umbrella application with the current builder needs some more steps. Hope this explanation could be useful to someone else Fly newbie struggling with umbrellas:

Plain App

A plain Phoenix app need just these four steps to be deployed successfully:

$ mix phx.new hello  --no-ecto --install
$ cd hello
$ export SECRET_KEY_BASE=$(mix phx.gen.secret)
$ fly launch

Umbrella App

Instead, the following are all the exact steps needed today to deploy a minimal umbrella application

  1. Setup the project:
$ mix phx.new hello  --umbrella --no-ecto --install
$ cd hello_umbrella
  1. enable server in config/runtime.exs:
config :hello_web, HelloWeb.Endpoint, server: true
  1. adds elixir_buildpack.config with the preferred Ex/Ph versions:
$ cat <<EOF>./elixir_buildpack.config
elixir_version=1.13.3
erlang_version=24.0
EOF
  1. deploy the assets from within the web app directory:
$ cd apps/hello_web
$ MIX_ENV=prod mix assets.deploy
$ cd ../../
  1. Setup the Fly’s stuff:
$ fly launch
# answer "no" to deploy request and leave fly launch, then:
  1. set up the secret:
$ export SECRET_KEY_BASE=$(mix phx.gen.secret)
$ fly secrets set SECRET_KEY_BASE=$SECRET_KEY_BASE
  1. deploy
$ fly deploy
  1. enjoy your app!
$ fly open

and the umbrella application is finally happily up and running!

Besides the steps above, here are the summary of the current differences in how Fly handles deployment between plain and umbrella.

to deploy an Umbrella via Fly:

  • you have to explicitly set server: true in config/runtime.exs
  • you have to add the required elixir_buildpack.config file to the project
  • you have to build the application assets
  • you have to set the SECRET_KEY_BASE executing fly secrets after fly launch and before fly deploy (you can’t just export it to an environment variable)
  • the Fly builder will not generate a Docker file as is the case with plain apps (but if you supply one, the builder will use it)
3 Likes