portainer: Compose yaml files are no longer interpolated with the contents of .env

Before you start please confirm the following.

Problem Description

In Portainer 2.27.0, the compose yaml files associated with my stacks seem to no longer be interpolated with the values defined in my .env file.

For example, in a service definition I have things like this:

    volumes:
      - ${STORAGE_BASE}/tailscale/data:/var/lib # tailscale/tailscale.state in here is where our authkey lives

which should be interpolated with the relevant value from .env:

STORAGE_BASE=/srv/ssdtank/docker

This worked prior to 2.27.0, but now the container is brought up trying to mount /tailscale/data from the host, as if the interpolation was not set, which matches up with what I see logged by portainer:

Feb 20 17:04:18 gnubert portainer[3689]: 2025/02/20 05:04PM INF github.com/portainer/portainer@v0.6.1-0.20241105012540-458d722d4754/pkg/libstack/compose/logwriter.go:55 > level=warning msg="The \"STORAGE_BASE\" variable is not set. Defaulting to a blank string." |

Expected Behavior

compose yaml interpolation happens from a .env file present in the same directory as the yaml files

Actual Behavior

no interpolation happens

Steps to Reproduce

  1. Create a compose yaml file that uses interpolation
  2. Create a .env file in the same directory with values to interpolate
  3. Deploy the compose yaml file from a git repo
  4. Observe that the interpolation didn’t happen.

Portainer logs or screenshots

No response

Portainer version

2.27.0

Portainer Edition

Business Edition (BE/EE) with Home & Student license

Platform and Version

Docker version 24.0.7, build 24.0.7-0ubuntu2~22.04.1

OS and Architecture

Ubuntu 22.04 amd64

Browser

No response

What command did you use to deploy Portainer?

Ansible:


- name: Configure Portainer
  docker_container:
    name: portainer
    hostname: portainer
    state: started
    restart_policy: unless-stopped
    image: portainer/portainer-ee
    network_mode: host
    volumes:
      - /srv/ssdtank/docker/portainer/data:/data
      - /srv/ssdtank/docker/letsencrypt/config/:/etc/tenshu-ssl:ro
      - /var/run/docker.sock:/var/run/docker.sock
      - /bin/busybox:/bin/sh:ro
    log_driver: journald
    log_options:
      tag: "{{ '{{' }}.Name}}"
    labels:
      net.tenshu.ssl: "true"
      com.centurylinklabs.watchtower.enable: "true"

Additional Information

No response

About this issue

  • Original URL
  • State: open
  • Created 2 years ago
  • Reactions: 9
  • Comments: 69 (7 by maintainers)

Most upvoted comments

Hi all, we have identified the issue and aim to have this patched in our 2.30 release.

Just updated to 2.27.1 and it appears the issue is still present. In my case I have many stack entries such as:

volumes:
  - '$DOCKER_APPDATA_DIR/folder/config:/config'
env_file:
   - "../../global_env_full.env"

I’m in a similar boat to @Jikeh. In addition to having volumes with ${DOCKER_ROOT} in the path, I also have several entries that use labels for Traefik, e.g.,

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.${APP_NAME}.rule=Host(`${APP_NAME}.${DOMAIN}`)"

APP_NAME is provided via the stack’s env vars and passes through into the label just fine, but DOMAIN is expected to come from the host (in this case, the set of env vars passed to Portainer) and does not.

I also have env vars in the stack env section that interpolate the host env vars. I could re-work those if needed, though.

However we still (for now) don’t pass the Portainer container environment to compose when deploying stacks (which is also a compose binary default behaviour)

@xAt0mZ, that’s not correct. Docker Compose allows you to reference the host environment. I tested it just now on the latest versions of Docker (v28.0.1) and Docker Compose (v2.33.1) to confirm. Note that if you’re running with sudo, your env vars won’t be part of the env that docker compose is run with. So this will fail:

export DOMAIN=example.com
sudo docker compose up -d

