docs: add a configuration operations guide - #25
Merged
Merged
Conversation
Cover mounting, validating a candidate, reloading, rollback, troubleshooting, and secret redaction, with every procedure exercised against the built image before being written down. The finding worth the guide on its own: a bind mount of a single configuration file resolves to that file's inode, so replacing the file by rename leaves the container on the previous inode. That is what `sed -i`, most editors, and every write-then-move deployment does. The subsequent reload then reports success while the old configuration stays live, which is the worst shape a failure can take. Verified both directions: an in-place rewrite preserving the inode is picked up, a rename is not, and mounting the containing directory instead makes an atomic rename work normally. Also records that `nginx -t` exits 1 on an invalid configuration so it can gate a deployment, that validation should carry the same restrictions the deployment uses because a configuration can pass without them and still fail to start under a read-only root or an arbitrary UID, and the permission failures that present as configuration bugs: a 0700 directory answering 403, and the Podman and Docker difference in how mounted file ownership reaches the runtime identity.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes the Package 3 item for documenting configuration mounting, validation,
reload, rollback, logging, troubleshooting, and secret redaction.
Every procedure was run against the built image before being written down.
The finding that justifies the guide
A bind mount of a single configuration file resolves to that file's inode.
Replacing the file by rename — what
sed -i, most editors, and everywrite-then-
mvdeployment does — creates a new inode. The mount still points atthe old one.
The reload then reports success while the previous configuration stays
live. Nothing errors. Nothing warns.
Verified in all three directions:
cat >)sed -i,mv)So the guide's rule is: mount the directory, point NGINX at a file inside it.
I found this because my first attempt to test reload used
sed -iand nothingchanged — which looked like a reload bug and was not.
Other verified content
nginx -texits1on an invalid configuration and0on a valid one, soit can gate a deployment. Confirmed properly — my first measurement read the
exit code of a pipeline rather than podman's.
pass without them and still fail under a read-only root or arbitrary UID.
0700directory answering
403on every request, and the Podman/Docker differencein how mounted file ownership reaches the runtime identity — both hit during
this work, in feat: add a qualified preview request-limiting profile #18 and feat: add qualified preview HTTP and TLS profiles #15 respectively.
Redaction
Restates the two rules that matter when editing configuration: log the path and
never the request line, and check what sits downstream, because a collector or
front proxy recording full request lines reintroduces exactly what the profiles
exclude.
Roadmap
Package 3 drops to three open items: DNS and upstream-verification defaults,
and the two blocked on a chosen logging platform and an exact supported host.
🤖 Generated with Claude Code