Staaarter Tools

Docker Secrets Generator

Generates a Docker secrets block for Compose or Swarm, toggled between a file-based secret (backed by a local file) and an external secret (created ahead of time in the cluster), the service-side secrets: reference with a target mount path, and a matching BuildKit --secret build-time usage snippet that keeps the value out of image layers. A free online tool from Staaarter, right in your browser.

Runs locallyUpdated 2026-07-26
generatordockersecurity

Overview

Introduction

Passing a database password or API key to a container as a plain environment variable or baking it into an image with COPY are both easy to reach for and both leave the secret exposed, in `docker inspect` output or in a recoverable image layer.

This tool generates the secrets: block Docker Compose and Swarm both understand, toggled between file-based and external secrets, plus a BuildKit --secret snippet for keeping a secret out of the image entirely during the build itself.

What Is Docker Secrets Generator?

A generator for the top-level secrets: key (file-based via `file:` or external via `external: true`), the per-service secrets: reference that mounts it at a target path, and a separate BuildKit build-time secret snippet.

The build-time snippet covers both sides: the `RUN --mount=type=secret` line for the Dockerfile and the matching `docker build --secret id=...,src=...` command that supplies it.

How Docker Secrets Generator Works

For a file-based secret, the generator emits `file: <path>` under the secret's top-level entry, pointing at a local file Compose or Swarm reads at deploy time. For an external secret, it emits `external: true`, meaning the secret must already exist in the cluster via `docker secret create`.

The service-side reference uses the long syntax (`source`/`target`) so the mount path inside the container can differ from the secret's name, and the runtime mount path always resolves to /run/secrets/<target> unless you override it. The BuildKit snippet is generated independently, since build-time secrets and runtime secrets are two different mechanisms that happen to share terminology.

When To Use Docker Secrets Generator

Use it whenever a service needs a credential, an API key, database password, TLS private key, and you want it delivered as a mounted file instead of an environment variable or a baked-in layer.

Use the BuildKit snippet specifically when a build step itself needs a credential, for example a private package registry token needed only during `npm install`, without that token ending up in the final image.

Often used alongside Docker Compose Generator, Docker Swarm Stack Generator and Dockerfile Generator.

Features

Advantages

  • Keeps secrets out of environment variables and image layers, both easier to accidentally leak than a mounted file.
  • Covers both runtime secrets (Compose/Swarm secrets:) and build-time secrets (BuildKit --secret) with one tool, since they're easy to conflate but use different mechanisms.
  • Produces the long-form service secrets: syntax, letting the in-container mount path differ from the secret's name.

Limitations

  • Doesn't create the actual secret, whether that's writing the local file for file-based mode or running `docker secret create` for external mode, that step still happens outside this tool.
  • External secrets require a real Swarm cluster or a Compose version that supports the external: true syntax; a plain single-host `docker compose` setup without Swarm mainly benefits from the file-based mode.

Examples

An external secret for a database password

Input

secretName: db_password, mode: external, targetMountPath: /run/secrets/db_password, serviceName: api

Output

secrets:
  db_password:
    external: true

services:
  api:
    secrets:
      - source: db_password
        target: db_password

# The secret is mounted read-only inside the container at:
# /run/secrets/db_password

# BuildKit build-time secret usage (kept out of image layers):
# Dockerfile:
# RUN --mount=type=secret,id=db_password cat /run/secrets/db_password

# Build command:
# DOCKER_BUILDKIT=1 docker build --secret id=db_password,src=./secrets/db_password.txt .

external: true tells Compose/Swarm the secret was already created in the cluster with docker secret create.

Best Practices & Notes

Best Practices

  • Prefer external secrets for anything reaching a real Swarm cluster; reserve file-based secrets for local development where the file itself is already gitignored.
  • Never COPY a secret file into an image directly, use the BuildKit --mount=type=secret snippet for anything a build step needs.
  • Give the secret's target name inside the container a clear, application-expected name even if the secret's source name in the cluster is different (e.g. a versioned name like db_password_v2).

Developer Notes

The generated build command always assumes BuildKit is enabled via DOCKER_BUILDKIT=1, since --mount=type=secret and --secret are BuildKit-only features not available in the legacy builder. The service-side reference always uses the long source/target syntax rather than the short list-of-names syntax, since it's strictly more flexible (it supports a differing in-container name) at no extra cost.

Docker Secrets Generator Use Cases

  • Delivering a database password or API key to a running Compose/Swarm service as a mounted file
  • Supplying a private registry token to `npm install` or `pip install` during a build without it ending up in the image
  • Documenting a project's expected secret names and mount paths for a teammate setting up their environment

Common Mistakes

  • Passing a secret as a plain environment variable instead of a mounted file, making it visible via `docker inspect` or a stack trace that dumps the environment.
  • COPYing a secret file into the image and deleting it in a later RUN step, forgetting that earlier layers still contain it permanently.
  • Forgetting DOCKER_BUILDKIT=1 (or a Buildx builder) when trying to use --secret, which silently fails on the legacy builder.

Tips

  • Pair this with the Docker Swarm Stack Generator when the secret needs to reach a service deployed with `docker stack deploy`.
  • Use the Docker Compose Generator to build out the rest of the service definition this secret attaches to.

References

Frequently Asked Questions