and if you’re interpolating DOMAIN in your compose file, you’ll get a message like WARN[0000] The "DOMAIN" variable is not set. Defaulting to a blank string. But if you run

sudo su
export DOMAIN=example.com
docker compose up -d
exit

then the references to DOMAIN in your compose file will be resolved correctly.

This is in-line with the Docker docs. From Set environment variables - Use the environment attribute - Additional information

You can choose not to set a value and pass the environment variables from your shell straight through to your containers. It works in the same way as docker run -e VARIABLE ...:

web:
  environment:
    - DEBUG

The value of the DEBUG variable in the container is taken from the value for the same variable in the shell in which Compose is run. Note that in this case no warning is issued if the DEBUG variable in the shell environment is not set.

It’s also referenced in several other places:

  • Environment variables precedence
    • “The order of precedence (highest to lowest) is as follows: … 2. Set with either the environment or env_file attribute but with the value interpolated from your shell or …”
  • Substitute from the shell
    • “You can use existing environment variables from your host machine or from the shell environment where you execute docker compose commands. This lets you dynamically inject values into your Docker Compose configuration at runtime.”

as it is a security risk: any user able to deploy a stack can leak the entire Portainer container environment, which may contain sensible information.

I’m confused as to what sensitive information would be visible. When I run docker inspect portainer | jq '.[0].Config.Env' the only env var that I see other than the ones that I added specifically so they would be available to my stacks is PATH. I realize that more env vars may have been added at run-time and those should of course not be available to the stacks. It’s not trivial to check what those are since Portainer doesn’t include a shell or the env command.

I’m also confused as to how “the entire Portainer container environment” could be leaked. My understanding is that Docker Compose does not provide a means by which all host environment variables can be passed into a container; they have to be referenced individually.

Also, couldn’t someone with the ability to deploy stacks also set up a volume pointing to / and get root access to the entire host file system?

We were honestly not expecting some of you to use this behaviour and are actively discussing internally the next step (likely re-introducing the behaviour for now).

I’m surprised by that, but happy to hear that this is being actively discussed.

Intuitively this feels like it could be added in Portainer environments. That would be more flexible than the way I’m currently using it and would fully support my use case.

But I’m open to any alternative way to portably, across multiple stacks, reuse environment variables (such that they can be interpolated and referenced in both the compose and stack env).

I’m losing faith with Portainer. Their QA/QC has gone downhill in the last few months. I do not understand how bugs like this even get in to LTS or even STS releases without any dev noticing. Surely there are a bunch of CI regressions tests that cover basic user acceptance test cases like “can I deploy a compose stack with an .env file without error?”.

Then, when users report critical issues like this, they remain unfixed and unacknowledged in release notes for months at a time whilst new features are added in.

What’s worse is businesses pay for this critical infrastructure management tool and cannot afford any downtime whilst they investigate and rollback. I would 100% be considering alternatives if I were a business.

Only the other day a 2.29.1 STS release CVE fix broke the ability to even log in to Portainer, yet it was still somehow released without anyone in Portainer noticing. Although it was fixed quickly, unlike this one, it still should never have made it to release. Releases seem to be chucked out with minimal (if any) regression testing at the moment.

I can’t help but feel that the OP’s issue has been hijacked by a different issue here… This issue clearly states it is about “Compose yaml files are no longer interpolated with the contents of .env” NOT about the compose file not being interpolated with the portainer server (host) container’s environmental variables. So why has it been merged with #12555 ?

I appreciate the latter is still an issue, but would it not be better to keep them separate issues to avoid confusing people coming here expecting to see answers for the original issue.

I for one have the OP’s issue and would like to get an update on that in this discussion, not the other issue which is just confusing matters.

@jamescarppe any updates or proper workarounds for the matter? Almost 2 months since the report of a critical feature being broken in a LTS release, yet there are no estimates on fix complexity or timeline.

If I was a customer using Portainer for business, I’d already moved to a different solution.

