mirror of
https://github.com/nicolargo/glances.git
synced 2026-04-19 05:18:04 -04:00
121 lines
3.8 KiB
Markdown
121 lines
3.8 KiB
Markdown
# CLAUDE.md — Glances Maintainer Context
|
|
|
|
> Auto-loaded by Claude Code at the start of every session.
|
|
> Glances-specific context. Global principles (role, refactoring strategy,
|
|
> contribution tone, communication, output formats) are in `~/.claude/CLAUDE.md`.
|
|
|
|
---
|
|
|
|
## Tech stack
|
|
|
|
| Layer | Technology |
|
|
| --- | --- |
|
|
| Backend | Python, psutil, FastAPI (REST API), curses (TUI) |
|
|
| Frontend | Vue.js, Bootstrap 5, SCSS |
|
|
| Export plugins | InfluxDB, MongoDB, MQTT, DuckDB, and others |
|
|
| Infrastructure | GitHub Actions, Helm/Kubernetes, Snap (snapcraft) |
|
|
| LLM abstraction | LiteLLM (multi-provider) |
|
|
| GPU/NPU monitoring | pynvml, sysfs/debugfs |
|
|
|
|
---
|
|
|
|
## Reference docs (use `@` to load on demand)
|
|
|
|
- **Commands & setup**: `@.claude/docs/commands.md`
|
|
- **Architecture**: `@.claude/docs/architecture.md`
|
|
|
|
---
|
|
|
|
## Code principles (Glances-specific)
|
|
|
|
### Exception handling for Snap confinement
|
|
|
|
Wrap the `open()` call inside `try/except`, not just the `read()`. Snap's strict
|
|
confinement blocks host file access at the open stage, not the read stage.
|
|
|
|
### Kubernetes workloads
|
|
|
|
Use a **DaemonSet** (one pod per node) for system-level monitoring.
|
|
Prefer `SYS_PTRACE` over `privileged: true`.
|
|
|
|
---
|
|
|
|
## Security (Glances-specific)
|
|
|
|
Glances runs unauthenticated by default — this is intentional and documented.
|
|
Most users deploy on private networks for personal use. See global CLAUDE.md
|
|
for the general OSS security philosophy (4 rules).
|
|
|
|
### Sensitive endpoints
|
|
|
|
- `/api/4/config` and `/api/4/args` — never expose credentials in plain text
|
|
(InfluxDB passwords, MongoDB tokens, MQTT passphrases, SSL key paths, etc.)
|
|
for unauthenticated access. Use the conditional `as_dict_secure()` method,
|
|
applied when `self.args.password` is `False`.
|
|
- CORS: `allow_origins=["*"]` + `allow_credentials=True` is invalid per the
|
|
CORS spec and reflected by Starlette. Default: `allow_credentials=False`.
|
|
- DNS rebinding: `TrustedHostMiddleware` via `webui_allowed_hosts` (optional).
|
|
The MCP endpoint is already protected via `mcp_allowed_hosts` +
|
|
`TransportSecuritySettings` in `glances/outputs/glances_mcp.py`.
|
|
|
|
---
|
|
|
|
## Contribution management (Glances-specific)
|
|
|
|
### Before merging a PR
|
|
- [ ] The code is actively used (no dead code)
|
|
- [ ] Existing tests pass
|
|
- [ ] New behaviour is covered by tests
|
|
- [ ] New configuration keys are documented
|
|
- [ ] Breaking changes are identified and documented
|
|
- [ ] The PR targets the correct branch
|
|
- [ ] Code should be formated and linted (make lint && make format)
|
|
|
|
### Glances-specific output formats
|
|
|
|
| Deliverable | Format |
|
|
| --- | --- |
|
|
| Changelog entry | `.rst` file following the `NEWS.rst` format |
|
|
| Helm Chart | `.tgz` archive or structured directory |
|
|
|
|
### Safe refactoring — applied example
|
|
|
|
Plugin dependency DAG — keep the hardcoded dict as fallback, add class-attribute
|
|
discovery, deprecate the dict over two releases.
|
|
|
|
---
|
|
|
|
## UI / TUI
|
|
|
|
### Web UI
|
|
Stack: Vue.js + Bootstrap 5 + SCSS.
|
|
|
|
Design principles:
|
|
- Strict typographic consistency across all plugins (size, weight, opacity,
|
|
letter-spacing).
|
|
- Pixel-perfect sparkline alignment (CSS grid, fixed row heights).
|
|
- Footer = vertical alert list (up to 10 entries), not a single horizontal row.
|
|
- No gauges — prefer sparklines with an inline current value.
|
|
|
|
### TUI (curses)
|
|
- 256-colour system with automatic fallback for limited terminals.
|
|
- Lightweight hierarchical separators for information density.
|
|
|
|
---
|
|
|
|
## CI/CD — GitHub Actions
|
|
|
|
In `build_docker.yml`, the trigger condition combines branch exclusion and event
|
|
type — a dynamic matrix with zero entries causes a silent failure without this
|
|
guard:
|
|
|
|
```yaml
|
|
if: >
|
|
github.event_name != 'pull_request' &&
|
|
(github.ref == 'refs/heads/develop' || startsWith(github.ref, 'refs/tags/'))
|
|
```
|
|
|
|
The `master` branch does not trigger a Docker build (empty matrix = silent
|
|
failure without this condition).
|
|
|