Proposition for an official Docker Compose Guide

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


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 :

        image: postgres
        restart: always
        container_name: database
            - 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
        container_name: hello-app
        restart: always
            context: .
            dockerfile: Dockerfile
            - db
        ports: # Docker need to expose ports for you to access your app.
            - 4000:4000
            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

        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.


The port as it is is exposing the app to the internet on your PC, because 4000:4000 is the same as, and what you want in localhost is For production setup where the docker container is the one directly handling the requests from the internet, then you want to use, but if the docker container is behind Nginx, Traefik or other, via docker compose, then you can remove the ports all together. If you have an hybrid dolution, where you have Nginx on the host serving the docker container, then use

I don’t recommend to use this, because if you then need to stop the container he will restart immediately. Instead use unless-stopped.


I feel like I get your point about the ports, but couldn’t properly explain it in a easy to understand manner.
Would you mind writing a small paragraph we could add in the guide, along with the changements which should be done in the compose.yml ?

The depends_on option is deprecated since docker-compose version 3 because depends_on only checks whether the dependent container is started, but does not check whether the dependent service (e.g. PostgreSQL server) is ready to accept requests.

It’s better to use something like wait-for-it (GitHub - vishnubob/wait-for-it: Pure bash script to test and wait on the availability of a TCP host and port) to wait for a port to open.

I do not see where depends_on is being deprecated.

I use depends_on long form with a condition, and in my database setup, I specify a healthcheck using the standard installed pg_isready command (in the case of PostgreSQL dependenceis) like so:

    image: foo:123
        condition: service_healthy
    image: postgres:14.4
      test: [ "CMD", "pg_isready", "-q", "-U", "postgres" ]
      timeout: 45s
      interval: 10s
      retries: 10

This will only works if your are not using docker in swarm mode, as per their docs for version 3:

The depends_on option is ignored when deploying a stack in swarm mode with a version 3 Compose file.

When I need to use it I set my docker compose file to version 2.