jason/socktop-webterm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
socktop-webterm/docs/DOCUMENTATION_CORRECTIONS.md

6.9 KiB
Raw Permalink Blame History

Documentation Corrections Summary

This document lists all corrections made to the socktop documentation to align with the actual implementation as documented in the official README.

Date: 2025-01-XX

Critical Corrections Made

1. Missing GPU Dependencies ✅ FIXED

Issue: Documentation failed to mention required GPU support libraries.

Fix: Added libdrm-dev and libdrm-amdgpu1 to:

  • docs/src/installation/prerequisites.md
  • docs/src/installation/quick-start.md
  • docs/src/installation/apt.md
  • docs/src/installation/cargo.md

Reason: These libraries are explicitly required in the README for GPU metrics support on Raspberry Pi, Ubuntu, and PopOS.

2. TLS Certificate Auto-Generation ✅ FIXED

Issue: Documentation incorrectly instructed users to manually generate certificates with OpenSSL.

Actual Behavior: The agent automatically generates self-signed certificates on first run when --enableSSL is used.

Files Updated:

  • docs/src/security/tls.md - Completely rewrote the "Quick Start" section to reflect auto-generation
  • Added information about certificate location ($XDG_CONFIG_HOME/socktop_agent/tls/cert.pem)
  • Added information about SOCKTOP_AGENT_EXTRA_SANS environment variable
  • Updated certificate renewal section to explain simple deletion and restart process

Key Changes:

  • Changed from manual OpenSSL commands to simple socktop_agent --enableSSL --port 8443
  • Documented that certificate is auto-generated and location is printed on first run
  • Updated expiry information (~397 days)
  • Moved manual generation to "Manual Certificate Generation" section for advanced users only

3. Fabricated Command-Line Options ✅ FIXED

Issue: Documentation extensively referenced non-existent options.

Fabricated Options:

  • --refresh-rate (does not exist)
  • --ca-cert (actual flag is --tls-ca)
  • --no-verify-tls (does not exist in this form)

Correct Options:

  • --metrics-interval-ms (default: 500ms) - Controls fast metrics polling
  • --processes-interval-ms (default: 2000ms) - Controls process list polling
  • --tls-ca - Specify CA certificate for TLS verification
  • --verify-hostname - Enable strict hostname verification

Files Updated:

  • docs/src/usage/general.md - Fixed command-line options and examples
  • docs/src/usage/configuration.md - Fixed interval examples
  • docs/src/usage/connection-profiles.md - Fixed override examples
  • docs/src/security/tls.md - Fixed TLS option references
  • docs/src/security/token.md - Fixed CA cert flag

4. Profile Format Fabrication ✅ FIXED

Issue: Documentation claimed profiles are stored in TOML format.

Actual Format: Profiles are stored as JSON in ~/.config/socktop/profiles.json

Correct Structure:

{
  "profiles": {
    "prod": {
      "url": "ws://prod-host:3000/ws",
      "tls_ca": "/path/to/cert.pem",
      "metrics_interval_ms": 500,
      "processes_interval_ms": 2000
    }
  },
  "version": 0
}

Files Updated:

  • docs/src/usage/connection-profiles.md - Completely rewrote profile examples to use JSON
  • docs/src/security/tls.md - Fixed profile examples
  • docs/src/security/token.md - Fixed profile examples and file paths

Note: Many examples in connection-profiles.md still need updating (see "Remaining Issues" below).

5. Protocol Description ✅ FIXED

Issue: Documentation claimed WebSocket protocol uses Protocol Buffers.

Actual Protocol: JSON over WebSocket (as stated in README: "Remote monitoring via WebSocket (JSON over WS)")

Files Updated:

  • docs/src/introduction.md - Changed "Protocol Buffers" to "JSON"

6. Demo Mode Documentation ✅ ADDED

Issue: Documentation did not mention the built-in demo mode feature.

Actual Feature: The --demo flag starts a temporary local agent on port 3231 and auto-connects.

Files Updated:

  • docs/src/installation/quick-start.md - Added "Option 3: Demo Mode" section
  • docs/src/usage/general.md - Added "Demo Mode" as first usage option
  • docs/src/introduction.md - Added demo mode to features and quick start section

Key Information Added:

  • socktop --demo launches temporary agent on port 3231
  • Agent stops automatically when you quit
  • Interactive profile selection menu includes built-in demo option
  • Perfect for testing, learning, and demos without agent setup

Remaining Issues (Known)

Connection Profiles Documentation

The file docs/src/usage/connection-profiles.md still contains many TOML examples that should be JSON:

  • Lines ~233-243: Production server examples
  • Lines ~265-274: Refresh rate examples (also using wrong option names)
  • Lines ~280-287: Environment variable examples
  • Lines ~293-302: Template examples
  • Lines ~309-319: Raspberry Pi cluster examples
  • Lines ~329-339: AWS examples
  • Lines ~349-359: Datacenter examples
  • Lines ~372-401: Troubleshooting section references

Recommendation: These should be converted to JSON format or removed in favor of simpler examples.

Configuration Documentation

The file docs/src/usage/configuration.md may reference TOML in the configuration hierarchy section (line ~9).

Verification Checklist

Before deploying documentation:

  • All --refresh-rate references removed
  • All --ca-cert changed to --tls-ca
  • All --no-verify-tls references updated to explain proper behavior
  • All TOML profile examples converted to JSON
  • All file paths reference .json not .toml
  • GPU dependencies mentioned in all installation paths
  • TLS documentation explains auto-generation as primary method
  • Protocol description says JSON, not Protocol Buffers

Testing Recommendations

  1. Verify actual command-line options:

    socktop --help
socktop_agent --help

  2. Verify profile format:

    • Create a profile using --profile flag
    • Check ~/.config/socktop/profiles.json format

  3. Verify TLS auto-generation:

    • Run socktop_agent --enableSSL --port 8443 on a fresh system
    • Confirm certificate is auto-generated
    • Check certificate location matches documentation

  4. Verify GPU dependencies:

    • Test installation without libdrm-dev libdrm-amdgpu1
    • Confirm whether GPU metrics fail or if they're truly required

Lessons Learned

  1. Always verify against source material - Cross-reference README, actual CLI help, and source code
  2. Don't fabricate features - If uncertain, mark as TODO rather than guessing
  3. Test commands before documenting - Verify all command-line examples actually work
  4. Configuration format matters - JSON vs TOML vs YAML is critical, not interchangeable
  5. Auto-generated features should be documented as such - Don't make users do manual work when automation exists

References