Mount-Zeile und Token-Variante explizit dokumentieren #4

Merged

nexus merged 2 commits from docs/secret-file-mount into main 2026-08-04 20:01:10 +02:00

Conversation 0 Commits 2 Files changed 5 +182 -25

nexus commented 2026-08-04 19:40:30 +02:00

Owner

Copy link

Aus dem Praxistest: Der Mount war korrekt, aber HETZNER_API_TOKEN_FILE zeigte auf den Host-Pfad statt auf den Container-Pfad. Die Datei lag auf dem Host sichtbar da, der Container meldete sie als fehlend.

Der alte Kommentar in der Compose-Datei war daran beteiligt: "Point HETZNER_API_TOKEN_FILE in .env at this path" — "this path" liest sich als der Host-Pfad, den man gerade eingetragen hat.

Fehlermeldung nennt jetzt den richtigen Wert

Ist der Mount schon korrekt, liegt die Datei unter /run/secrets/ unter demselben Namen. Das Programm schaut dort nach und gibt die fertige Einstellung aus:

HETZNER_API_TOKEN_FILE: /srv/.../hetzner_api_token does not exist — in a
container this has to be the path INSIDE the container, which is the right hand
side of the volume mount, not the path on the host. A file of that name is
mounted at /run/secrets/hetzner_api_token, so set
HETZNER_API_TOKEN_FILE=/run/secrets/hetzner_api_token

Gesucht wird in /run/secrets, /var/run/secrets und /secrets. Findet sich nichts, bleibt der Hinweis weg — ein erfundener Pfad waere schlimmer als keiner.

Quick Start: die beiden Varianten gegenuebergestellt

Bisher zeigte der Quick Start nur HETZNER_API_TOKEN und erwaehnte die Datei-Variante gar nicht. Jetzt steht dort, dass es genau eine von beiden sein muss, dass die Datei-Variante zwei zusaetzliche Schritte kostet, und ein Link auf den ausfuehrlichen Abschnitt.

Mount-Zeile aufgeschluesselt

Die README sagt jetzt ausdruecklich, dass die Zeile in docker-compose.yml einzukommentieren ist, und schluesselt beide Seiten auf:

  ./hetzner_api_token  :  /run/secrets/hetzner_api_token  :ro
  └── wo die Datei        └── wo sie im Container            └── nur lesbar
      auf dem Host liegt      erscheint

Dazu eine Tabelle, wie die linke Seite je nach Ablageort aussieht — daneben, im Unterverzeichnis, oder als absoluter Pfad irgendwo auf dem Host.

Getestet

• Zwei neue Testfaelle: Vorschlag wird ausgegeben, wenn die Datei gemountet ist; kein Vorschlag, wenn nicht
• Fehlermeldung gegen das gebaute Binary geprueft
• make lint test-race gruen, 0 Lint-Issues, Domain-Schranke gruen, keine toten Anker

Aus dem Praxistest: Der Mount war korrekt, aber `HETZNER_API_TOKEN_FILE` zeigte auf den **Host**-Pfad statt auf den Container-Pfad. Die Datei lag auf dem Host sichtbar da, der Container meldete sie als fehlend. Der alte Kommentar in der Compose-Datei war daran beteiligt: *"Point HETZNER_API_TOKEN_FILE in .env at this path"* — "this path" liest sich als der Host-Pfad, den man gerade eingetragen hat. ## Fehlermeldung nennt jetzt den richtigen Wert Ist der Mount schon korrekt, liegt die Datei unter `/run/secrets/` unter demselben Namen. Das Programm schaut dort nach und gibt die fertige Einstellung aus: ``` HETZNER_API_TOKEN_FILE: /srv/.../hetzner_api_token does not exist — in a container this has to be the path INSIDE the container, which is the right hand side of the volume mount, not the path on the host. A file of that name is mounted at /run/secrets/hetzner_api_token, so set HETZNER_API_TOKEN_FILE=/run/secrets/hetzner_api_token ``` Gesucht wird in `/run/secrets`, `/var/run/secrets` und `/secrets`. Findet sich nichts, bleibt der Hinweis weg — ein erfundener Pfad waere schlimmer als keiner. ## Quick Start: die beiden Varianten gegenuebergestellt Bisher zeigte der Quick Start nur `HETZNER_API_TOKEN` und erwaehnte die Datei-Variante gar nicht. Jetzt steht dort, dass es genau eine von beiden sein muss, dass die Datei-Variante **zwei zusaetzliche Schritte** kostet, und ein Link auf den ausfuehrlichen Abschnitt. ## Mount-Zeile aufgeschluesselt Die README sagt jetzt ausdruecklich, dass die Zeile in `docker-compose.yml` **einzukommentieren** ist, und schluesselt beide Seiten auf: ``` ./hetzner_api_token : /run/secrets/hetzner_api_token :ro └── wo die Datei └── wo sie im Container └── nur lesbar auf dem Host liegt erscheint ``` Dazu eine Tabelle, wie die linke Seite je nach Ablageort aussieht — daneben, im Unterverzeichnis, oder als absoluter Pfad irgendwo auf dem Host. ## Getestet - Zwei neue Testfaelle: Vorschlag wird ausgegeben, wenn die Datei gemountet ist; kein Vorschlag, wenn nicht - Fehlermeldung gegen das gebaute Binary geprueft - `make lint test-race` gruen, 0 Lint-Issues, Domain-Schranke gruen, keine toten Anker

nexus added 1 commit 2026-08-04 19:40:30 +02:00

Name the mounted file in the missing-secret error ... bd8d9af190

The variable takes the container side of the mount, and typing the host side
into it is the natural mistake — that is the path one has just written into
the volume line. The error described the distinction but left the reader to
work out the value.

When the mount is already correct the file is sitting in /run/secrets under
the same name, so the error now looks there and prints the setting outright.

The docs stop assuming the difference is obvious. The quick start contrasts
the two variables and says that the file route costs two extra steps; the
mount section spells out which side is which and how the left side changes
with where the file lives.

nexus added 1 commit 2026-08-04 19:48:21 +02:00

Run the container as the file's owner instead of the other way round ... cacdc67da2

Handing the secret file to UID 65532 leaves it owned by a user that does not
exist on the host, so every later edit needs sudo or podman unshare. Setting
 to the uid that already owns the file inverts that: the file stays
yours at 0600, the container reads it, and no chown is involved on any engine.

The 0400 that went with the old advice is dropped as well. It costs the owner
write access and buys nothing — 0600 already keeps other users of the host
out, and the file is only ever as protected as the directory holding it.

The 65532 variants stay for anyone whose policy demands a fixed non-human uid,
now with a note on how to keep the file editable there too.

nexus force-pushed docs/secret-file-mount from cacdc67da2 to d1034661bc 2026-08-04 19:48:38 +02:00 Compare

nexus merged commit db79abbc53 into main 2026-08-04 20:01:10 +02:00

nexus deleted branch docs/secret-file-mount 2026-08-04 20:01:10 +02:00

nexus referenced this pull request from a commit 2026-08-04 20:01:12 +02:00

Merge pull request 'Mount-Zeile und Token-Variante explizit dokumentieren' (#4) from docs/secret-file-mount into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

nexus/hetzner-ddns!4

No description provided.