Ignore deploy/certs and document direct-mode certificate handling #19

Merged

hannah-vernon merged 1 commit from fix/certs-gitignore into dev

2026-08-25 22:58:32 -05:00

hannah-vernon commented

2026-08-25 22:09:48 -05:00

Owner

What does this PR do?

Two fixes from tonight''s live certificate setup on the deployment VM:

.gitignore gains deploy/certs/. The directory holds the TLS private key copied from Let''s Encrypt for the admin container''s direct mode; it appeared as untracked in git status on the VM, meaning one careless git add -A away from committing key material to a public repo. Now ignored alongside secrets/data/backups.
docs/deployment.md documents direct-mode certificate handling as learned live: directory must be 755 with files 400 owned by UID 1654 (a umask 077 shell creates 700 directories whose contents are invisible to the container - the "requires readable ... PEM files" startup error is the symptom); the certbot deploy hook that refreshes the copies and restarts the admin service on renewal; --http-01-address/--http-01-port for NAT-translated challenge ports; and the compose recreate-vs-restart gotcha when adding the volume to an existing deployment.

How was this tested?

dotnet build - not applicable (no code changes); documentation and ignore rules only
dotnet test - not applicable
Manually verified on the deployment VM: the documented fixes are exactly what brought viegard-admin up in direct TLS mode tonight

Checklist

I have read the Contributing Guide
Changes are focused - one logical change per PR
Documentation updated (README.md / DECISIONS.md / TODO.md / AGENT-README.md, if applicable)
New dependencies are MIT/Apache-2.0/BSD, security-vetted, and recorded in THIRD-PARTY-NOTICES.md (none added)
No secrets, credentials, or real infrastructure identifiers in the diff
No commented-out code or debug leftovers

## What does this PR do? Two fixes from tonight''s live certificate setup on the deployment VM: 1. **`.gitignore` gains `deploy/certs/`.** The directory holds the TLS private key copied from Let''s Encrypt for the admin container''s direct mode; it appeared as untracked in `git status` on the VM, meaning one careless `git add -A` away from committing key material to a public repo. Now ignored alongside secrets/data/backups. 2. **`docs/deployment.md` documents direct-mode certificate handling** as learned live: directory must be `755` with files `400` owned by UID 1654 (a `umask 077` shell creates `700` directories whose contents are invisible to the container - the "requires readable ... PEM files" startup error is the symptom); the certbot deploy hook that refreshes the copies and restarts the admin service on renewal; `--http-01-address`/`--http-01-port` for NAT-translated challenge ports; and the compose recreate-vs-restart gotcha when adding the volume to an existing deployment. ## How was this tested? - [x] `dotnet build` - not applicable (no code changes); documentation and ignore rules only - [x] `dotnet test` - not applicable - [x] Manually verified on the deployment VM: the documented fixes are exactly what brought viegard-admin up in direct TLS mode tonight ## Checklist - [x] I have read the [Contributing Guide](../CONTRIBUTING.md) - [x] Changes are focused - one logical change per PR - [x] Documentation updated (README.md / DECISIONS.md / TODO.md / AGENT-README.md, if applicable) - [x] New dependencies are MIT/Apache-2.0/BSD, security-vetted, and recorded in THIRD-PARTY-NOTICES.md (none added) - [x] No secrets, credentials, or real infrastructure identifiers in the diff - [x] No commented-out code or debug leftovers

hannah-vernon added 1 commit

2026-08-25 22:09:48 -05:00

Ignore deploy/certs and document direct-mode certificate handling 5618dc7489

deploy/certs/ holds TLS private key material copied from Let's Encrypt
for the admin container; it must never be committable.  Found live when
the directory appeared untracked in git status on the deployment VM.

deployment.md gains the direct-mode certificate section learned from
the first live setup: 755 directory / 400 files owned by UID 1654 (a
umask 077 shell creates 700 directories that hide the files from the
container), the certbot deploy hook that refreshes copies and restarts
the admin service, --http-01-address/--http-01-port for NAT-translated
challenge ports, and the compose recreate-vs-restart gotcha.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>