Skip to content

docs update user-facing documentation#5

Merged
kjdev merged 1 commit intomainfrom
docs/update-user-document
Mar 2, 2026
Merged

docs update user-facing documentation#5
kjdev merged 1 commit intomainfrom
docs/update-user-document

Conversation

@kjdev
Copy link
Copy Markdown
Owner

@kjdev kjdev commented Mar 2, 2026

Summary by CodeRabbit

  • Documentation
    • Restructured README with a concise overview and task-oriented layout
    • Added Installation, Directives reference, Examples, Security, Troubleshooting, and JWT-supported-algorithms guides
    • Added Commercial Compatibility document
    • Simplified configuration examples and clarified required vs. recommended settings (including session/TTL guidance and logout message)
    • Improved cross-references to related docs for easier navigation

@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Mar 2, 2026

Warning

Rate limit exceeded

@kjdev has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 4 minutes and 55 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 2941cc0 and 09eba0a.

⛔ Files ignored due to path filters (2)
  • docs/images/examples-auth-flow.png is excluded by !**/*.png
  • docs/images/oidc-auth-flow.png is excluded by !**/*.png
📒 Files selected for processing (8)
  • README.md
  • docs/COMMERCIAL_COMPATIBILITY.md
  • docs/DIRECTIVES.md
  • docs/EXAMPLES.md
  • docs/INSTALL.md
  • docs/JWT_SUPPORTED_ALGORITHMS.md
  • docs/SECURITY.md
  • docs/TROUBLESHOOTING.md
📝 Walkthrough

Walkthrough

This pull request restructures and expands the nginx OIDC module documentation: README condensed and modularized; six new docs added (DIRECTIVES, INSTALL, SECURITY, TROUBLESHOOTING, JWT_SUPPORTED_ALGORITHMS, COMMERCIAL_COMPATIBILITY); EXAMPLES revised. No runtime code changes.

Changes

Cohort / File(s) Summary
Top-level README & Examples
README.md, docs/EXAMPLES.md
README rewritten and shortened (−1458 lines overall); README now points to modular docs. EXAMPLES reorganized with streamlined quick-starts, clarified defaults, multi-provider notes, and updated example blocks.
Directive Reference
docs/DIRECTIVES.md
New comprehensive directive reference documenting syntax, defaults, embedded variables, internal fetch mechanics, validation rules, and usage examples (+1121 lines). Review for accuracy of directive semantics and internal endpoint notes.
Installation & Build
docs/INSTALL.md
New installation guide with prerequisites, distro package examples, build-from-source steps, Docker build/start instructions, and verification steps (+145 lines).
Security Guidance
docs/SECURITY.md
New security considerations covering PKCE, TLS guidance, cookie settings, session/ttl interplay, client-secret handling, and automatic protections (+203 lines). Verify recommendations align with implementation behavior.
Troubleshooting & Diagnostics
docs/TROUBLESHOOTING.md
New troubleshooting guide covering redirect loops, SSL/DNS/timeouts, session persistence, debug log parsing, and remediation steps (+276 lines).
JWT Algorithms & Compatibility
docs/JWT_SUPPORTED_ALGORITHMS.md, docs/COMMERCIAL_COMPATIBILITY.md
Two new reference files: JWT algorithm support matrix and rationale (+60 lines), and commercial compatibility table enumerating OSS vs commercial directive/variable availability (+58 lines). Review algorithm recommendations and compatibility markings.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 I hopped through lines and trimmed the green,

