Hands-on Lab

Managing Secrets in Docker (without baking them into the image)

July 17, 2026 3 min

0 / 9

Cheat sheet

Found it useful? Don't miss the next lab

0:00 / 0:00

Write the Dockerfile for the most common anti-pattern: ARG defines a build-time variable (defaulting to changeme), ENV promotes it into a persistent image environment variable, and the RUN instruction also writes it into a file inside a layer. Three different places where the same value gets fossilized and stays readable later.

mkdir -p /lab/leaky && cd /lab/leaky && cat > Dockerfile <<'EOF'
FROM alpine:3.20
ARG API_TOKEN=changeme
ENV API_TOKEN=$API_TOKEN
RUN echo "using token: $API_TOKEN" > /app-info.txt
CMD ["cat", "/app-info.txt"]
EOF
cat Dockerfile

I did it

Build the image passing the secret as a build-arg, exactly the way a CI pipeline might (wrongly) try to 'inject' a credential into the build. Docker accepts the flag without complaint: no error, just an image that already carries the secret inside.

cd /lab/leaky && docker build --build-arg API_TOKEN=changeme -t leaky-app:1.0 .

I did it

Confirm the leak with two read-only commands: docker history shows the RUN layer that used the token in plain text, and docker inspect reveals it was also stored as an image environment variable. Anyone with access to leaky-app:1.0 —on a registry, in a backup, from an accidental pull— can read the secret without ever running the container.

echo '--- docker history: capa que usó el token ---'; docker history --no-trunc leaky-app:1.0 | grep -i token; echo '--- docker inspect: token guardado como env de la imagen ---'; docker inspect leaky-app:1.0 --format '{{json .Config.Env}}'

Create the secret as a separate file, outside any build context directory, with 600 permissions so only root can read it. It's the same 'changeme' placeholder from the previous step, but now it lives in a file we control exactly when and how to expose, instead of being fixed forever inside an image.

mkdir -p /lab/secrets && printf '%s' 'changeme' > /lab/secrets/api_token && chmod 600 /lab/secrets/api_token && ls -l /lab/secrets/api_token

I did it

Confirm the file exists with 600 permissions and 8 bytes of content, and that it sits outside any directory a COPY instruction would ship into an image. This is the foundation the next three safe techniques build on.

stat -c '%a %s %n' /lab/secrets/api_token

The # syntax=docker/dockerfile:1 directive turns on BuildKit's extended syntax. RUN --mount=type=secret,id=api_token makes the file available ONLY inside that one instruction, at /run/secrets/api_token, without ever being recorded as an ARG, an ENV, or copied into a layer: the moment the RUN finishes, the mount is gone.

mkdir -p /lab/safe-build && cd /lab/safe-build && cat > Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
FROM alpine:3.20
RUN --mount=type=secret,id=api_token \
    test -s /run/secrets/api_token && \
    echo "build used a secret of $(wc -c < /run/secrets/api_token) bytes" && \
    echo "no secret baked into this layer" > /build-note.txt
CMD ["cat", "/build-note.txt"]
EOF
cat Dockerfile

I did it

--secret id=api_token,src=/lab/secrets/api_token tells BuildKit which host file to mount under that identifier, which must match the id used in the Dockerfile's RUN --mount. BuildKit has been the default builder since Docker 23, so no extra environment variable is needed.

cd /lab/safe-build && docker build --secret id=api_token,src=/lab/secrets/api_token -t safe-app:1.0 .

I did it

Neither docker history nor the image's Env array contain the token: the build genuinely used it —the previous step's message confirms it read 8 bytes— but it never wrote it into a layer. Compare this clean output with the leak in the reveal-leak step.

echo '--- docker history (sin coincidencias esperadas) ---'; docker history --no-trunc safe-app:1.0 | grep -i token; echo '--- docker inspect env (sin API_TOKEN esperado) ---'; docker inspect safe-app:1.0 --format '{{json .Config.Env}}'

For a secret needed at runtime (not at build time), mount the host file directly as :ro inside the container. The process reads it like any regular file, it never shows up in docker inspect as an environment variable, and :ro stops the container from modifying it.

docker run --rm -v /lab/secrets/api_token:/run/secrets/api_token:ro alpine:3.20 sh -c 'echo "container read a secret of $(wc -c < /run/secrets/api_token) bytes from a mounted file"'

