Building a production Docker image for Backstage

Bake only the base configuration into the image: the settings that are identical in every environment, such as plugin wiring, feature flags that do not change between stages, and the catalog and template locations that every instance should load. Everything that differs between development, staging and production, or that is a secret, belongs outside the image. That includes the database host and credentials, the sign-in client secret, integration tokens, the external URL of the portal and any cache endpoint. Backstage reads these through environment variables referenced from the config files, so the same image can run everywhere and the values arrive at container start. Keep the file list short and deliberate, because every file you copy is a file someone can read from the image later.

Backstage merges several app-config*.yaml files in the order they are passed on the command line, with later files overriding earlier ones. A common pattern is an app-config.yaml holding the defaults, an app-config.production.yaml loaded when the process runs in production, and optional overrides supplied at runtime. Confirm the exact startup flags and file names against the configuration documentation for your Backstage version before you write the container command. The production file must not inherit development defaults: a backend.database block that points at SQLite, or a guest sign-in provider, will ship to production silently if it is left in the base file. Move those settings into development-only files and check the final merged configuration in a staging container before release.

Keep one image for all environments and promote it unchanged from test to production, so the artifact you tested is the artifact you run. Frontend configuration deserves a specific check. In the default setup the backend injects the frontend configuration at runtime, so values set through the same layered files reach the browser without a rebuild. If you later serve the frontend separately from NGINX or a CDN, that injection stops and the static bundle must carry or load its own configuration, which changes what belongs in the image. Ask your platform team to confirm which values the browser needs and where they will come from before you decide what to copy.

Keep credentials out of the Backstage image entirely. Docker stores every instruction that changes the filesystem as a layer, and docker history exposes the arguments used to build each one. A token passed with ARG or ENV during the build, or a .env or app-config.local.yaml file copied in with COPY . . and deleted in a later RUN rm step, still exists in an earlier layer. Anyone who can pull the image can recover it, so deleting the file afterward does not remove the secret. Treat any value that reached a build step as exposed and rotate it.

The correct pattern splits secrets from the artifact. Config that is safe to ship, such as the base URL, plugin switches and the catalog locations, belongs in the image or a mounted app-config.production.yaml. Tokens for GitHub, GitLab, the database and the auth provider should be referenced by environment variable name in config (for example ${POSTGRES_PASSWORD}) and injected at runtime from your platform's secret store, typically a Kubernetes Secret populated by an external secret operator or your vault. Where a build step truly needs a credential, such as a private npm registry during yarn install, use a BuildKit secret mount (RUN --mount=type=secret) so the value is available to that single command and is not written to a layer. Confirm your Docker and BuildKit versions support this in your build pipeline before relying on it.

Add a .dockerignore file before the first build. It should exclude .env*, *.pem, *.key, local app-config.local*.yaml files, .git, and any node_modules or dist output that should be rebuilt inside the image. Then check the result: build the image, run docker history --no-trunc on it, and search every layer and the exported filesystem for known token prefixes and high-entropy strings. Use a dedicated image scanner for secret detection in addition to vulnerability scanning, and repeat the check in CI for every build. Only push to a registry after the scan passes, because a secret pushed once remains in the registry's layer history even after you delete the tag.

DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside the client's own infrastructure, including their cloud accounts, data centers and air-gapped networks. For a production Backstage image, the work is agreed as a written, fixed scope before any build starts. That scope names the deliverables: the Dockerfile and build pipeline, how the app-config.yaml layers are split between the image and the runtime environment, how secrets are injected without landing in image layers, how the image is scanned, and how it is rebuilt when the Backstage release line moves. Each item is written down so the client knows what they receive and what they must provide, such as the registry, the CI runner, and the list of plugins that need to be included.

Because Backstage ships a main release line monthly and a next release line weekly, the image is a moving target. DeployOpen can run the rebuild and upgrade work as an ongoing retainer rather than a one-off project, so that new base images, Node.js changes and security backports are applied on a schedule your team agrees. Confirm during scoping how often rebuilds should happen, who approves a promoted image, and where scan results are reviewed. DeployOpen does not publish a price list. A quote follows from the agreed scope, and the drivers of that quote are the number of custom plugins, the number of build targets and environments, the registry and CI setup, and whether the client wants ongoing retainer support after handover.