Secrets and Docker builds on Voroa
Why a credential must never be passed as a Docker build argument, where Voroa keeps secret values instead, and how your service reads them while it runs.
Every instruction a Docker build runs is recorded in the finished image. That includes the build arguments it was given and any file it copied in, even if a later step deletes the file. Anyone who can pull or inspect that image can read those values back. This is how images work; it is not something a platform can undo for you.
So the rule is short: never pass a token, password or private key as a build argument, and never copy one into an image.
What is safe to pass at build time
Values that are already public once your service ships. A frontend build that bakes in an API base URL or an analytics key is the usual case — those end up in a JavaScript bundle any visitor can read, so recording them in the image changes nothing.
On Voroa these are the environment variables you mark as available at build time. Voroa deliberately keeps a short list of names out of the build entirely, so a variable that controls how your program behaves at runtime cannot silently change how it is built.
Where a secret should live instead
Give it to your service when it runs, not when it is built. Voroa offers two ways, and neither of them reaches the image.
Environment variables. Add them under the service’s Environment section. They are stored encrypted and are given to your container when it starts. A value can be replaced but never read back — not by you, and not by us — so keep your own copy somewhere safe.
Secret files. For anything that has to be a file on disk — a certificate, a service-account
JSON, a private key — add it as a secret file. Voroa places it at /etc/secrets/<name> inside your
container, read-only. Your Dockerfile does not mention it and the image does not contain it; it is
mounted at run time.
// reading a secret file at runtime
const key = require('fs').readFileSync('/etc/secrets/service-account.json', 'utf8');
If your build itself needs a credential
Some builds genuinely need one — most often a token to install a package from a private registry. Reading a secret during the build is not available on Voroa yet, and we would rather say that than suggest a workaround that ends with your token inside an image.
What to do in the meantime, in order of preference:
- Vendor the dependency. Commit the package, or publish it to a registry your build can read without a credential.
- Build the artifact elsewhere and have your Dockerfile copy in the result, so the credential stays where it already is.
- Contact support and tell us what you are trying to install. It helps us prioritise, and there may be a specific answer for your registry.
What not to do: pass the token as a build argument “just for now”. It is in the image from that build onwards, and rebuilding without it does not remove it from the images already built.