I did it

We attempt to write over the read-only mount from inside the container, even as root. The write fails with a filesystem error and a non-zero exit code: the :ro flag is enforced at the mount level, not at the user-permission level, so the original file on the host stays untouched.

docker run --rm -v /lab/secrets/api_token:/run/secrets/api_token:ro alpine:3.20 sh -c 'echo overwritten > /run/secrets/api_token; echo "write attempt exit code: $?"'

Create a .env file with the secret and exclude it from the build context via .dockerignore, so a stray COPY . could never accidentally ship it. Start a background container with --env-file .env to inspect in the next step: this pattern is common in local development, but it has an important caveat we're about to check.

cd /lab/safe-build && printf 'API_TOKEN=changeme\n' > .env && printf '.env\n' > .dockerignore && docker run -d --name envfile-demo --env-file .env alpine:3.20 sleep 300

I did it

Here's the caveat: the .env file keeps the secret out of the IMAGE, but docker inspect on the running CONTAINER still shows it in plain text inside Env. It's safer than ARG/ENV in the Dockerfile, but weaker than a file mount or Compose secrets against anyone with access to the Docker socket.

docker inspect envfile-demo --format '{{json .Config.Env}}'

Compose's secrets: block is file-based and works with a plain docker compose up, no Swarm needed: it mounts /lab/secrets/api_token as /run/secrets/api_token inside the app service, read-only, and never goes through an ARG or an ENV. -d leaves it running in the background so we can inspect it in the next step.

mkdir -p /lab/compose-secrets && cd /lab/compose-secrets && cat > compose.yaml <<'YAML'
services:
  app:
    image: alpine:3.20
    command: 'sh -c "echo secret length: $(wc -c < /run/secrets/api_token) && sleep 60"'
    secrets:
      - api_token
secrets:
  api_token:
    file: /lab/secrets/api_token
YAML
cd /lab/compose-secrets && docker compose up -d

I did it

Two checks at once: the logs show the service read the secret fine (secret length: 8), and docker inspect on that same container has no trace of API_TOKEN in Env, unlike the envfile-demo from the previous step. The secret reached the process only as a mounted file.

cd /lab/compose-secrets && sleep 2 && docker compose logs app && CID=$(docker compose ps -q app) && docker inspect "$CID" --format '{{json .Config.Env}}'

Tear down everything the lab created: the envfile-demo container, the Compose stack with its volumes (-v), both the leaky-app and safe-app images, and the entire /lab working directory, so no secret or compromised image is left behind on this disposable host.

docker rm -f envfile-demo >/dev/null 2>&1; cd /lab/compose-secrets && docker compose down -v >/dev/null 2>&1; docker rmi -f leaky-app:1.0 safe-app:1.0 >/dev/null 2>&1; rm -rf /lab; echo 'cleanup done'

I did it

Confirm the final state: neither docker ps nor docker images show anything from this lab, and /lab no longer exists. The host is back exactly the way it was before we started, with no leftover demo secret on disk.

echo '--- contenedores restantes ---'; docker ps -a --format '{{.Names}}' | grep -E 'envfile-demo|compose-secrets'; echo '--- imagenes restantes ---'; docker images --format '{{.Repository}}:{{.Tag}}' | grep -E 'leaky-app|safe-app'; echo '--- directorio /lab ---'; ls /lab 2>/dev/null || echo '/lab removed, all clean'

Was this lab useful? Rate it:

Click to rate this post!

[Total: 0 Average: 0]

Docker secrets management is not optional

Docker secrets management starts by assuming that anything passed through a Dockerfile’s ARG, ENV, or COPY gets written into the image’s layers and metadata forever, visible to anyone who pulls the image via docker history or docker inspect. In this lab we first manufacture the leak, then fix it with four techniques that genuinely keep the secret out of the image: a BuildKit build secret, a read-only file mount, a properly scoped env-file, and Docker Compose’s native secrets without needing Swarm.

Which technique to use, and when

If the secret is only needed while the image is being built (a private key to clone a repository, a token to fetch a dependency), docker build --secret mounts it at /run/secrets/ only for that one RUN instruction and it never reaches a layer. If the running process needs the secret instead, a read-only (:ro) file mount or Compose’s secrets: block keep it out of the container’s Env, which is exactly what --env-file does not do. Teams managing credentials at scale should consider a dedicated manager like HashiCorp Vault, and real clusters running Docker Swarm also get docker secret create, encrypted in the cluster’s Raft log.

