Secrets usage in docker-compose

[PowershellScripter]

How do I properly use docker secrets with controlr?

Postgres sets up just fine, but when trying to present the secrets to Controlr, it thinks they are empty. Ive used secrets in other containers this way and the docs say secrets are supported, did something change?

secrets:
postgres_user:
file: /containers/controlr/secrets/pguser
postgres_password:
file: /containers/controlr/secrets/pgpass
aspire_token:
file: /containers/controlr/secrets/aspiretoken
environment:
ASPNETCORE_ENVIRONMENT: Production
ASPNETCORE_HTTP_PORTS: 8080
ControlR_POSTGRES_USER_FILE: /run/secrets/postgres_user
ControlR_POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
ControlR_POSTGRES_HOST: controlr-db
ControlR_AspireDashboard__Token_FILE: /run/secrets/aspire_token

2026-03-07T06:04:20.374146037Z Unhandled exception. System.ArgumentNullException: Value cannot be null. (Parameter 'pgUser')
2026-03-07T06:04:20.374181218Z at System.ArgumentNullException.Throw(String paramName)
2026-03-07T06:04:20.374185717Z at System.ArgumentNullException.ThrowIfNull(Object argument, String paramName)
2026-03-07T06:04:20.374189570Z at System.ArgumentException.ThrowNullOrWhiteSpaceException(String argument, String paramName)
2026-03-07T06:04:20.374192338Z at System.ArgumentException.ThrowIfNullOrWhiteSpace(String argument, String paramName)
2026-03-07T06:04:20.374195407Z at ControlR.Web.Server.Startup.WebApplicationBuilderExtensions.AddPostgresDb(IHostApplicationBuilder builder) in E:\ActionsRunner\controlr-public\_work\ControlR\ControlR\ControlR.Web.Server\Startup\WebApplicationBuilderExtensions.cs:line 326
2026-03-07T06:04:20.374199358Z at ControlR.Web.Server.Startup.WebApplicationBuilderExtensions.AddControlrServer(IHostApplicationBuilder builder, Boolean isOpenApiBuild) in E:\ActionsRunner\controlr-public\_work\ControlR\ControlR\ControlR.Web.Server\Startup\WebApplicationBuilderExtensions.cs:line 76
2026-03-07T06:04:20.374203287Z at Program.<Main>$(String[] args) in E:\ActionsRunner\controlr-public\_work\ControlR\ControlR\ControlR.Web.Server\Program.cs:line 16
2026-03-07T06:04:20.374206818Z at Program.<Main>(String[] args)

[bitbound]

Secrets aren't very intuitive in compose. Here's the official docs: https://docs.docker.com/compose/how-tos/use-secrets/

Each secret is mounted as a file inside the container. So I'd need code in ControlR that explicitly reads each file and adds them to IConfiguration (so it can be used within the app), and there would need to be pre-defined environment variables that ControlR knows to look for. For example, in your above config, I'd need code that gets the file path from ControlR_POSTGRES_USER_FILE environment variable.

I haven't implemented this because I think the pattern would be highly error prone for self-hosting and result in a lot of support requests.

Currently, passing them in via the host's environment variables or via a .env file are the only options.

I've also thought about adding support for a single secret that should point to a json file in the format of appsettings.json, then these values would get merged with those passed in via env vars. That might end up creating confusion too, though.

[PowershellScripter]

󠀠󠀠󠀠ㅤㅤㅤㅤㅤㅤㅤ
Fair enough. You may want to update this part of the documentation as it is what had me assuming secrets could be used 😅
Secrets would be a more secure addition to have since they only are only ever used during the docker container build process and dont have a chance of being exposed in the container env.
ㅤㅤㅤㅤㅤㅤㅤ
ㅤㅤㅤㅤㅤㅤㅤ

[bitbound]

Oh, my bad! I'm sorry to have you misled you there. Thank you for pointing that out, though. I'll updated the readme.

I'm anticipating some non-trivial changes to the configuration soon. For example, I wanted to move to the DB values that aren't needed at application startup. I'll use that opportunity to look into creating a custom configuration provider for Docker secrets.

[bitbound]

Created a issue here to track it: #106

[PowershellScripter]

No worries lol, just didnt want someone else to RTFM and end up the same way 😅

I just try to make remote access tools like vpns or remote desktop utilities as secure as possible (especially in business environments where hardening is required for certain compliance). Unlike secrets, env variables can be exposed in docker ps commands and logs.

Based on info read, secrets and key vaults are the only real secure solutions for passing passwords and tokens into containers.

I will still use the env variables as I have really wanted to try your tool out for awhile.

If a choice had to be made between passwords and tokens through env variables and secrets, I would choose secrets every time.

