fix(hedgedoc): Seeded admin account + R2 snapshot/restore persistence

[stefanko-ch]

Summary

Two coupled fixes for HedgeDoc, both required for the stack to be useful:

1. Seeded admin account — HedgeDoc shipped with email signup disabled AND anonymous editing as the in-app workflow. The auth UI surprised users with a sign-in modal that couldn't accept any credentials, and "anonymous editing behind CF Access" misses HedgeDoc's core value (note ownership, "My Notes", private notes).
2. R2 snapshot/restore persistence — HedgeDoc was NOT in s3_restore.standard_targets, so every teardown discarded ALL notes + uploads. Independently broken regardless of auth mode.

Login without persistence would be nonsense, so both fixes land together.

Closes #618

Admin authentication

Layer	Mechanism
Edge	Cloudflare Access (email OTP) — gates who reaches the HedgeDoc login page
In-app	Single seeded admin account, credentials in Infisical

• random_password.hedgedoc_admin in Tofu → outputs.tf secrets → Infisical /hedgedoc as HEDGEDOC_USERNAME (admin email) + HEDGEDOC_PASSWORD.
• service_env._render_hedgedoc extends the fail-fast guard to require all four (session secret, DB pw, admin pw, admin email).
• render_hedgedoc_hook (services.py) seeds the admin via node /hedgedoc/bin/manage_users --add EMAIL --pass PASS during services-configure. Idempotent: try --add first, fall back to --reset if user exists (mirrors the Superset hook's create→reset pattern, handles snapshot-restore + Tofu password rotation).
• Password piped via stdin to docker exec -i so the cleartext never appears in host-side ps argv (same as the Superset hook).
• Compose flips CMD_ALLOW_ANONYMOUS / ANONYMOUS_EDITS / FREEURL to false and CMD_DEFAULT_PERMISSION to private — newly-created notes are admin-only until explicitly shared via the per-note ⚙ permission selector.

Persistence

• PostgresDumpTarget(container="hedgedoc-db", database="hedgedoc", user="nexus-hedgedoc") added to standard_targets.
• hedgedoc-uploads converted from a Docker named volume to a bind-mount on /mnt/nexus-data/hedgedoc/uploads so rsync can capture it (named volumes can't be rsynced without --volumes-from gymnastics).
• New compose_runner.hedgedoc_uploads_prep flag: idempotent mkdir + owner-guarded chown to 10000:10000 (the in-container hedgedoc UID, verified via docker exec hedgedoc id). Mirrors the existing dify_storage_prep / metabase_storage_prep pattern.
• Matching RsyncTarget(name="hedgedoc-uploads", s3_subpath="hedgedoc/uploads") so the existing teardown→R2 / spin-up→R2 cycle preserves attachments.

Why this shape

• Single-admin default per user choice. Convention matches Metabase, Grafana, Portainer — Tofu generates the credential, stack ships locked-down. If multi-user is needed (workshop / pair-collaboration), flip CMD_ALLOW_EMAIL_REGISTER=true and re-deploy; CF Access at the edge still gates entry.
• Bind-mount over named volume. Named volumes need docker run --volumes-from to be rsynced; bind-mounts on /mnt/nexus-data/ align with the Dify / Metabase / Gitea pattern that s3_restore already handles.
• manage_users CLI over direct SQL. HedgeDoc bcrypt-hashes the password via Sequelize hooks; replicating that in psql would track upstream's algorithm choices. The CLI is the contract.
• --add → --reset fallback for idempotency. --add fails (exit 2 + "already exists") on second run; --reset succeeds when the user exists. Together: same logical "ensure admin exists with this password" semantics, robust against R2 snapshot restore from a stack with a different password.

Test plan

• uv run pytest tests/unit/ — 1552 passed
• All four secret-guards fire individually + together with a single error message naming all missing keys
• render_hedgedoc_hook: stdin pipe, password NOT in docker exec argv on any line (HD-CANARY check), email via -e VAR=, both --add and --reset paths rendered
• compose_runner.hedgedoc_uploads_prep: block only when flagged, owner-guarded chown structure
• s3_restore.standard_targets: pg-dump pin (container/db/user), rsync subpath pin
• pre-commit run clean (ruff format, ruff check, mypy strict, shellcheck)

Manual deploy test:

gh workflow run spin-up.yml --ref fix/hedgedoc-admin-and-persistence

Then:

1. Open https://hedgedoc.<domain> → CF Access OTP → HedgeDoc login form should appear (NO sign-up link).
2. Username = your ADMIN_EMAIL, password = infisical secrets get HEDGEDOC_PASSWORD --path=/hedgedoc --plain.
3. Create a note, upload an image.
4. teardown.yml → spin-up.yml.
5. Note + image should still be there.

Out of scope

• Gitea OAuth (alternative auth mechanism). Would be a separate enhancement if SSO across the stack is wanted.
• LDAP / SAML / external IdP integration.
• HedgeDoc Pro features.

Files

18 files modified:

• tofu/stack/main.tf, tofu/stack/outputs.tf — random_password + secret output
• src/nexus_deploy/config.py, infisical.py — schema + Infisical folder
• src/nexus_deploy/service_env.py — extended guard + new env vars
• src/nexus_deploy/services.py — render_hedgedoc_hook + registry entry
• src/nexus_deploy/compose_runner.py — hedgedoc_uploads_prep flag
• src/nexus_deploy/s3_restore.py — pg-dump + rsync targets
• stacks/hedgedoc/docker-compose.yml — auth flags, bind-mount, comment update
• docs/stacks/hedgedoc.md — auth model + persistence sections rewritten
• tests/unit/{test_config,test_compose_runner,test_s3_restore,test_service_env,test_services}.py — new tests + updated fixture
• tests/fixtures/secrets_full.json — hedgedoc_admin_password
• tests/unit/__snapshots__/{test_config,test_infisical}.ambr — regenerated

[github-actions]

Coverage report — nexus_deploy

File	Stmts	Miss	Cover	Missing
__init__.py	5	0	100%
_remote.py	15	0	100%
cli.py	4	0	100%
compose_restart.py	40	0	100%
compose_runner.py	84	0	100%
config.py	137	0	100%
firewall.py	206	0	100%
gitea.py	587	55	90%	691–692, 697, 720–721, 733–734, 770–771, 783–784, 802–803, 828–829, 851–852, 863–864, 919–920, 928–929, 934, 940–941, 965–966, 999–1000, 1003, 1034–1035, 1076–1077, 1082–1083, 1123–1124, 1155–1156, 1179–1180, 1185–1186, 1285–1286, 1291–1292, 1766, 1770, 1791, 1819–1820, 1907
hetzner_capacity.py	126	0	100%
infisical.py	203	0	100%
kestra.py	176	3	98%	223, 427, 768
orchestrator.py	620	73	88%	456, 616, 628, 798–799, 804–805, 837–839, 848, 853–855, 866, 903–904, 909–910, 930, 965–966, 971–972, 980, 1005–1006, 1014, 1036–1037, 1042–1043, 1095–1096, 1101–1102, 1335, 1338, 1408, 1414–1415, 1420–1421, 1455, 1562–1563, 1568–1569, 1618–1619, 1624–1625, 1684, 1699, 1756, 1761–1762, 1767–1768, 1775, 1781, 1948, 1955, 1967–1968, 1973–1974, 1980, 1986, 2059–2060, 2081–2082
pipeline.py	207	13	93%	165–166, 350, 388, 468, 485, 580–581, 626–627, 717–718, 765
r2_tokens.py	113	2	98%	87, 150
s3_persistence.py	199	1	99%	315
s3_restore.py	103	0	100%
secret_sync.py	99	0	100%
seeder.py	98	0	100%
service_env.py	383	33	91%	1083, 1085–1087, 1095–1096, 1424–1427, 1432–1438, 1467–1471, 1487–1491, 1513, 1515, 1537–1538, 1545, 1654
services.py	319	1	99%	2018
setup.py	165	13	92%	238, 308–311, 319, 323–328, 344
ssh.py	56	0	100%
stack_sync.py	96	0	100%
tfvars.py	44	0	100%
tofu.py	86	0	100%
workspace_coords.py	101	0	100%
TOTAL	4272	194	95%

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

This PR makes the HedgeDoc stack usable by (1) introducing a seeded in-app admin account (with self-signup + anonymous edits disabled) and (2) adding full R2 snapshot/restore coverage for HedgeDoc’s Postgres DB and uploads directory, so notes and attachments survive teardown/spin-up cycles.

Changes:

• Add a new OpenTofu-generated HedgeDoc admin password, plumb it through config/Infisical, and add a services-configure hook to idempotently create/reset the admin via manage_users.
• Add HedgeDoc to s3_restore.standard_targets (Postgres dump + uploads rsync) and switch uploads from a named volume to a /mnt/nexus-data/... bind mount with a guarded chown prep step.
• Update HedgeDoc compose + docs + unit tests/snapshots to reflect the new auth and persistence model.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tofu/stack/main.tf	Adds random_password.hedgedoc_admin for the seeded HedgeDoc admin credential.
tofu/stack/outputs.tf	Exposes hedgedoc_admin_password via the secrets output for downstream sync.
src/nexus_deploy/config.py	Extends the secrets schema to include hedgedoc_admin_password.
src/nexus_deploy/infisical.py	Pushes HedgeDoc admin username/password into the /hedgedoc Infisical folder.
src/nexus_deploy/service_env.py	Adds HedgeDoc admin email/password to rendered env and extends fail-fast guards.
src/nexus_deploy/services.py	Implements render_hedgedoc_hook and registers it in the hook registry.
src/nexus_deploy/compose_runner.py	Adds hedgedoc_uploads_prep to prep/chown the uploads bind mount directory.
src/nexus_deploy/s3_restore.py	Adds HedgeDoc Postgres dump + uploads rsync targets to standard persistence.
stacks/hedgedoc/docker-compose.yml	Disables anonymous/signup, sets private-by-default notes, converts uploads to bind mount.
docs/stacks/hedgedoc.md	Updates usage/auth/persistence docs for the seeded-admin + R2 persistence behavior.
tests/unit/test_config.py	Updates schema field-count assertion.
tests/unit/test_service_env.py	Adds coverage for new HedgeDoc admin guardrails and env rendering.
tests/unit/test_services.py	Adds coverage for the rendered HedgeDoc admin-seed hook script behavior.
tests/unit/test_compose_runner.py	Adds coverage for the HedgeDoc uploads prep block rendering/defaulting.
tests/unit/test_s3_restore.py	Adds assertions for the new HedgeDoc persistence targets.
tests/fixtures/secrets_full.json	Adds fixture value for hedgedoc_admin_password.
tests/unit/snapshots/test_config.ambr	Updates snapshot to include the new config field.
tests/unit/snapshots/test_infisical.ambr	Updates snapshot to include the new HedgeDoc Infisical secrets.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated no new comments.