Best practices for managing secrets with Arcane

[llaumgui]

Hi,

I recently migrated from Portainer to Arcane, and I have to say the tool is really great 👍
I’ve even connected agents on my other servers, which gives me a single, unified interface across all my infrastructure.

Now I’m starting to think about secrets management.

So far, I’m still using .env files, but that means secrets are stored in clear text, which is not ideal.
Before going further, I’d like to understand what the recommended best practices with Arcane are regarding secrets:

Is there a native way to manage secrets securely in Arcane?

Is it expected to rely on external tools (e.g. Docker secrets, SOPS, Vault, etc.)?

Are there any plans or guidelines documented somewhere for secret management?

In short: what is the “Arcane way” to avoid keeping secrets in plain text .env files?

Thanks in advance for your guidance, and congrats again on the project 🚀

[kuya1284]

I use the Docker Secrets implementation. Just add the __FILE suffix to the end of your environment variable and store your secrets in a file on the filesystem in a secure location (i.e. /opt/secrets/app/db-password).

This is what I do for all my containers that require a password/key/token.

[llaumgui]

Good solution for container that support the _FILE suffix... But not a global solution.

[kuya1284]

Sorry, I thought you were asking specifically about Arcane. I'm now realizing that you were referring to all projects/containers managed via Arcane.

[ymickler]

I have a similar issue and would like to find a good solution.
I could use a global .env and use env_file in compose, but it injects these variable in the service directly and I can't use these variables in compose with $ prefix

[peitschie]

I'm interested in this also. I'm attempting full infrastructure as code, and am hoping to use SOPS or a similar setup so I can maintain cross-container credentials more easily.

My understanding is that this needs some way to run a hook after checkout/pull for gitsync projects. I believe there used to be hooks for this but they were removed for security reasons?

[peitschie]

@kmendell can I request a bit of your attention here? This is something I'd love to help solve if you desire help. I am a software dev by trade... not go-native, but technically capable. I'd be likely contributing with a lot of claude code assistance.

From spending a bit of time today looking at the code and checking for other existing solutions in the space, here's some ideas that cover combinations of #1707 / #2249 / #2301.

They both fix the exact use-case here (handling secrets)... but might be complementary solutions too.

1. Pluggable secrets backends

A typed SecretsBackend.Decrypt(src) → map[string]string interface in core. The first implementation would be SOPS (age keys) specifically (this is my own use case).

Effectively:

• Global: backend config in settings UI (e.g. SOPS age key path).
• Per-project: .arcane/secrets.yaml declares { backend, sources: [{ path, format, scope }] }. Same shape if configured via UI instead. Can handle this a different way if you want to keep avoiding arcane specific files like this
• Runtime: before compose-go load, decrypt declared sources, merge into compose Environment. Clear-text lives in process memory only for the deploy.

Repo config is data interpreted through a typed schema instead of a command surface to avoid untrusted input or executables that the container hooks struggled with. This would address this issue fully, and part of of #2249, much of #2301 (perhaps).

2. Approval-gated lifecycle commands

Per-project preDeployCommand (argv form), optionally in .arcane/lifecycle.yaml (again, same question about arcane specific files...) in the synced project directory.

Repo-sourced commands are hashed on sync and deploy refuses to run until an admin approves the change. Per-environment auto-approve toggle exists, off by default and logged on change, but user could be turned on for gitops sources selectively (e.g., when sync is coming from a trusted repository always).

The specific approval design avoids the issues from #1468. It does mean a bit more complexity in the UI state for containers (can be blocked waiting approval, need to consider how webhook-pushes interact, etc.) Can be leveraged to implement sops decryption, but also closes the broader #2249 including non-secrets cases (Swarm mkdir/chmod, migrations, registrations).

Do you have any thoughts on either or both of these approaches?

I'm happy to contribute one or more PRs in this direction if you are interested.

[kmendell]

yuo can submit a Pr with your attempt at it, secrets for docker swarm can be created in the UI now, but normal file based secrets can not.

[peitschie]

Update on the approach above — PR is now open at #2782.

Took option (2) — approval-gated lifecycle commands — but with these deliberate deviations from what I sketched:

What shipped

• Per-sync, not per-project, configured via the GitOps Sync dialog (no .arcane/lifecycle.yaml). Config lives on the sync row in DB without an Arcane-specific file in the user's repo.
• Standard compose env_file flow for secrets, no Arcane-specific secrets injection. The SOPS use case becomes "hook decrypts to .env.runtime, compose env_file: reads it" - pure compose primitives.
• Defense-in-depth sandbox: throwaway runner container with no-new-privileges, CapDrop ALL, default network=none, workspace-only mount, per-sync timeout.
• Admin kill switch (lifecycleEnabled setting, default off, env-overridable).

What I dropped from the original sketch, and why

• Hash-based approval gate - This turned out to be super hard to implement (scripts can call other scripts, inject via env variables etc.). Ultimately I decided it was security theatre. Trust is at the repo-link step, not per-hash. If the source isn't trusted, then the pre-deploy script should absolutely not be used.
• Per-environment auto-approve toggle - fell out with the approval gate.
• .arcane/lifecycle.yaml - This didn't follow any established patterns. Leaving it in the DB only seemed the right step.

What I didn't do

• Option (1) — pluggable typed secrets backends - The hook approach unblocks the SOPS use case without trying to bake in specific opinions about the secrets workflow.