Keep going

See our guide to environment variables and secrets in Docker Compose, and if you haven’t installed Docker yet, our guide to installing Docker on Debian. More reproducible labs live in the Tools category and among our other hands-on labs. The official reference for RUN --mount=type=secret is Docker’s Dockerfile reference, Compose secrets are detailed in the Compose Specification, and OWASP’s Docker Security Cheat Sheet covers broader best practices.

FAQ

Why shouldn't I put a secret in a Dockerfile's ARG or ENV?

Because both get baked into the image's layers and metadata forever: anyone who runs docker history or docker inspect on that image can read it, even if you "delete" it in a later instruction — the earlier layer is still there.

What is a BuildKit build secret and how is it different from ARG?

docker build –secret mounts a file at /run/secrets/ only for the RUN instruction that requests it and never writes it to a layer or the history. ARG, by contrast, gets recorded as part of the image's build metadata.

Is it safe to use –env-file with docker run?

It's better than ARG/ENV in the Dockerfile because the secret never touches the image, but it's still visible via docker inspect on the running container. For runtime processes, a read-only file mount or Compose secrets are safer.

Do I need Docker Swarm to use Compose secrets?

No. The top-level secrets: block with a file: driver works with a plain docker compose up on a single host. docker secret create and encrypted storage in the Raft log do require a cluster started with docker swarm init.

Cheat sheet

mkdir -p /lab/leaky && cd /lab/leaky && cat > Dockerfile <<'EOF'
FROM alpine:3.20
ARG API_TOKEN=changeme
ENV API_TOKEN=$API_TOKEN
RUN echo "using token: $API_TOKEN" > /app-info.txt
CMD ["cat", "/app-info.txt"]
EOF
cat Dockerfile

cd /lab/leaky && docker build --build-arg API_TOKEN=changeme -t leaky-app:1.0 .

mkdir -p /lab/secrets && printf '%s' 'changeme' > /lab/secrets/api_token && chmod 600 /lab/secrets/api_token && ls -l /lab/secrets/api_token

mkdir -p /lab/safe-build && cd /lab/safe-build && cat > Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
FROM alpine:3.20
RUN --mount=type=secret,id=api_token \
    test -s /run/secrets/api_token && \
    echo "build used a secret of $(wc -c < /run/secrets/api_token) bytes" && \
    echo "no secret baked into this layer" > /build-note.txt
CMD ["cat", "/build-note.txt"]
EOF
cat Dockerfile

cd /lab/safe-build && docker build --secret id=api_token,src=/lab/secrets/api_token -t safe-app:1.0 .

docker run --rm -v /lab/secrets/api_token:/run/secrets/api_token:ro alpine:3.20 sh -c 'echo "container read a secret of $(wc -c < /run/secrets/api_token) bytes from a mounted file"'

cd /lab/safe-build && printf 'API_TOKEN=changeme\n' > .env && printf '.env\n' > .dockerignore && docker run -d --name envfile-demo --env-file .env alpine:3.20 sleep 300

mkdir -p /lab/compose-secrets && cd /lab/compose-secrets && cat > compose.yaml <<'YAML'
services:
  app:
    image: alpine:3.20
    command: 'sh -c "echo secret length: $(wc -c < /run/secrets/api_token) && sleep 60"'
    secrets:
      - api_token
secrets:
  api_token:
    file: /lab/secrets/api_token
YAML
cd /lab/compose-secrets && docker compose up -d

docker rm -f envfile-demo >/dev/null 2>&1; cd /lab/compose-secrets && docker compose down -v >/dev/null 2>&1; docker rmi -f leaky-app:1.0 safe-app:1.0 >/dev/null 2>&1; rm -rf /lab; echo 'cleanup done'

Found it useful? Don't miss the next lab

Subscribe to the newsletter

Docker secrets management is not optional

Which technique to use, and when

Keep going

FAQ

Why shouldn't I put a secret in a Dockerfile's ARG or ENV?

What is a BuildKit build secret and how is it different from ARG?

Is it safe to use –env-file with docker run?

Do I need Docker Swarm to use Compose secrets?

Cheat sheet