Skip to content

docs: document experimental Docker CE support and known limitations #562

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
joe0BAB merged 1 commit into from
Jun 25, 2026
Merged

docs: document experimental Docker CE support and known limitations #562

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 52 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,40 @@

Secrets Engine and [docker pass](https://docs.docker.com/reference/cli/docker/pass/)
are bundled with [Docker Desktop](https://docs.docker.com/desktop/).
A standalone version can also be installed from the [releases](https://github.com/docker/secrets-engine/releases).

> [!NOTE]
> Secret injection in Docker CE is on our roadmap.
## Docker CE (experimental / early access)

Runtime secret injection is now available in Docker CE as an **experimental,
early-access** feature. It requires Docker Engine (`dockerd`) **29.2.0 or
higher**.

### Install

Download the latest packages for your Linux distribution from the
[releases](https://github.com/docker/secrets-engine/releases), then install them:
```shell
# Replace with the files you downloaded (matching your distro and arch).
sudo apt install ./DockerSecretsEngine-linux-amd64-ubuntu2404.deb \
./DockerSecretsEnginePlugins-linux-ubuntu2404.deb
systemctl --user daemon-reload
systemctl --user enable --now docker-secrets-engine.service
```

Recommended:
- `dbus` — required for the keyring backends.
- `gnome-keyring` or `kwallet` — secret storage backend.

### Uninstall

```shell
systemctl --user disable --now docker-secrets-engine.service
sudo apt remove docker-secrets-engine-plugins docker-secrets-engine

@docker-agent docker-agent Jun 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[LOW] Uninstall section omits systemctl --user daemon-reload after apt remove

The install section explicitly runs systemctl --user daemon-reload to register the new unit file with systemd. The uninstall section skips the equivalent step after package removal, which can leave stale unit metadata in systemd (e.g., the unit may still show as "loaded" in systemctl --user status docker-secrets-engine even after the package is gone).

Suggested fix: Add a daemon-reload at the end of the uninstall block:

systemctl --user disable --now docker-secrets-engine.service
sudo apt remove docker-secrets-engine-plugins docker-secrets-engine
systemctl --user daemon-reload

```

> [!WARNING]
> Docker CE support is experimental and may change between releases. Do not
> rely on it for production workloads yet. Also see
> [known limitations](#known-limitations).

@docker-agent docker-agent Jun 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] Broken anchor: #known-limitations won't scroll to the section

The WARNING callout links to #known-limitations, but GitHub generates the anchor from the actual heading ## Known limitations and issues as #known-limitations-and-issues. The link will be silently dead in the rendered README — clicking it does nothing.

Fix: Change line 42 from:

[known limitations](#known-limitations)

to:

[known limitations](#known-limitations-and-issues)


## Runtime secret injection (no plaintext in your CLI or Compose)

Expand Down Expand Up @@ -257,6 +287,25 @@ echo "<base64 string>" | base64 --decode
echo "<base64 string>" | base64 -d
```

## Known limitations and issues

These apply to the experimental Docker CE integration described above. We are
actively working to address them.

- **No multi-user support.** A single Docker Engine is shared by every user on
the host, but Secrets Engine runs as a per-user daemon. When multiple users
are logged in and using the same engine in parallel, the engine cannot
reliably route a resolution request to the right user's daemon.
- **Requires a keyring backend.** The daemon depends on D-Bus together with a
Secret Service provider (GNOME Keyring or KWallet). On hosts where these are
missing — typically headless or server installs — the daemon currently crashes
instead of degrading gracefully. We are working on a fix; in the meantime, the
workaround is to install and set up D-Bus and either GNOME Keyring or KWallet.
- **No automatic restart after a `dockerd` restart.** When the Docker Engine is
restarted, the Secrets Engine daemon must be restarted manually
(`systemctl --user restart docker-secrets-engine`) for injection to keep
working.

## Legal

_Brought to you courtesy of our legal counsel. For more context,
Expand Down
Loading