(Elixir) BEAM Docker Release GitHub Action

1 minute read

The BEAM docker release GitHub action builds a tiny from scratch container. It works with Elixir and the Phoenix Framework. With a minimal attack surface, of tens rather than hundreds of megabytes. We are building containers not virtual machines here!

When packaging an application as a docker container it is too easy to just put FROM debian (other distributions are available, replace debian with your distribution of choice). For sure it is going to work, but you have just included dozens of libraries and binaries that your application just does not need.

The BEAM docker release GitHub action uses a multi-stage, multi-platform build that:


  • linux/amd64
  • linux/arm64

Default will create a multi-platform image for both amd64 and arm64.

Only the release and required runtime shared libraries are present. There is no shell, or any executable other than those required to run the BEAM.

The following example workflow is triggered by a push event to build an Elixir Mix Prod Release.

on: [push]
      - '[0-9]+.[0-9]+.[0-9]+'
    runs-on: ubuntu-latest
      - name: Beam Docker Release
        uses: shortishly/beam-docker-release-action@v1.23
          registry: ghcr.io
          username: ${{github.actor}}
          password: ${{secrets.GITHUB_TOKEN}}
          build-command: >-
            mix do local.hex --force +
            deps.get +
            local.rebar --force +
            compile +
            assets.deploy +
            phx.digest +
            release --overwrite
          build-image: elixir:1.14.2
          build-tags: ghcr.io/${{github.repository}}:${{github.ref_name}}

Hello World! is an example Phoenix Framework application using the BEAM docker release GitHub action with this workflow to build the container.

You can pull and run the container from GitHub Container Registry (ghcr.io) with:

docker run \
    --pull always \
    --detach \
    --env SECRET_KEY_BASE=$(cat /dev/urandom | head --bytes=64 | base64) \
    --publish 4000:4000 \
    --rm \

Open your browser at http://localhost:4000 and you will be greeted with the “Welcome to Phoenix!” banner from a container weighing in at just 30MB.

The parameters used in the BEAM docker release GitHub action can be found here. Some of the ideas are described further in this article with the dependency copying script now written as an escript to support both Erlang/OTP and Elixir.