Why no support for Docker secrets when using Compose?

Help docker
1

Is there a technical reason for why Docker secrets are not being supported when the container is run in Docker compose but only in swarm mode?

After using PiHole on a RPI for years, I am currenlty trying out setting it up using the Docker container for the first time. And I am doing so with Docker compose. And so I've hit the issue of how to configure the admin credential via Docker Secrets, when using Compose.

It seems that the implementation of file based secrets, via the WEBPASSWORD_FILE parameter is ONLY being used when the container is run in swarm mode (when attempting to use the content of the secret file to log into the PiHole admin portal the password is not being accepted).

At least that seems to be what I gather from other discussions on this forum:

However, nowhere can I find the rational behind only supporting secrets when running in swarm mode.

It can't be due to secrets not being a supported feature in compose:

To give a complete example, the following secret named pihole_password is fully available inside the container given the Docker compose configuration below:

# Only relevant parts shared

secrets:
  pihole_password:
    file: /srv/project/pihole_password

services:
  pihole:
      container_name: pihole
      image: pihole/pihole:2025.03.0
      secrets:
        - pihole_password
      environment:
        - WEBPASSWORD_FILE=/run/secrets/pihole_password

Shelling into the container sudo docker exec -it pihole /bin/bash makes that clear:

:/# echo $WEBPASSWORD_FILE
/run/secrets/pihole_password
:/# cat $WEBPASSWORD_FILE
super_secret_password_11!!
2

Are you running your Docker daemon and your containers in swarm mode?

Docker secrets are a feature of Docker Swarm, Docker's container orchestration toolset.

3

Thank you for the quick reply to my question.

As was mentioned in my question above, "..I am doing so with Docker compose". Not using swarm in any way.

Docker secrets are indeed not just a feature of Docker Swarm, but also a completely supported feature of Docker Compose. Please see the following link to Docker's own documentation, that was part of my question above.

As an example of a project using Docker secrets for a container running in compose, please see Nextcloud's container documentation.

4

No doubt Docker secrets can be used with docker compose, but they are still a Swarm feature.

What makes you think that when Docker's documentation says otherwise?
docker-secrets

5

Fair enough, what is named "Docker Secrets" is a swarm only feature. Using secrets is not a swarm only feature (please see my link above referencing Docker's own documentation). The naming strategy of Docker in this regard is abysmal.

Moving on from splitting hairs on that, the initial question stands:

Is there a technical reason for why the pihole container does not use file based secrets (such as these) unless they are the swarm only Docker secrets (such as these)?

1 Like
6

Suggestion:

Compose files can use .env files (read also this) to store environment variables.

Create a file called .env on the same directory where you saved your compose file.
Then add something like this to the file:

PASSWORD=My_Password_1234

Now change your compose file to use the variable, like this:

FTLCONF_weserver_api_password: "${PASSWORD}"

7

This is where it's going wrong - but perhaps our documentation isn't clear enough here. (Note: there is a PR to fix this on the docs page...)

Set WEBPASSWORD_FILE=pihole_password instead, as the /run/secrets/ part is implied:

I've just tried this myself and WEBPASSWORD_FILE works as expected in compose

2 Likes
11

Thank you for pointing this out to me! This was exactly what I was missing.

12

I agree Docker's documentation is not as clear as it could be on that matter.
Lack of proper understanding may have contributed to WEBPASSWORD_FILE having been dropped in and out of v6 during beta phase, perhaps regarding it as little used when exclusively a Docker swarm feature.
Thank you for clarifying it's available with plain docker compose as well.

2 Likes