LCORE-973: config documentation, 1st version

[tisnik]

Description

LCORE-973: config documentation, 1st version

Type of change

• Refactor
• New feature
• Bug fix
• CVE fix
• Optimization
• Documentation Update
• Configuration Update
• Bump-up service version
• Bump-up dependent library
• Bump-up library or tool used for development (does not change the final image)
• CI configuration change
• Konflux configuration change
• Unit tests improvement
• Integration tests improvement
• End to end tests improvement

Related Tickets & Documents

• Related Issue #LCORE-973

Summary by CodeRabbit

• Documentation
  • Introduced comprehensive configuration reference documentation for Lightspeed Core Stack, including detailed specifications for authentication, authorization, database, caching, inference, and deployment options in Markdown, JSON Schema, and HTML formats for reference and validation.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Three new documentation files introduce the Lightspeed Core Stack configuration schema across formats: a static HTML page, an OpenAPI v3.0 schema definition, and Markdown documentation. All three cover identical configuration sections (AccessRule, Authentication, Authorization, Database, JWT, CORS, and others) with field definitions, types, and descriptions.

Changes

Cohort / File(s)	Change Summary
Configuration Schema Documentation docs/config.html, docs/config.json, docs/config.md	Introduces comprehensive configuration schema documentation in three formats: static HTML page with styled layout and tables, OpenAPI v3.0 schema with nested component definitions, and Markdown documentation with tabular field descriptions. Covers 30+ configuration sections including authentication, authorization, database, JWT, CORS, quota, and service settings.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20–30 minutes

• Schema Completeness: Verify all configuration sections are present and accurately documented across HTML, JSON, and Markdown formats.
• Consistency: Ensure field definitions, types, and descriptions align consistently across the three files.
• JSON Schema Correctness: Validate OpenAPI v3.0 schema format, nested definitions, type constraints, required fields, and default values.
• Documentation Accuracy: Cross-reference configuration descriptions with actual implementation to catch omissions or inconsistencies.

Possibly related PRs

• LCORE-535: Regenerated OpenAPI schema #428: Extends OpenAPI/documentation schemas with CORSConfiguration and ServiceConfiguration.cors definitions.
• Regenerated OpenAPI spec + doc #451: Adds/modifies the same OpenAPI schemas (AccessRule, Action, JsonPathOperator, JwtRoleRule, role\_rules, authorization).
• LCORE-390: description for SQL storage config #378: Modifies documentation schemas to add DatabaseConfiguration and SQLite/PostgreSQL variant definitions.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding configuration documentation for the Lightspeed Core Stack, specifically for issue LCORE-973.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (4)

docs/config.json (2)

1-1054: Add maxItems constraints to array fields for schema completeness.

Several array fields lack maxItems constraints, which can lead to unbounded configurations. This is flagged by Checkov (CKV_OPENAPI_21). While this is a "1st version" (as noted in the PR title), adding reasonable bounds to arrays like actions, access_rules, mcp_servers, limiters, and role_rules would improve schema robustness.

Consider adding maxItems to array definitions. For example:

       "actions": {
         "items": {
           "$ref": "#/components/schemas/Action"
         },
         "title": "Actions",
+        "maxItems": 100,
         "type": "array"
       }

---

683-683: Minor: Fix description capitalization.

The description "model context protocol server configuration" should be capitalized to match other descriptions in the schema.

-        "description": "model context protocol server configuration.",
+        "description": "Model context protocol server configuration.",

docs/config.md (1)

1-384: Populate field descriptions and complete type information.

The Markdown documentation has well-structured tables but the "Description" column is uniformly empty across all sections, and type information is incomplete for complex types (showing blank instead of references or type names). For example:

• Line 39-42: Type columns show blank for k8s_cluster_api, k8s_ca_cert_path, jwk_config, and rh_identity_config
• Lines 21-27: Action section lists an enum but provides no table of available values
• Lines 185-192: JsonPathOperator similarly lacks enum values

This is acceptable for a "1st version" (as noted in the PR title), but consider enhancing descriptions with usage guidance and completing type references in future iterations.

docs/config.html (1)

7-7: Add meaningful page title and complete table content.

Line 7 has an empty <title> tag. Consider adding a descriptive title like "Lightspeed Core Stack Configuration Schema Documentation".

Additionally, like the Markdown file, the HTML tables have empty "Description" columns and incomplete type information for complex fields. This mirrors the Markdown documentation gaps and should be addressed alongside Markdown improvements.

-  <title> </title>
+  <title>Lightspeed Core Stack Configuration Schema Documentation</title>

Also applies to: 174-1031

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d8e504b and 6a23f62.

📒 Files selected for processing (3)

• docs/config.html (1 hunks)
• docs/config.json (1 hunks)
• docs/config.md (1 hunks)

🧰 Additional context used

🧠 Learnings (1)

📓 Common learnings

Learnt from: onmete
Repo: lightspeed-core/lightspeed-stack PR: 417
File: src/lightspeed_stack.py:60-63
Timestamp: 2025-08-19T08:57:27.714Z
Learning: In the lightspeed-stack project, file permission hardening (chmod 0o600) for stored configuration JSON files is not required as it's not considered a security concern in their deployment environment.

🪛 Checkov (3.2.334)

docs/config.json

[high] 1-1054: Ensure that the global security field has rules defined

(CKV_OPENAPI_4)

---

[medium] 17-23: Ensure that arrays have a maximum number of items

(CKV_OPENAPI_21)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: build-pr
• GitHub Check: Konflux kflux-prd-rh02 / lightspeed-stack-on-pull-request
• GitHub Check: e2e_tests (ci)
• GitHub Check: e2e_tests (azure)

🔇 Additional comments (1)

docs/config.html (1)

5-5: Clarify whether HTML is auto-generated or manually maintained.

The meta generator tag at Line 5 indicates this is "pandoc"-generated. If the HTML is auto-generated from the Markdown source (docs/config.md), maintainers should focus updates on the Markdown file and regenerate HTML. If manually maintained, ensure it stays synchronized with the Markdown and JSON schema versions.