Dockhand v1.0.45 adds KeePassXC to Compose deploymentsDockhand v1.0.45 adds KeePassXC to Compose deployments

The issue is not environment variables, but where the password ends up

In many homelabs, the compose.yaml file lives in Git while sensitive values are placed in a separate .env file. That is better than hard-coding credentials in Compose, but it still creates another file that must be protected, copied, and kept in sync across machines. It can also end up in backups, shared directories, or the repository by mistake.

Dockhand v1.0.45 adds KeePassXC as a secrets provider for this workflow. Credentials can remain in a local .kdbx database and be fetched only when a stack is deployed. Dockhand passes the resolved value to Docker Compose for that operation, without writing the secret back to the persistent .env file or the Compose file.

Using keepass:// references in a stack

The provider relies on keepassxc-cli, which must be installed or supplied by the operator. Dockhand does not bundle or download the KeePassXC client, so the database and, where necessary, the CLI need to be available inside the container. It looks for the executable at /usr/bin/keepassxc-cli by default, but an alternative absolute path can be set with DOCKHAND_KEEPASSXC_CLI_PATH.

An individual reference uses the keepass://GROUP/ENTRY/FIELD format. Groups may be nested, with the last segment selecting the attribute and the previous segments defining the entry path. Alongside Password, Dockhand can read UserName, URL, and custom attributes stored in the KeePassXC entry.

services:
  dockhand:
    image: fnsys/dockhand
    volumes:
      - dockhand_data:/app/data
      - /host/secrets/passwords.kdbx:/secrets/passwords.kdbx:ro
      - /host/secrets/db.keyx:/secrets/db.keyx:ro
      - /opt/dockhand-tools/keepassxc-cli:/usr/bin/keepassxc-cli:ro
 
volumes:
  dockhand_data:

After configuring the provider under Settings → Secrets, the database path must be set as seen from inside the container, together with a master password, a key file, or both. Dockhand sends the master password to keepassxc-cli through standard input rather than as a command-line argument. Stack variables can then use values such as DB_PASSWORD=keepass://Web/Postgres/Password, with Compose consuming them through ${DB_PASSWORD}.

It can also pull an entire group

Secrets do not have to be resolved one by one. Dockhand can use a KeePassXC group as a selector through DOCKHAND_SECRET_SELECTOR. Every entry in that group becomes an environment variable, using the entry title as its key and the entry’s Password field as its value.

That makes naming important. Titles containing spaces or dashes are not valid environment-variable names, so Dockhand skips them and emits a warning. If the same title appears in multiple subgroups, the first match wins, so duplicate names are worth avoiding.

Validate before deploying

The other practical addition is Compose validate. Dockhand combines docker compose config with its own rules, allowing it to catch both syntax or schema failures and valid-but-risky configuration choices. Validation runs before deployment and reports findings in the editor as well as in a dedicated results panel.

Its suggestions include services that do not define a healthcheck and named volumes declared at the top level that are not mounted by any service. Neither issue prevents Compose from running, and neither should automatically be treated as an error. They are still useful prompts when reviewing a stack before adding it to a homelab or automating its updates.

A warning is not a technical decision

An empty, slow, or irrelevant healthcheck does not improve availability simply because it exists. Some services do not need one, while others already provide an appropriate check through their image. The warning is valuable because it forces the right question: what must be true before this container is actually ready?

The same applies to unused volumes. They may be leftovers from an earlier configuration and safe to remove, or they may be reserved for a profile, override file, or planned change. Before deleting them, I would inspect the effective Compose configuration, any additional files, and the profiles used by the deployment.

KeePassXC has limits here

This does not turn KeePassXC into a centralized secrets service or remove the need to secure the host. Dockhand needs read access to the .kdbx database and, depending on the setup, the key file as well; anyone controlling the server and provider configuration occupies a sensitive position. There is no network service involved in this integration: it works locally through the database and keepassxc-cli.

There is also a deployment detail worth remembering. The official Dockhand image is minimal and does not ship with a package manager or KeePassXC. Mounting the executable alone may not work because the CLI depends on shared libraries. On SELinux hosts, mounts also need appropriate labels such as :z or :Z so the process can access the required files.

For a homelab already using KeePassXC as its source of truth, this integration removes the need to duplicate passwords in deployment files. Compose validation complements that change by surfacing oversights that often appear only after deployment. Neither feature replaces a proper stack review, but both reduce manual work and unnecessary exposure.

Release source · Official documentation