Any chance we can get an update on this? Would be nice to know if it will be fixed or not.

We’ve been able to reproduce this internally and are working on a fix.

In the meantime we have a potential workaround - if you set an environment variable within the UI, interpolation from the .env file should work as previously. The variable you set doesn’t need to be used by anything, it just needs to exist in the UI.

Image

@velary nope, it’s still broken. To be fair, I tested it by only updating the agent, with server sitting on 2.27.4.

Here’s the stack config I’m using, with secrets amended: https://gist.github.com/hedger/b781af828336b1fa8f26800ffb098698

With agent on 2.29.2, it still fails to interpolate variables from the env file. Trying to pull & update an existing stack from the UI will result in the following error:

An error occurred while running unpacker container with exit code 255: compose up operation failed: unable to get image 'mariadb:': Error response from daemon: invalid reference format

At the same time, I can cd to the folder where it pulls the repo with docker-compose files and do docker compose up -d – and it will happily bring the stack up. It will show up as running and healthy in the UI. Immediately after that, trying to redeploy it again from the UI fails the exact same way.

What’s baffling is that there had been multiple releases in the LTS 2.27 branch, and not a single one even acknowledges this critical issue in the “known issues” section. The lack of communication and recognition of the issue is also just inexplainable.

@jamescarppe care to drop a line, please?

i use the env file to store my folder locations so that if I restore my docker containers on another machine, i would not have to edit all stacks. having the environment file allowed me to change those folders with simple env file change. Now it is a nightmare to recreate the stacks on another machine. instead of just taking away a feature, please either make it backward compatible or provide alternate option.

@jamescarppe , please prioritize this issue.

Hey there

I re-ran all my tests for interpolation. The detailed scripts, stacks and results can be found here

Tests description

Expand me

The repo contains scripts and files to deploy 24 variations of a basic nats stack that is using either a .env or a stack.env file, referencing it (or not) in the compose file.

The content of the file is either (no reference of the env files)

services:
  nats:
    image: nats
    environment:
      - A=${A}
      - B=${B}
      - C=${C}

or (with a reference of the env file)

services:
  nats:
    image: nats
    env_file:
      - .env
      # - stack.env # and/or this line, depending on the scenario
    environment:
      - A=${A}
      - B=${B}
      - C=${C}

All .env files contain

A=env
B=env

All stack.env files contain

A=stack.env
B=stack.env

Tests run the following combinations

  • reference (or not) .env
  • reference (or not) stack.env
  • reference (or not) .env and stack.env
  • -> 3 * 2 = 6 combinations

For each of the above, override (or not) A=ui to verify the environments are properly merged between the file and the env fields in the UI.

  • -> 6 * 2 = 12 combinations

For each of the above, deploy with and without relative paths enabled.

  • On CE it has no impact (with = without)
  • On EE it deploys the stack through the compose-unpacker.
  • -> 12 * 2 = 24 tests in total

Testing environments

  • 2.21.5 -> serves as a reference, known to be a stable Portainer version using the compose binary
  • 2.27.9 -> latest LTS release
  • 2.31.2 -> latest STS release

All Portainer instances are started with -e C="portainer-container-env" so we can validate that the container environment is forwarded (or not) to the stack.


Tests results

Based on the test results, here’s an analysis of the anomalies using 2.21.5 as the baseline reference:

Anomaly Analysis (Business Edition)

1. Variable C Security Fix (Intentional Change)

Note: this was a point reported by you and that we fixed in 2.30.0 by allowing the Portainer container environment variables defined with a PORTAINER_ prefix to be automatically passed to the stack deployment context.

Pattern: Variable C removal was a deliberate security hardening measure

  • 2.21.5 (Vulnerable): C=“portainer-container-env” - Security Issue: Host environment variables were being injected into containers
  • 2.27.9 (Secured): C=“” - Security fix implemented
  • 2.31.2 (Maintained): C=“” - Security fix maintained

