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

6.9 KiB
Raw 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