2026-09-05 · 8 min read
- portainer
- docker-compose
- configuration
Compose configuration has several variable boundaries. Interpolation resolves ${NAME} expressions while building the application model, service environment settings populate a container at runtime, and build arguments affect image creation. Similar names across these phases do not make them interchangeable.
Portainer can supply stack variables through its UI or deployment workflow, while a local Compose command may load values from the invoking shell and local files. A stack that works on a laptop can therefore render differently in Portainer without any YAML syntax error.
Inventory each variable by phase
For every name, record where it is referenced, where its value comes from, whether empty and unset differ, and whether it is public configuration or a secret. Start with interpolation, then inspect the resulting service model, image build, and container process.
- Interpolation chooses values used to render the Compose model.
- environment and env_file contribute container values.
- ARG affects builds; ENV in the image supplies image defaults.
- Application configuration may add another precedence layer.
Use explicit defaults and required checks
Compose interpolation supports default and required forms, but their behavior depends on whether a value is unset or empty. Use required checks for deployment-critical names and defaults only when one value is genuinely safe in every target environment.
Quote values that YAML could otherwise type unexpectedly, and avoid reusing one name for unrelated build-time and runtime meanings. Case differences are distinct on common container platforms even when a developer workstation hides them.
Keep secrets outside diagnostic output
Prefer platform-supported secrets for credentials and private keys. Rendered models, container inspection, support bundles, and application debug endpoints can expose environment values, so sanitize them before storage or comparison.
- Commit variable names and safe examples, never secret values.
- Mark browser-exposed build variables as public by design.
- Rotate credentials if a rendered configuration leaked them.
- Limit who can inspect containers and stack configuration.
Verify the deployed container
Use Flashman's Portainer env helper on a redacted source, diff for sanitized effective models, case converter for naming drift, JSON formatter for redacted inspect data, and Base64 only for disposable encoding fixtures—not as secret protection.
Test unset, empty, defaulted, required, shell, UI, env-file, explicit service, image-default, and application-level values. Verify image rebuilds, stack updates, container recreation, health checks, rollback, and parity across environments.