Repository navigation
Maintainer Alignment: Documentation preferences and open questions #14
Description
Context
We've completed a comprehensive analysis of both documentation sites and are ready to contribute. Before starting, we need alignment on a few key areas to make sure our work matches your vision.
What we've done so far:
- Full gap analysis of both projects (code vs. docs comparison)
- Staging environments running at docs-crowdsec.strausmann.cloud and docs-middleware.strausmann.cloud
- CI/CD pipeline with GitHub Actions → GHCR → Docker staging
- 23 prioritized issues covering all identified gaps ([crowdsec-manager] Fix incorrect API docs and outdated architecture information #1–[crowdsec-manager] Document remaining system API endpoints: Cron, Profiles, Events, Terminal, Hosts #13, [middleware-manager] Complete API reference: Security endpoints, External Middlewares, Bulk-Delete, Pagination #15–[ROADMAP] HHF Docs Documentation Backlog – Master Tracking Issue #23)
- Content plan with page structure, styleguide, and roadmap
Our approach: We work in our own fork, test on our staging, and submit PRs when ready. You review on staging or in the PR — no write access to your repos needed.
1. Writing Style & Content Depth
What we found: Current pages average 35-43 lines, many are stubs with headings but little content. Example: The Health page exists but doesn't explain what each health check does or how to interpret results.
Our suggestion: Expand pages to 80-120 lines with:
- Brief intro (what this feature does, when you'd use it)
- Configuration section with examples
- Troubleshooting section for common issues
Question: Does this direction work for you, or do you prefer keeping pages short and letting users figure things out from the UI?
2. Screenshots
What we found: Multiple pages have empty screenshot placeholders (`{/* Screenshot */}`). Some features are hard to understand without visuals (e.g., Hub Browser navigation, Security Hub configuration).
Our suggestion: Add screenshots for complex UI workflows, skip them for simple pages. We'd capture them from our staging instances.
Question: Should we add screenshots? Any preferences on style (full page vs. cropped, light/dark mode)?
3. CrowdSec Manager — Architecture & Router
What we found: The docs describe the HTTP router as `chi`, but the actual code (`internal/api/routes.go`) uses `gin-gonic/gin`. The response format is documented as `{"status": "success", "data": {}}` but the code uses `{"success": true, "data": {}}`. Go version is documented as 1.21 but `go.mod` shows 1.23+.
Our plan: Correct all of these to match the actual code.
Question: Was there a migration from chi to gin at some point? Just want to confirm we're not documenting a planned revert.
4. CrowdSec Manager — Undocumented Features
We found several fully implemented features with zero documentation:
| Feature | Code Location | What It Does |
|---|---|---|
| Hub Browser | 8 nav entries, 12 API endpoints, 6 pages | Browse, install, upgrade CrowdSec collections, parsers, scenarios |
| Config Validation | `internal/api/handlers/config_validation.go` | Detect drift between running config and saved snapshots |
| History | `internal/api/handlers/history.go` | Decision history with trends, charts, geographic data |
| Simulation Mode | `internal/api/handlers/simulation.go` | Toggle CrowdSec simulation mode from UI |
| Terminal | `web/src/pages/Terminal.tsx` | Web-based shell into the CrowdSec container |
| Multi-Host Docker | `DOCKER_HOSTS` env var in `config.go` | Manage multiple Docker hosts (docs say "not available") |
Question: Which of these are stable and should be documented? Any that are experimental or planned for removal?
5. CrowdSec Manager — Deployment Variants
We found three deployment configurations in the repo that aren't documented:
| File | Purpose |
|---|---|
| `docker-compose.pangolin.yml` | Deployment behind Pangolin reverse proxy |
| `charts/` | Helm chart for Kubernetes |
| Tailscale sidecar references | Tailscale integration in compose variants |
Question: Which of these are maintained and ready for documentation? Is the Pangolin compose the recommended setup for Pangolin users?
6. CrowdSec Manager — Environment Variables
What we found: `internal/config/config.go` defines 40+ environment variables, but the docs only cover 9. Notable undocumented ones:
| Variable | Purpose |
|---|---|
| `DOCKER_HOSTS` | Multi-host Docker management |
| `PANGOLIN_DIR` | Pangolin integration directory |
| `GEOAPIFY_API_KEY` | Geolocation for threat maps |
| `CAPTCHA_PROVIDER` | Turnstile/hCaptcha/reCAPTCHA selection |
| `RETENTION_DAYS` | Data retention period |
| `CROWDSEC_ACQUIS_FILE` | Path to acquisition config |
| `BACKUP_DIR` | Backup storage path |
Our plan: Document all of them with descriptions, defaults, and examples.
Question: Any env vars that are internal/deprecated and should NOT be documented?
7. Middleware Manager — Operating Mode
What we found: `ENABLE_FILE_CONFIG` switches between two fundamentally different modes:
- API Proxy Mode (default when `ENABLE_FILE_CONFIG=false`): Middlewares managed via API, proxied to Traefik
- File Provider Mode (when `ENABLE_FILE_CONFIG=true`): Middlewares written to Traefik's dynamic config file
The docs mostly describe the File Provider mode, but the code defaults to API Proxy.
Question: Which mode should we recommend to new users? Should both be documented equally, or is one the preferred path?
8. Middleware Manager — Security Hub Completeness
What we found: The Security Hub has three sub-features, but only one is documented:
| Feature | Documented | Implemented |
|---|---|---|
| mTLS | Yes (detailed page) | Yes |
| TLS Hardening | No | Yes (in code + UI) |
| Secure Headers | No | Yes (in code + UI) |
Our plan: Document TLS Hardening and Secure Headers with the same depth as the mTLS page.
Question: Are TLS Hardening and Secure Headers stable features? Any gotchas we should know about?
9. Middleware Manager — External Middlewares
What we found: The ability to assign Traefik-native middlewares (rate limiting, headers, etc.) to resources exists in code and UI but has no documentation at all.
Question: Is this the same as "Plugin Hub" in the navigation, or a separate feature? Is it stable?
10. Process Preferences
How we'd like to work:
- Submit PRs grouped by feature area (not one massive PR)
- Each PR links to our staging for visual review
- You review when convenient — no rush
Questions:
- PRs per feature area — does that work for you, or do you prefer a different grouping?
- Should we work against `main`, or is there a `docs` branch you'd prefer?
- Are you ok with us removing `test.mdx` from Middleware Manager docs? (appears to be a test page)
Items We Can Start Immediately (no questions needed)
These don't depend on any open questions:
- Fix Go version (1.21 → 1.23+), response format, router name in architecture docs
- Fix `TRAEFIK_API_URL` default value typo in Middleware Manager
- Remove `test.mdx` (pending confirmation above)
- Improve navigation structure (`meta.json` cleanup)
- Add missing page titles and descriptions
Activity
strausmann commentedon Mar 24, 2026
Additional Question: Test Environment
To create accurate documentation with real screenshots, verified workflows, and tested guides, we need a complete Pangolin stack with CrowdSec Manager and Middleware Manager running.
Would you be able to provide a test instance for documentation work?
What we'd need:
Why this matters:
If hosting is a concern, we can set up our own Hetzner CX22 VM (~4 EUR/month) and install the full stack ourselves. That would also serve as a dogfooding exercise — our setup experience becomes the Getting Started guide. We'd just need guidance on the recommended docker-compose configuration.
See #27 for our detailed infrastructure plan.
strausmann commentedon Mar 24, 2026
Additional Question: Documentation Versioning
Context: Both projects release new versions regularly (CrowdSec Manager v2.0.0 → v2.1.0, Middleware Manager dev → latest). Features change between versions, and users may run older versions.
Question: Should the documentation be versioned per release?
Options:
Fumadocs supports versioning via Next.js routing or manual directory structure. If versioning is desired, we should plan this before writing major new content — retrofitting is harder.
Our recommendation: Start with single version + changelog notes ("Added in v2.1.0" callouts). Add full versioning later if user demand justifies the maintenance cost.
oidebrett commentedon Apr 24, 2026
PR raised on Crowdsec-manager repo to address these issues. hhftechnology/crowdsec_manager#96
Summary of changes made to CrowdSec Manager documentation:
Fixed Inaccuracies
Architecture Documentation:
Changed router from chi to gin-gonic/gin to match actual code
Updated Go version from 1.21+ to 1.23+ to match go.mod
API Response Format:
Corrected from {"status": "success", "data": {...}} to {"success": true, "data": {...}} to match actual Response struct
Added Documentation for Previously Undocumented Features
Hub Browser - Browse, install, upgrade CrowdSec collections, parsers, scenarios
Config Validation - Detect drift between running config and saved snapshots
History - Decision history with trends, charts, geographic data
Simulation Mode - Toggle CrowdSec simulation mode from UI
Terminal - Web-based shell into the CrowdSec container
Multi-Host Docker - Manage multiple Docker hosts via DOCKER_HOSTS env var
Each new feature document includes:
Feature description and capabilities
API endpoints with examples
Usage instructions
Configuration notes
All changes were made to files following the existing documentation structure and style.
oidebrett commentedon Apr 25, 2026
PR Raised on Middleware-manager repo to address these issues: hhftechnology/middleware-manager#109
Completed Tasks:
Removed test.mdx file - Deleted the unnecessary test file from the docs
Fixed Go version references - Verified that the actual Go version is 1.24.0 (as shown in go.mod) and confirmed no documentation updates were needed for version references
Fixed TRAEFIK_API_URL default value - Corrected from http://host.docker.internal:8080/ to http://traefik:8080/ in environment.mdx
Improved navigation structure - Verified meta.json files were already correctly structured
Verified page titles and descriptions - All documentation pages already had appropriate titles and descriptions
Expanded Security Hub documentation - Added two new pages:
security-tls-hardening.mdx - Documenting TLS hardening feature
security-secure-headers.mdx - Documenting secure headers feature
Updated security/meta.json to include these new pages
Documented External Middlewares feature - Created ui-guides/external-middlewares.mdx explaining how to assign Traefik-native middlewares to resources, and updated ui-guides/meta.json
Documented both API Proxy Mode and File Provider Mode - Added detailed explanation to onboarding.mdx about the ENABLE_FILE_CONFIG environment variable and when to use each mode
Expanded documentation pages - Enhanced multiple pages to 80-120 lines with introduction, configuration, and troubleshooting sections, including:
dashboard.mdx (expanded to ~90 lines)
Several other key pages were enhanced with more detailed content
Added screenshot placeholders - Added screenshot placeholder divs to all expanded documentation pages for complex UI workflows
All documentation updates have been completed without modifying any code, focusing solely on improving the documentation as requested. The changes align with the recommendations in the GitHub issue to improve content depth, fix inaccuracies, and better document all available features.