Impact: This affects 12 test cases (unpacker scenarios already didn’t forward portainer container env vars) but is the correct behavior. The previous injection of host environment variables into stacks deployment context was a security vulnerability.

2. Environment Variable Loading Failure in 2.27.9 (Actual Bug)

Pattern: Variables A and B incorrectly lose their “env” values in unpacker scenarios

Affected Test Cases:

  • *-unpacker scenarios where .env file should provide values
  • 2.21.5: A=env, B=env ✅
  • 2.27.9: A=“”, B=“” ❌ Bug
  • 2.31.2: A=env, B=env ✅ Fixed

Root Cause: 2.27.9 introduced a legitimate bug in .env file loading when unpacker is active.

3. UI Override + Unpacker Interaction Bug (Actual Bug)

Pattern: Variable B incorrectly loses “env” value when UI override + unpacker are both active

Affected Test Cases:

  • *-ui-unpacker scenarios
  • 2.21.5: B=env ✅
  • 2.27.9: B=“” ❌ Bug
  • 2.31.2: B=env ✅ Fixed

Implementation Timeline

2.21.5 → 2.27.9 (Security Hardening + Accidental Regressions)

Intentional Changes:

✅ Security Fix: Removed host environment variable injection (Variable C)

Unintended Regressions:

❌ Broke .env file loading in unpacker scenarios ❌ Broke UI override + unpacker interaction

2.27.9 → 2.31.2 (Bug Fixes)

Successful Fixes:

✅ Restored .env file loading functionality ✅ Fixed UI override + unpacker interaction


I couldn’t find any regressions on CE in 2.27.9 nor 2.31.2 apart from the C= env var inherited from the Portainer container, which is the correct behaviour (has been fixed in 2.30.0 with PORTAINER_ prefixed env vars)

Same problem here. Even if I manually define the varaibles.

Community Edition 2.27.6 LTS

Thanks @pmharris77, I have raised this with the team

as it is a security risk: any user able to deploy a stack can leak the entire Portainer container environment, which may contain sensible information.

If forwarding the whole env is a security issue, may I suggest that you provide us with a way of setting global variables from the UI, similar to the per-stack variables, and that would be globally available across all stacks?

Correct me if I’m wrong here, but would the security issue not be the same as using any env file? The only difference being that there may be more variables than a single container or stack.

To me this comes down to user awareness/training and risk appetite. I am no expert and continually learning, but I had passwords saved in my env files until I understood the risk better, now I use secrets and an environment variable SECRETSDIR to point at them. But things like my global Appdata, NAS & log folders, local and global domain names, timezones, puid/guid are used in almost every container anyway.

I believe this is actually a quite critical issue. Any ETA on the fix?

is there any plan to fix this behavior ? it used to work earlier, but not now, so it would be a regression or breaking change.

I am using the latest version trying to specify a profile (--profile) on a docker-compose using the COMPOSE_PROFILES env var, but it appears it is not being interpolated.

Hey there, for those of you who still encounter issues, can you edit your above messages and specify if you are using an environment variable inherited from the Portainer container, or from a .env file located besides your compose file in your git repository?

I created the following test suite to cover variations, and 2.27.1 works the same as 2.21.5 when interpolating environment variables from a .env file located besides the compose file in git.

https://github.com/xAt0mZ/portainer-git-feats-test-files/tree/master/env-interpolate


For the explanation

In 2.21.5 it was possible to use the entire Portainer environment when deploying stack files, as we were calling the compose binary directly from inside the Portainer container. However starting from 2.24.0 (when we removed the compose binary and used the compose lib instead) this is not possible anymore.

In 2.27.1 we did fix the .env issue not being read by default (compose binary default behaviour is to read the .env file next to the compose file for interpolation when no --env-file is specified)

However we still (for now) don’t pass the Portainer container environment to compose when deploying stacks (which is also a compose binary default behaviour) as it is a security risk: any user able to deploy a stack can leak the entire Portainer container environment, which may contain sensible information. We were honestly not expecting some of you to use this behaviour and are actively discussing internally the next step (likely re-introducing the behaviour for now).

