OpenBao -> one-shot host Agent -> Docker Compose file secret
==========================================================

Full guide: ../../docker.md in this documentation source tree, or the
"Docker secrets and example project" page in the published OpenBao series.

For individual web downloads, save gitignore.txt as .gitignore and
app/dockerignore.txt as app/.dockerignore. These non-hidden download copies
avoid site-builder exclusions; the source project already has the dotfiles.

Copy this entire directory into a private, writable working directory OUTSIDE
the documentation source tree before using it. Do not place live credentials
under the site's docs directory: a documentation build can publish them.

Requirements: a sudo-capable non-root user, native local Linux Docker Engine
and Compose plugin access, bao (OpenBao 2.7.x), GNU timeout, Python 3, OpenSSL,
and an initialized/unsealed OpenBao server with the existing secret/ KV v2
mount. Docker access is root-equivalent. Rootless Engine, user namespaces,
Docker Desktop and remote daemons need a different ownership/path setup.

1. Change agent.hcl's address to your real verified HTTPS OpenBao address.
2. Create tls/ and install your trusted PUBLIC CA certificate as tls/ca.pem.
   No CA private key or server private key belongs in this project.
3. Follow the main guide to write secret/apps/docker-demo (api_token), upload
   policies/docker-demo-read.hcl and create the docker-demo AppRole.
4. As an authorized operator, under umask 077, create .runtime/ (mode 700),
   then redirect RoleID and a fresh single-use SecretID to .runtime/role-id
   and .runtime/secret-id. Never print them or pass their values in argv.
5. Review the files, then run: sh ./run.sh
6. Once the app is healthy, run: python3 -B ./verify.py

run.sh does not source .env. It exports only the non-secret numeric APP_UID
and APP_GID. Its timeout/failure gate prevents a failed Agent run from starting
or replacing the app, but does not stop an already running old container.
BAO_ADDR and BAO_CACERT, if exported, override the corresponding Agent config
settings; keep them consistent. TLS verification is never disabled.

The Agent deletes its SecretID input after reading. Issue a new SecretID for
EVERY run. There is no token sink and no AppRole credential in the container.
The rendered file has mode 600; the container uses the same numeric host UID.
The app reads its token once and only returns fixed text. verify.py handles
bearer credentials in memory and prints test outcomes, never the token.

This is an illustrative loopback HTTP app, NOT a production HTTP server or
public TLS/authentication gateway. OpenBao communication uses verified TLS.
Image tags are mutable; choose reviewed image digests for production.

Rotation: update KV without placing the value in argv, issue a fresh SecretID,
then rerun sh ./run.sh and python3 -B ./verify.py. Containers are force-recreated
because Agent uses atomic file replacement and single-file mounts can retain
the old inode. There is NO continuous renewal or automatic secret reload.

Cleanup (from this directory, same non-root user):
  export APP_UID="$(id -u)" APP_GID="$(id -g)"
  docker compose down
  rm -f .runtime/app.json .runtime/role-id .runtime/secret-id
  rmdir .runtime

Deleting files is not credential revocation or guaranteed secure erasure.
Follow the main guide for OpenBao role/policy/KV teardown and Swarm lifecycle.
Git ignores and the app-only Docker build context are defense in depth, not
protection from host root, Docker administrators, backups or site publishing.