They are still just as easy to use in docker-compose files as env variables, but more secure as they never get exposed and are only invoked during runtime.

Single docker instances can still use secrets, but they are not used the same way that swarms use them, but the implementation of _FILE is the same between single and swarm.

If you do ever implement support for secrets, postgres already supports secrets and the same secrets file can be called for different docker container variables.

The file path of the file can also be used as an env variable for both containers as well, like so:

secrets:
controlr_database_user:
file: ${POSTGRES_PASS_FILE_PATH}
postgres_pass:
file: ${POSTGRES_PASS_FILE_PATH

env file -

POSTGRES_USER_FILE_PATH = /path/to/pass/file.txt

Not sure if it makes it any more secure, but it makes the organization easier since, if the file path ever changes, it just gets changed in one location instead of multiple places.

I asked grok, the. took the response and had gpt clean it up and here is what was said about how to parse a secrets file like json data.

https://chatgpt.com/s/t_69ad0fb607588191903480f5424d16d1

Hope this helps 🤗

[PowershellScripter]

@bitbound So, I was doing some research and I think I may have found an alternative solution to the secrets debacle. There is a tool called "age" (ahge) and it essentially uses a public private key pair to encrypt and decrypt files. (Its a tool heavily used with Mozilla SOPS for Git, but can also be used locally with just the binary file).

The thought process is, if you add this binary to your container build, this would give flexibility and security. If you build your appsettings.json code, you can add an env variable to say [ CONTROLR_AGE_KEY = value / null ] and that will determine if the appsettings.json takes the plain route of just directly passing the json file to your code, or if age need to decrypt that file before passing the values to the code.

This prevents the settings from being passed as direct env variables to the host, adds a layer of security that the user can choose at runtime and the only requirement for them is to get the age tool an run a simple command to encrypt the file (this is no different than using something like (openssl rand -base64 32) to generate tokens). Then, they can pass the private key to the CONTROLR_AGE_KEY and mount the appsettings.json as RO and your container sees that the CONTROLR_AGE_KEY is not empty and uses that key value to decrypt the settings json.

This is a solution that I believe would work for Docker (non-swarm), Docker Swarm and K3S and even Podman. Give you the ability to not just utilize it with your appsettings.json file idea, but also have a way to secure the whole thing if a user wants to.

Im defintiely no cryptography or docker expert so this is only a theory based on research and conversing with AI 😅

https://github.com/FiloSottile/age

[bitbound]

Thanks for the detailed follow-up on this. I've implemented a solution today, but my brain is too tired at the moment to go into detail. I'll follow up soon. :)

[PowershellScripter]

Fair enough 😀 look forward to checking it out when its released. I just figured if I was going to complain about it, I should try to find a feasible solution to help 😅🤗 glad to hear you found a workable solution 👊🏼

[bitbound]

I'm not sure how deep you want to get into the details. But in ASP.NET Core, there's a standard pattern for providing configuration using APIs provided by the framework. Configuration providers are added to the app using methods like below on the main IConfigurationBuilder:

Some of these get loaded in by default. Others need to be explicitly added. And there are many more providers that can be added via NuGet packages (e.g. Azure Key Vault provider ).

Or you can create your own pretty easily. In most cases, you only need to supply a few details yourself, and the framework handles the rest.

But all of them end up in the same place. At runtime, the values from all sources/providers are added to IConfiguration, which is the basic API used from accessing them. (Then you'd use IOptions for binding them to strongly-typed classes, but that's another topic.) If you compare the appsettings.json and docker-compose.yml files, you'll see environment variables in the compose file are the same values as in appsettings. They just get flattened so they can be represented by a single string. All sources and providers work this way, because they're "feeding the same values" after being consumed.

I try to stick to ASP.NET-idiomatic conventions as much as possible. I also try minimize external dependencies.