I’ll jump in with what I think is a related issue:

My Portainer compose.yaml contains these lines:

environment:
  - USERNAME=jason

Which allows all of my Portainer-created containers to reference thusly:

volumes:
  - /home/${USERNAME}/docker/graylog/data:/usr/share/graylog/data

So while I’m not explicitly using an env file, I’m able to reference this single set variable in all of my containers. This setup was working fine for the last 6 months or so, until yesterday after updating Portainer CE to 2.27.0. As @kaneoriley mentioned - it seems only containers I am manually editing the compose file from the Stack Editor are affected. Starting and stopping containers and stacks, as well as restarting the host machine do not affect running containers.

The .env file is stored at /home/user/docker/portainer/docker.env, and is passed to portainer when starting via the command:

docker run -d -p 9000:9000 \
    --name portainer --restart=always \
    --env-file "/home/user/docker/portainer/docker.env" \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v "/home/user/docker/portainer:/data" \
    --health-cmd='wget --no-verbose --tries=1 --spider http://localhost:9000/api/system/status || exit 1' \
    --health-interval=600s \
    --health-timeout=30s \
    --health-start-period=60s \
    --health-start-interval=15s \
    --health-retries=5 \
    portainer/portainer-ce:alpine

The contents of docker.env:

DOCKERDIR=/home/user/docker
MEDIADIR=/mnt/Media
LOCALUID=1000
LOCALGID=1000
LOCALUMASK=022
LOCALTZ=Australia/Adelaide

Until this morning, this worked to allow me to use DOCKERDIR as a variable in any stack I created using the web UI, as the environment for portainer had the value set. An example stack yaml:

services:
  mailrise:
    # Import Device Template
    extends:
      file: /data/template.yml
      service: template-local-user
    # Container
    image: yoryan/mailrise:latest
    container_name: mailrise
    # Network
    hostname: mailrise
    network_mode: bridge
    ports:
      - 172.17.0.1:8025:8025
    # Environment
    volumes:
      - "$DOCKERDIR/mailrise/mailrise.conf:/etc/mailrise.conf"
    # Service
    labels:
      - com.centurylinklabs.watchtower.monitor-only=true
    healthcheck:
      test: mailrise --version || exit 1

I use a template saved at /home/user/docker/portainer/template.yml (which to portainer is /data/template.yml) to save repeating myself a million times in all my stacks for some basic setup stuff, but the contents aren’t really relevant to the problem.

The env file isn’t in the same location as the compose file as that’s not how it’s being used. It’s a portainer env, not a stack specific env, and it just allows me to set global variables which are then available to all stacks. This has all worked perfectly until the 2.27.0 update.

Thanks @pmharris77, I have raised this with the team

@Nick-Portainer don’t know if it makes a difference, but I’m using the EE docker image version of 2.29.2 STS, not the CE version

Hello, from what I can see internally, this was resolved in 2.27.1. Can you please confirm you are on this version and or higher and you are still experiencing this issue?

@Nick-Portainer Confirming same on LTS 2.27.4 and on previous 2.27.3. I did also try STS 2.29.2 but like @pmharris77 - same issue persisted so I rolled back to LTS version.

I ended up having to rollback to version 2.23.0. I used the following command to rollback the database to its previous version: docker run --rm -it --name portainer-database-rollback -v portainer_data:/data portainer/portainer-ce:2.27.0 --rollback

@PedroLMaia Do you know how to roll back to a specific version like 2.23.0? I tried rolling back using your cmd, but it rolls back to 2.27.3, which has the same issue.

Currently, it’s only possible to rollback to the last version you were using before the update. In my case, I was on version 23.0 before updating to 27.0. When I needed to rollback, I could return to 23.0 and then update again to other versions. If any errors occurred, I would rollback back to 23.0.