New guides now nest where noise had been.
Directives spelled, installs in view,
Secure and tidy — hoppity-doo! 🥕

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The PR title 'docs update user-facing documentation' directly summarizes the main change—comprehensive updates to user-facing documentation across multiple files (README, DIRECTIVES, EXAMPLES, INSTALL, SECURITY, TROUBLESHOOTING, JWT_SUPPORTED_ALGORITHMS, COMMERCIAL_COMPATIBILITY).
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch docs/update-user-document

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/DIRECTIVES.md`:
- Around line 1118-1121: Update the four external nginx documentation URLs to
use HTTPS instead of HTTP: change the links for "nginx proxy_pass directive",
"nginx resolver directive", "nginx SSL proxy settings", and "nginx
subrequest_output_buffer_size directive" so their targets start with https://
(keeping the rest of each URL unchanged) in the docs/DIRECTIVES.md content;
ensure there are no other http:// nginx links left in the same section to
maintain consistency.
- Around line 25-516: Many fenced code blocks (e.g., the directive syntax blocks
for auth_oidc, auth_oidc_mode, oidc_provider and examples like the oidc_provider
full configuration, oidc_session_store examples, and usage snippets) lack
language identifiers; update each triple-backtick block to include an
appropriate language label (use "nginx" for nginx/conf examples, "text" for
plain syntax blocks, or "json"/"yaml" if applicable) so markdownlint MD040 is
satisfied and syntax highlighting works consistently across blocks.

In `@docs/INSTALL.md`:
- Line 57: The example download command in INSTALL.md uses an insecure HTTP URL;
update the wget example (the line containing "wget
http://nginx.org/download/nginx-x.y.z.tar.gz") to use HTTPS instead (i.e.,
change the URL scheme to https://nginx.org/download/nginx-x.y.z.tar.gz) so the
source tarball is fetched over TLS.

In `@docs/TROUBLESHOOTING.md`:
- Around line 125-129: The docs currently show embedding secrets with redis-cli
using the -a option and REDISCLI_AUTH which encourages plaintext secrets; update
the examples to avoid inline secrets by using redis-cli's interactive prompt or
secret-file patterns instead (e.g., replace references to "-a" and
"REDISCLI_AUTH=password" with an example using redis-cli --askpass to prompt for
the password or instructions to read the password from a protected file and
supply it securely), and update the text around the examples to explicitly
instruct readers not to place passwords on the command line or in shell history.

ℹ️ Review info

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2df0445 and 9db5a21.

📒 Files selected for processing (8)
  • README.md
  • docs/COMMERCIAL_COMPATIBILITY.md
  • docs/DIRECTIVES.md
  • docs/EXAMPLES.md
  • docs/INSTALL.md
  • docs/JWT_SUPPORTED_ALGORITHMS.md
  • docs/SECURITY.md
  • docs/TROUBLESHOOTING.md

Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

♻️ Duplicate comments (1)
docs/DIRECTIVES.md (1)

25-516: ⚠️ Potential issue | 🟡 Minor

Add language identifiers to directive syntax code fences.

Multiple fenced blocks still omit language labels, so markdownlint MD040 will continue to fail. Please label these blocks (e.g., text for syntax/default/context blocks, nginx for config snippets).

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/DIRECTIVES.md` around lines 25 - 516, The markdown fenced code blocks in
this doc (e.g., the "Syntax:  auth_oidc <provider_name> | off;" block, the
various "Syntax/Default/Context" blocks, and the configuration examples such as
the nginx provider/session_store examples) lack language identifiers and trigger
markdownlint MD040; update each fenced block to include an appropriate language
label (use "text" for the Syntax/Default/Context blocks and "nginx" for
Nginx/config examples like the auth_oidc usage and
oidc_provider/oidc_session_store examples) so every triple-backtick block has a
language tag.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/INSTALL.md`:
- Around line 47-53: The fenced directory-tree block is unlabeled (triggers
MD040); update the code fence that contains the nginx-oidc tree so the opening
triple backticks include the language label "text" (i.e., change ``` to ```text)
so the snippet is treated as plain text; refer to the directory tree block
containing "nginx-oidc/          # OIDC module repository root" when making the
edit.

In `@README.md`:
- Line 195: The README note references `opt userinfo on` which is likely a typo;
update the sentence to use the correct label `userinfo on` (or explicitly match
the diagram's intended label) so it reads something like "To enable UserInfo
retrieval (the `userinfo on` section), set `userinfo on;` within
`oidc_provider`"—locate the existing note that mentions `opt userinfo on` and
replace it accordingly, keeping the link to DIRECTIVES.md intact.

---

Duplicate comments:
In `@docs/DIRECTIVES.md`:
- Around line 25-516: The markdown fenced code blocks in this doc (e.g., the
"Syntax:  auth_oidc <provider_name> | off;" block, the various
"Syntax/Default/Context" blocks, and the configuration examples such as the
nginx provider/session_store examples) lack language identifiers and trigger
markdownlint MD040; update each fenced block to include an appropriate language
label (use "text" for the Syntax/Default/Context blocks and "nginx" for
Nginx/config examples like the auth_oidc usage and
oidc_provider/oidc_session_store examples) so every triple-backtick block has a
language tag.

ℹ️ Review info

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9db5a21 and 2941cc0.

⛔ Files ignored due to path filters (2)
  • docs/images/examples-auth-flow.png is excluded by !**/*.png
  • docs/images/oidc-auth-flow.png is excluded by !**/*.png
📒 Files selected for processing (4)
  • README.md
  • docs/DIRECTIVES.md
  • docs/EXAMPLES.md
  • docs/INSTALL.md

@kjdev kjdev force-pushed the docs/update-user-document branch from b690b43 to 09eba0a Compare March 2, 2026 04:03
@kjdev kjdev merged commit 09eba0a into main Mar 2, 2026
4 checks passed
@kjdev kjdev deleted the docs/update-user-document branch March 2, 2026 04:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant