Environment variables are not working at build time


I’m currently trying to get my multi container app running on balena OS.
The build fails because the environment variables are not beeing substituted (as documented in docker-compose: environment variables)

Am I right when I assume, that the builder does not have access to the variables I’ve set in my dashboard and it does not support env variables at all?

I need to pull some python packages from a private pypi and therefore I need an auth token during the build.
This token should not appear in my code base, so environment vars are the way to go.

The critical part of the docker-compose file looks like this:

        restart: always
            auth_token: ${AUTH_TOKEN:?err}
          context: ./web
          dockerfile: Dockerfile

Inside the Dockerfile I set the environment variable like this:

ARG auth_token
ENV AUTH_TOKEN $auth_token

When I run echo $AUTH_TOKEN I just see the literal string I used in the docker-compose.yml, e.g.:

I also tried the following syntax versions in the compose file:


So my question is:
How can I use environment variables during the build?
If not, what could be a work around?


Hello there,
Substitute environment variables syntax isn’t yet supported in our compose file. We re actively working on build time secrets, and will make sure to post an update here once they re out. We’ll also be adding build-time env var interpolation soon.


Can you give a status update on compose file substitute environment variable syntax support? I use a .env file (https://docs.docker.com/compose/environment-variables/#the-env-file) to populate the image tags to use for my multicontainer docker-compose.yml file, but it seems the .env file is not being used as part of a local balena push (--env seems to be intended for inside the containers, not the docker-compose.yml file). I can obviously do some preprocessing with docker-compose config, but it’d be nice not to have to.

Hey @mrjogo

This is definitely on our radar, but I can’t give you a definite timeline right now.

Could you explain your use case a little please? It will enable us to tune the features to what users would actually find useful.


I develop each container’s Docker image in a different git repo and then autobuild them on Docker Hub. The compose file references those images with an environment variable for each of the tags. This makes it easy to try a new combination of versions, branches, etc simply by changing one of the environment variable. Here’s an example:


version: '2.1'
    image: service1:${SERVICE1_TAG}
    image: service2:${SERVICE2_TAG}
    image: service3:${SERVICE3_TAG}



Thanks for that @mrjogo – considering the multiple environments users can build projects on balenaCloud (the cloud builder via git push, local builds via the cli, etc.) it isn’t entirely straightforward to support build-time environment variables (ie. where do values come from?) and last we discussed it we didn’t settle on a nice uniform way to support this, though like Cameron mentioned above it’s a feature we definitely want. In the meantime, the workaround is what you do with docker-compose config unfortunately.

Yeah, I understand it’s a little tricky. I actually assumed there would be an entry for the environment variables in the balena.yml file (seemed logical to put it next to build-variables), and that only ones explicitly put there would be replaced in the docker-compose.yml file.

That makes sense indeed. I noted this in our feature description.
We’ll update this thread when we have progress on this feature implementation.

It took me a while to find out that substitute environment variables isn’t supported.

Especially since the docs explicitly mention that docker-compose v2.1 feature set is supported (which supports env var interpolation).

The docs should be updated.

@ftes welcome to the forums. The docs correctly state that a ‘a subset of the Compose v2.1 feature set’ is supported but we could definitely add this information to the ‘known unsupported’ list to save users getting caught out by this.

You are free to create issues in the docs repo or even PRs to implement the addition at any time but for now I’ve created an issue here.