As I wrote a week ago in this post, I found the lack of official documentation for Docker compose rather annoying, and I met a lot of problems trying to setup a compose stack for my api. So I wanted to try to write a guide which, if approved, could be added to the official doc. Feedback needed. keep in mind that I am not experienced with Docker, so I could have wrote inexact stuff.

Create a Docker compose stack for your Phoenix app

What we’ll need

We are continuing from the “Deploying with Releases” guide, and by having used the --docker flag in mix phx.gen.release

Goal

The goal is to integrate our dockerised phoenix app in a Compose stack containing the app and the database.

The compose file

We will start by adding a file “docker-compose.yml” at the root of the project. The file should contain the following :

services:
    db:
        image: postgres
        restart: always
        container_name: database
        volumes:
            - pg-data:/var/lib/postgresql/data
        environment: # Used by the postgres image to setup a default user. For security reason, you should avoid using the postgres user
            POSTGRES_USER: pg_user
            POSTGRES_PASSWORD: pg_pass
            POSTGRES_DB: hello_database
    
    app:
        container_name: hello-app
        restart: always
        build:
            context: .
            dockerfile: Dockerfile
        depends_on:
            - db
        ports: # Docker need to expose ports for you to access your app.
            - 4000:4000
        environment:
            DATABASE_URL: "ecto://pg_user:pg_pass@db/hello_database" # Template : "ecto://db_user:db_password@ip_or_compose_service_name/db_name"
            SECRET_KEY_BASE: really_long_secret # Can literally be anything, but generally generated randomly by tools like mix phx.gen.secret

volumes:
    pg-data:
        external: true # Must use "docker volume create --name=pg-data before

By using docker compose up, you will now have your containers running, but it’s not over yet, the last part is the migration of your schema in the newly instancied database service

A word about volume

As you may know, Docker is really shining when it doesn’t have to persist data, because container are stateless by default. However, when using a database, and needing to save data, we need volume to map the space from within the container to outside. Moreover, by using an external volume, we can ensure the data is stored somewhere we can easily find it.

A word about environment

In this docker-compose file, we set our environment directly, for simplicity’s sake. It is not a good reflex. When you will push your compose.yml, you’ll put up your credentials in plain day, between others problems. You may prefer to use a .env file, but this subject isn’t the point of this guide, so we won’t go further.

The migration

Once both the containers are started, we need to migrate our schema in the newly created postgres. To do so, we will use a variante of the _build/prod/rel/my_app/bin/my_app eval "MyApp.Release.migrate we saw in the previous chapter.

First, we need to enter the Docker container of our phoenix app, by clicking the CLI button in the Docker Desktop GUI. Or, if you prefer a terminal, using it’s docker id we can get with docker ps along with docker exec -it <container_id> /bin/sh.

Then, because the Dockerfile simply copied the release folder in the container, we need to remove everything before the bin folder. Leaving us with bin/my_app eval "MyApp.Release.migrate"

And that’s it. You now have a Docker Compose Stack of two containers, which will be restarted automatically if one of them goes down, and deploying your app on another machine is now as easy as git clone, docker compose up.