José Valim recently twittered about the Liveview-Cluster project, which showcased how state can be shared among a global cluster of Elixir nodes.

I found this project impressive, because the global state (a simple counter) was shared by 17 machines all around the globe. What I found even more impressive was, their server provider. It allowed them to deploy machines in 17 different regions with relative ease.

I tried out recently and would like to share how to get started with it. I will create a new Phoenix project, upload it to as a Docker image, and provision the application with a Postgres instance. Let’s get started!

Creating the application

First, let’s create a new Phoenix application with:

mix my_app --live

This will create a basic Phoenix LiveView project with a database connection using Ecto. We want to run the database migration every time the application starts. Since we will create a Mix Release for the application, we cannot use mix for migrating the database. The recommended solution is to create a custom Release module, which takes care of migrating the repo.

Create a /lib/my_app/release.ex file and copy the following code into it:

defmodule MyApp.Release do
  @app :my_app

  def migrate do

    for repo <- repos() do
      {:ok, _, _} =
          &, :up, all: true)

  def rollback(repo, version) do

    {:ok, _, _} =
        &, :down, to: version)

  defp repos do
    Application.fetch_env!(@app, :ecto_repos)

  defp load_app do

Now, whenever we want to migrate the database, we can call MyApp.Release.migrate() instead of mix ecto.setup. We will use this in the following section when we start our Docker image.

As the last step, we need to configure our application with a /config/release.exs file. This allows us to read the environment variables when the application is started (at runtime) instead of when the Docker image is built (at compile time).

Create a /config/release.exs file and copy the following code into it:

import Config

secret_key_base =
  System.get_env("SECRET_KEY_BASE") ||
    raise """
    environment variable SECRET_KEY_BASE is missing.
    You can generate one by calling: mix phx.gen.secret

app_name =
  System.get_env("FLY_APP_NAME") ||
    raise "FLY_APP_NAME not available"

database_url =
  System.get_env("DATABASE_URL") ||
    raise """
    environment variable DATABASE_URL is missing.
    For example: ecto://USER:PASS@HOST/DATABASE

config :my_app, MyApp.Repo,
  url: database_url,
  socket_options: [:inet6],
  pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10")

config :my_app, MyAppWeb.Endpoint,
  server: true,
  secret_key_base: secret_key_base,
  load_from_system_env: true,
  http: [port: {:system, "PORT"}],
  url: [scheme: "https", host: "#{app_name}", port: 443],
  force_ssl: [rewrite_on: [:x_forwarded_proto]],
  cache_static_manifest: "priv/static/cache_manifest.json"

# Do not include metadata nor timestamps in development logs
config :logger, :console, format: "[$level] $message\n"

Make sure that you defined the socket_options: [:inet6] option for your Repo. Otherwise, your repo won’t be able to talk to the provisioned Postgres instance, which requires a connection via IPv6. This info was brought to you by a very kind engineer at

The Docker setup only supports deploying Docker images as of now. We need to create a Dockerfile to build and deploy a Docker image with our application inside of it.

Create a Dockerfile and copy the following code into it:

# Stage 1: Build a Mix.Release of the application (image size: ~750mb)
FROM bitwalker/alpine-elixir-phoenix:latest AS phx-builder


# These two environment variables will be overwritten when the application is started.
# They are needed here to satisfy the env-variable checks in `prod.secret.exs`

# If you set the PORT to 4000, you need to change it in the fly.toml as well.

# Cache elixir deps
ADD mix.exs mix.lock ./
RUN mix do deps.get --only prod, deps.compile

# Cache npm deps
ADD assets/package.json assets/
RUN npm install --prefix assets

# Copy all local files to the build context
# Ignores the ones specified in .dockerignore
ADD . .

# Run frontend build, compile, and digest assets
RUN npm run --prefix assets deploy
RUN mix do compile, phx.digest

# Create a Mix.Release of the application
RUN mix release

# Stage 2: Create a smaller deployment image (image size: ~98mb)
FROM bitwalker/alpine-elixir:latest

# Make sure that this PORT is equal to the one above
# and to the one in fly.toml