Anyhow, creating a provider that loads Docker secrets into IConfiguration is a trivial task. What I wasn't certain about was how to present it in a way that minimizes confusion, can still be debugged without manual file changes, and still runs everywhere by default. I have two environments (one running bare metal and one on Railway) where Docker Secrets aren't available, and I'm sure there are others I haven't even thought of (e.g. someone recently mentioned Nomad, which I hadn't heard of). So I need to keep things as platform-agnostic as possible.

So I settled on a convention: Secrets would get loaded into IConfiguration using their file names as the keys. That way, to override any existing ControlR_ environment variable, you'd just create a secret with the same name (minus the "ControlR_" prefix).

Here's the funny part! 😄

I was searching to see if it was possible for Aspire Dashboard to use Docker Secrets instead of environment variables (because it's not mentioned in their official docs), and I found a PR, which then led me to here: https://github.com/dotnet/aspire/blob/main/src/Aspire.Dashboard/DashboardWebApplication.cs#L165

So yep, they support but, but also there's a built-in KeyPerFile provider that does almost exactly the same thing as what I just made (which can be seen on the above screenshot).

I'm deleting my version now and will use the built-in provider. It will be included in the next release. 🙂

[BeardedTek]

I actually took a different approach to setting up compose for controlr using env_file for everything and traefik as the reverse proxy:

docker-compose.yml

name: controlr-beardedtekservices:
controlr:
image: bitbound/controlr:latestcontainer_name: controlrrestart: unless-stoppeddepends_on:
- postgres
- aspirenetworks:
- controlr-network
- proxyenv_file:
- .envlabels:
- "traefik.enable=true"
- "traefik.http.routers.controlr.rule=Host(`${TRAEFIK_DOMAIN_NAME:-controlr.example.com}`)"
- "traefik.http.routers.controlr.entryPoints=https"
- "traefik.http.routers.controlr.tls=true"
- "traefik.http.routers.controlr.tls.certresolver=le"
- "traefik.http.routers.controlr.service=controlr-entrypoint"
- "traefik.http.services.controlr-entrypoint.loadbalancer.server.port=8080"postgres:
image: postgres:18container_name: postgresrestart: unless-stoppednetworks:
- controlr-networkvolumes:
- postgres-data:/var/lib/postgresqlenv_file:
- .envaspire:
image: mcr.microsoft.com/dotnet/aspire-dashboard:13.1container_name: aspirerestart: unless-stoppedports:
- "18888:18888"expose:
- "18889"networks:
- controlr-networkenv_file:
- .envvolumes:
postgres-data:
name: "postgres-data"networks:
controlr-network:
driver: bridgetraefik:
external: true

.env

# Traefik domain nameTRAEFIK_DOMAIN_NAME=controlr.example.com# Core database and Aspire settingsControlR_POSTGRES_USER=postgresControlR_POSTGRES_PASSWORD=change_meControlR_POSTGRES_HOST=postgresControlR_POSTGRES_PORT=5432ControlR_POSTGRES_DB=controlrControlR_ASPIRE_BROWSER_TOKEN=change_me# ASP.NET Core hostingASPNETCORE_ENVIRONMENT=ProductionASPNETCORE_HTTP_PORTS=8080# ControlR server optionsControlR_AspireDashboard__Token=${ControlR_ASPIRE_BROWSER_TOKEN}ControlR_AspireDashboard__PublicWebUrl=http://localhost:18888ControlR_AppOptions__EnablePublicRegistration=falseControlR_AppOptions__AllowAgentsToSelfBootstrap=falseControlR_AppOptions__AuthenticatorIssuerName=ControlRControlR_AppOptions__PersistPasskeyLogin=falseControlR_AppOptions__EnableCloudflareProxySupport=falseControlR_AppOptions__EnableNetworkTrust=falseControlR_AppOptions__DockerGatewayIp=::ffff:172.29.0.1ControlR_AppOptions__MaxFileTransferSize=104857600ControlR_AppOptions__RequireUserEmailConfirmation=trueControlR_AppOptions__DisableEmailSending=false# Logging and telemetryControlR_OTLP_ENDPOINT_URL=http://aspire:18889ControlR_Logging__LogLevel__Default=InformationControlR_Logging__LogLevel__Microsoft.AspNetCore.HttpLogging=InformationControlR_Logging__LogLevel__Microsoft.AspNetCore.HttpOverrides=DebugControlR_AppOptions__UseHttpLogging=false# SMTP (leave empty or configure as needed)ControlR_AppOptions__SmtpDisplayName=ControlR_AppOptions__SmtpEmail=ControlR_AppOptions__SmtpHost=ControlR_AppOptions__SmtpLocalDomain=ControlR_AppOptions__SmtpCheckCertificateRevocation=trueControlR_AppOptions__SmtpPassword=ControlR_AppOptions__SmtpPort=587ControlR_AppOptions__SmtpUserName=# Optional proxy configuration (uncomment and set as needed)#ControlR_AppOptions__KnownProxies__0=ControlR_AppOptions__KnownNetworks__0=172.18.0.0/16# Optional external auth (leave empty unless configured)#ControlR_AppOptions__MicrosoftClientId=#ControlR_AppOptions__MicrosoftClientSecret=#ControlR_AppOptions__GitHubClientId=#ControlR_AppOptions__GitHubClientSecret=# Postgres container variablesPOSTGRES_USER=${ControlR_POSTGRES_USER}POSTGRES_PASSWORD=${ControlR_POSTGRES_PASSWORD}POSTGRES_DB=${ControlR_POSTGRES_DB}

[bitbound]

@BeardedTek Totally valid setup! 🙂 This will continue working the same after the update, and Docker Secrets will be purely optional.