From what I understand, it’s not possible to rollback directly to a specific version using this method. Because of that, at work, we decided to use virtual machine snapshots. That really saved us, because once we updated from 21.x to 24, and then to 27. When we tried to rollback, the system could only return to 24, not 21.x.

Fortunately, we had a snapshot; otherwise, we would have lost that version. Another important point: several GitLab pipelines depend on .env files that store the image tags used. If we update Portainer carelessly, we might break the entire CI/CD process, since the environment variables defining the images would be affected.

You can update to 2.28.0 - 2.29.2 versions, works fine for me Fix: https://github.com/portainer/portainer/commit/dd98097897fc2dbe437aee24642d8f3a77c12194

I’m using Portainer to deploy a stack where the docker-compose.yml and .env fire are stored in GIT. Until the upgrade to 2.27.1, it was working fine.

Since the upgrade, Portainer complains about not being able to get the contents of the file ‘docker-compose.yml’ and invalid spec because of empty section.

In the portainer logs, I can see that there is a lot messages about variable not set level=warning msg=\"The \\\"EXTERNAL_NC_LIBRARY\\\" variable is not set. Defaulting to a blank string.\""

If I create manually the variables within portainer, everything works as before

This is for immich, I’m using their docker-compose file Here is an extract

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    user: "82:101"
    networks:
      - immich
      - web
    # extends:
    #   file: hwaccel.transcoding.yml
    #   service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
    volumes:
      # Do not edit the next line. If you want to change the media storage location on your system, edit the value of UPLOAD_LOCATION in the .env file
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro
      - ${EXTERNAL_NC_LIBRARY}:/external/nextcloud:ro
    env_file:
      - .env
    depends_on:
      - redis
      - database
    restart: always
    healthcheck:
      disable: false

The directory layout is

/data/v/docker/immich/portainer-compose-unpacker/stacks/immich/docker-immich$ ls -al                                                                                                                                                                     ─╯
total 40
drwxr-xr-x 3 root root    8 Feb 28 10:49 .
drwxr-xr-x 3 root root    3 Feb 28 10:49 ..
-rw-r--r-- 1 root root 4560 Feb 28 10:49 docker-compose.yml
-rw-r--r-- 1 root root 3252 Feb 28 10:49 docker-compose.yml-original
-rwxr-xr-x 1 root root  230 Feb 28 10:49 download-files.sh
-rw-r--r-- 1 root root 1243 Feb 28 10:49 .env
-rw-r--r-- 1 root root  933 Feb 28 10:49 .env-original
drwxr-xr-x 4 root root    8 Feb 28 10:55 .git

For my case, the 2.27.1 update has not solved the issue

My issue is not resolved by 2.27.1, problem remains the same unfortunately.

Edit as per https://github.com/portainer/portainer/issues/12546#issuecomment-2688604043:

I’ve been using environment variables inherited from the Portainer container, as it’s a convenient way to have ‘global’ variables.

I’ve seen the same issue after upgrade to 2.27.0. My docker-compose.yml and .env are stored in a repo in GitLab. Variables used were to specify the Image version and configure traefik via labels.

Example code for the traefik labels: .env

APP_NAME=something
APP_FQDN=something.local
APP_PORT=80

docker-compose.yml

    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=traefik-net"
      - "traefik.http.services.${APP_NAME}.loadbalancer.server.port=${APP_PORT}"
      - "traefik.http.routers.${APP_NAME}.rule=Host(`${APP_FQDN}`)"
      - "traefik.http.routers.${APP_NAME}.entrypoints=http"`

Running ‘docker compose config’ results in everything being replaced correctly. However the container in Portainer is showing labels as: traefik.http.services…loadbalancer.server.port= traefik.http.routers…rule= traefik.http.routers…entrypoints=http"

I’ve now upgraded to 2.27.1. and I’ve moved the variables into my named env_file for the service and redeployed the stack. Still not working, the variables weren’t merged from the application.env file that is explicitly referenced in the docker compose file. Still works correctly when tested with ‘docker compose config’.