# Create a unprivileged user to run the app
# This is a common security practice to avoid
# giving root permissions to the application which attackers 
# could potentially abuse if they gain access to the application.
ENV USER="phoenix"
ENV HOME=/home/"${USER}"
  addgroup \
  -g 1000 \
  -S "${USER}" && \
  adduser \
  -s /bin/sh \
  -u 1000 \
  -G "${USER}" \
  -h "${HOME}" \
  -D "${USER}" && \
  su "${USER}" sh -c "mkdir ${APP_DIR}"

# Copy the files necessary to run the application
COPY --from=phx-builder --chown="${USER}":"${USER}" /app/_build/prod/rel/my_app ./
COPY --from=phx-builder --chown="${USER}":"${USER}" /app/ ./

# Define the entrypoint and the command it should execute
ENTRYPOINT ["/app/"]
CMD ["bin/my_app", "start"]

This Dockerfile defines a multi-stage build process and creates a Mix.Release of the application. Alex Koutmos wrote about this topic in great depth. I recommend reading his fabulous blog post to learn more about it.

To speed up the build process you can define the following rules in your .dockerignore file. They will prevent Docker from uploading the specified folders to the build context.


The last step is to create an script, which migrates our database and starts our application.

Create a file and copy the following code into it:

# Docker entrypoint script.

/app/bin/my_app eval "MyApp.Release.migrate"

exec $@

We use Mix.Release’s eval command to run the migrate function of our MyApp.Release module. This will migrate the database for us. We don’t need to create the database first since will take care of that for us.

Deploying to

We created an application and configured our Docker build process. Now, it’s time to let our application (Badumm, tsssss).

If you haven’t already, please install the flyctl command line interface and sign up or log in to your account.

# To sign up
flyctl auth signup

# To log in
flyctl auth login

Now that you are logged in, let’s first provision our app with a postgres instance. In order to create a new postgres cluster, run:

flyctl postgres create

This command will ask you a few questions. I added example answers below:

? App name: my-app-postgres
Automatically selected personal organization: Your Name
? Select region: fra (Frankfurt, Germany)
? Select VM size: shared-cpu-**1x** - 256
? Volume size (GB): 10
Creating postgres cluster my-app-postgres in organization personal
Postgres cluster my-app-postgres created
  Username:    postgres
  Password:    BASE64-PASSWORD-HERE
  Hostname:    my-app-postgres.internal
  Proxy Port:  5432
  PG Port: 5433
Save your credentials in a secure place, 
you will not be able to see them again!

Monitoring Deployment

2 desired, 2 placed, 2 healthy, 0 unhealthy 
[health checks: 6 total, 6 passing]
--> v0 deployed successfully

Connect to postgres
Any app within the personal organization can connect to postgres using the 
above credentials and the hostname "my-app-postgres.internal."
For example: 

We received the DATABASE_URL in the last section here. Normally, we would need to set it manually for our application, but don’t worry since we will let set this environment variable automatically.

Next, let’s create an app on

# This will generate a random app name
flyctl launch

# To set the app name yourself, run:
flyctl launch --name my-app

If you run the above command, you can choose a region for the app. Don’t worry. You can always change and add regions afterward. For now, select a region close to you.

This will create the fly.toml file, which configures the deployment to

app = "my-app"

kill_signal = "SIGINT"
kill_timeout = 5


  internal_port = 4000
  protocol = "tcp"

    hard_limit = 25
    soft_limit = 20

    handlers = ["http"]
    port = "80"

    handlers = ["tls", "http"]
    port = "443"

    grace_period = "1s"
    interval = "15s"
    port = "4000"
    restart_limit = 6
    timeout = "2s"

Before we deploy the first version of our application, we must not forget to attach the Postgres database to the application:

flyctl postgres attach --postgres-app my-app-postgres

This will add the DATABASE_URL environment variable to your application.

Finally, let’s deploy the application with:

flyctl deploy

This command will build, upload, and start the Docker container of your application. It might take a minute or two.

After the deployment process is done, you should be able to access your application at If not, please don’t hesitate to contact the folks at either on their community board, or me on Twitter.