feat: comprehensive debug logging across all controller modules
Add detailed [DEBUG] logging to every controller module when logging.level is set to "debug". Each module with stateful debug uses SetDebug(bool) wired from main.go. Covers stacks, backup, cloudflare, integrations, system, monitor, settings, scheduler, web handlers, storage, metrics, API, selfupdate, and assets. Also includes the app export/import (.fab bundles) feature from v0.32.0 and its debug page integration. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
+70
-26
@@ -13,19 +13,20 @@ A single, lightweight Go container that replaces Portainer + scattered systemd s
|
||||
- [Architecture](#architecture)
|
||||
- [Features](#features)
|
||||
- [App Management](#1-app-management)
|
||||
- [Backup System](#2-backup-system)
|
||||
- [Storage Management](#3-storage-management)
|
||||
- [Monitoring & Health](#4-monitoring--health)
|
||||
- [Notifications](#5-notifications)
|
||||
- [Update Management](#6-update-management)
|
||||
- [Authentication & Settings](#7-authentication--settings)
|
||||
- [Central Hub](#8-central-hub-reporting)
|
||||
- [Setup Wizard](#9-first-run-setup-wizard)
|
||||
- [Disaster Recovery](#10-disaster-recovery)
|
||||
- [Asset Sync](#11-asset-sync)
|
||||
- [Debug Mode](#12-debug-mode)
|
||||
- [Geo-Restriction](#13-geo-restriction)
|
||||
- [App-to-App Integrations](#14-app-to-app-integrations)
|
||||
- [App Export/Import](#2-app-exportimport-fab-bundles)
|
||||
- [Backup System](#3-backup-system)
|
||||
- [Storage Management](#4-storage-management)
|
||||
- [Monitoring & Health](#5-monitoring--health)
|
||||
- [Notifications](#6-notifications)
|
||||
- [Update Management](#7-update-management)
|
||||
- [Authentication & Settings](#8-authentication--settings)
|
||||
- [Central Hub](#9-central-hub-reporting)
|
||||
- [Setup Wizard](#10-first-run-setup-wizard)
|
||||
- [Disaster Recovery](#11-disaster-recovery)
|
||||
- [Asset Sync](#12-asset-sync)
|
||||
- [Debug Mode](#13-debug-mode)
|
||||
- [Geo-Restriction](#14-geo-restriction)
|
||||
- [App-to-App Integrations](#15-app-to-app-integrations)
|
||||
- [Repository Layout](#repository-layout)
|
||||
- [Configuration](#configuration)
|
||||
- [REST API](#rest-api)
|
||||
@@ -106,6 +107,7 @@ A single, lightweight Go container that replaces Portainer + scattered systemd s
|
||||
| **Assets** | `internal/assets/` | Hub-managed asset syncer: downloads logos/screenshots with SHA-256 change detection |
|
||||
| **SelfTest** | `internal/selftest/` | Startup self-test: 9 diagnostic checks (Docker, dirs, storage, hub, restic, metrics) |
|
||||
| **Util** | `internal/util/` | Shared utilities: `TruncateStr` for debug log output truncation |
|
||||
| **AppExport** | `internal/appexport/` | Per-app export/import via `.fab` bundles (config + DB + user data), optional AES-256 encryption |
|
||||
| **API** | `internal/api/` | REST JSON endpoints, diagnostic dump (`/api/debug/dump`) |
|
||||
| **Web** | `internal/web/` | Hungarian dashboard, auth, page handlers, template functions, alerts |
|
||||
|
||||
@@ -234,7 +236,27 @@ Multiple checks per app are supported (all must pass). The probe scheduler runs
|
||||
|
||||
---
|
||||
|
||||
### 2. Backup System
|
||||
### 2. App Export/Import (.fab bundles)
|
||||
|
||||
Per-app export creates a self-contained `.fab` file (tar.gz, optionally encrypted) that can be stored externally or used to restore the app on the same server. Distinct from the automatic backup system — user-initiated, per-app, produces a single portable file.
|
||||
|
||||
**Bundle contents:** `manifest.json` + `config/` (compose, .felhom.yml, app.yaml with plaintext secrets) + `database/` (gzipped SQL dump) + `data/` (HDD bind mount tars or Docker named volume tars).
|
||||
|
||||
**Encryption:** Optional AES-256-CTR + HMAC-SHA256 with scrypt key derivation (N=32768). Format: `"FABE"` magic header + salt + IV + encrypted tar.gz + HMAC tag. Streaming for multi-GB files.
|
||||
|
||||
**Export flow:** Estimate size → check free space → optionally stop app → copy config → dump DB → tar user data → create tar.gz → optionally encrypt → atomic rename. App restarts automatically after export if it was stopped.
|
||||
|
||||
**Import flow:** Decrypt if needed → extract → prepare stack dir (create new or `compose down --volumes` for existing) → restore config (re-encrypt app.yaml with current server key) → restore user data (HDD or volumes) → restore DB (start DB service, wait for ready, import dump) → start full stack → refresh UI.
|
||||
|
||||
**Architecture:** `internal/appexport/` package with `ExportStackProvider` adapter interface (same pattern as `backup.StackDataProvider`). `exportAdapter` in `main.go` bridges `stacks.Manager` to the provider.
|
||||
|
||||
**API endpoints:** `/api/export/estimate`, `/api/export/start`, `/api/export/status`, `/api/export/bundles`, `/api/export/manifest`, `/api/export/import`, `/api/export/import/status`.
|
||||
|
||||
**UI:** Export button on app info page, standalone import page at `/import` accessible from the stacks page header.
|
||||
|
||||
---
|
||||
|
||||
### 3. Backup System
|
||||
|
||||
The backup system implements a **3-2-1 backup architecture**. Each tier is a **complete,
|
||||
self-sufficient backup** — any single tier can fully restore an app.
|
||||
@@ -441,7 +463,7 @@ not just those with HDD data. Non-HDD apps can configure destination, method, an
|
||||
|
||||
---
|
||||
|
||||
### 3. Storage Management
|
||||
### 4. Storage Management
|
||||
|
||||
The storage subsystem handles the full lifecycle of external storage: detection, initialization, path registration, and data migration.
|
||||
|
||||
@@ -554,7 +576,7 @@ Continuously monitors registered storage paths for disconnection/reconnection (p
|
||||
|
||||
---
|
||||
|
||||
### 4. Monitoring & Health
|
||||
### 5. Monitoring & Health
|
||||
|
||||
#### System Health Checks (`internal/monitor/healthcheck.go`)
|
||||
|
||||
@@ -610,7 +632,7 @@ State-based alerts displayed on all pages:
|
||||
|
||||
---
|
||||
|
||||
### 5. Notifications
|
||||
### 6. Notifications
|
||||
|
||||
#### Hub Event System (`internal/notify/notifier.go`)
|
||||
|
||||
@@ -660,7 +682,7 @@ Notification preferences (email, enabled events, cooldown hours) are:
|
||||
|
||||
---
|
||||
|
||||
### 6. Update Management
|
||||
### 7. Update Management
|
||||
|
||||
#### App Catalog Sync
|
||||
|
||||
@@ -807,7 +829,7 @@ self_update:
|
||||
|
||||
---
|
||||
|
||||
### 7. Authentication & Settings
|
||||
### 8. Authentication & Settings
|
||||
|
||||
#### Session Auth (`internal/web/auth.go`)
|
||||
|
||||
@@ -868,7 +890,7 @@ Five sections:
|
||||
|
||||
---
|
||||
|
||||
### 8. Central Hub Reporting
|
||||
### 9. Central Hub Reporting
|
||||
|
||||
#### Report Push (`internal/report/`)
|
||||
|
||||
@@ -923,7 +945,7 @@ The hub service (separate Go app in the `felhom.eu` repo) provides:
|
||||
- Color coding: green (<30min), yellow (30-60min), red (>60min since last report)
|
||||
- 90-day report + event retention with daily prune at 04:30 Budapest time
|
||||
|
||||
### 9. First-Run Setup Wizard
|
||||
### 10. First-Run Setup Wizard
|
||||
|
||||
When the controller starts with no valid customer configuration (`customer.id` empty), it enters **setup mode** — a web-based wizard that handles all initial configuration. This replaces the old interactive shell wizard in `docker-setup.sh`.
|
||||
|
||||
@@ -1010,7 +1032,7 @@ During setup wizard drive scan, both current and historical backups are discover
|
||||
|
||||
Generates `recovery-info.txt` on the system data partition with customer ID, Hub URL, retrieval password, and recovery instructions in Hungarian. Updated on startup and after config changes. Also displayed on the Settings page in a "Vészhelyzeti információk" section.
|
||||
|
||||
### 10. Disaster Recovery
|
||||
### 11. Disaster Recovery
|
||||
|
||||
When a system drive fails and is replaced, the recovery flow uses the setup wizard:
|
||||
|
||||
@@ -1040,7 +1062,7 @@ When a system drive fails and is replaced, the recovery flow uses the setup wiza
|
||||
|
||||
---
|
||||
|
||||
### 11. Asset Sync
|
||||
### 12. Asset Sync
|
||||
|
||||
App assets (logos, screenshots) are managed centrally by the Hub and downloaded to each controller via a daily sync process. This decouples asset updates from controller image rebuilds — new app icons only require a Hub redeploy.
|
||||
|
||||
@@ -1096,7 +1118,7 @@ The Hub serves three asset types per app:
|
||||
|
||||
---
|
||||
|
||||
### 12. Debug Mode
|
||||
### 13. Debug Mode
|
||||
|
||||
When `logging.level: "debug"` is set in `controller.yaml`, the controller exposes a full diagnostic dashboard at `/debug` with 9 testing sections. All debug endpoints are gated — at `info` level, the sidebar link disappears and all `/api/debug/*` routes return 404.
|
||||
|
||||
@@ -1123,9 +1145,31 @@ When `logging.level: "debug"` is set in `controller.yaml`, the controller expose
|
||||
- **DebugCallbacks**: 7 closures wired from main.go for operations needing modules not on Server struct (hub push, infra backup, connectivity tests, telemetry preview).
|
||||
- **Telemetry debug**: `GetTelemetryPreview` callback calls `report.BuildAppTelemetryForDebug()` (exported wrapper around the private `buildAppTelemetrySection()`). Result renders as a table with collapsible raw JSON. Available regardless of hub configuration.
|
||||
|
||||
#### Per-Module Debug Logging
|
||||
|
||||
When `logging.level: "debug"`, every module emits detailed `[DEBUG] [module]` prefixed log lines. Each module with stateful debug (struct-based) exposes a `SetDebug(bool)` method, wired from `main.go`. Modules without a struct use package-level `DebugLogger` variables (e.g., `system.DebugLogger`).
|
||||
|
||||
| Module | Debug Field | Prefix | Key Areas |
|
||||
|--------|------------|--------|-----------|
|
||||
| `stacks` | `cfg.Logging.Level` | `[DEBUG] [stacks]` | Stack CRUD, compose commands, env vars, HDD mounts, encryption migration, health probes |
|
||||
| `backup` | `ResticManager.debug` | `[DEBUG] [restic]` / `[DEBUG] [backup]` | Restic commands, snapshot operations, restore scanning, drive mounting |
|
||||
| `cloudflare` | `Client.debug` + `GeoSyncManager.debug` | `[CF-DEBUG]` / `[DEBUG] [cloudflare]` | API requests/responses, WAF rule CRUD, zone resolution, geo sync diff |
|
||||
| `integrations` | `Manager.debug` | `[DEBUG] [integrations]` | Toggle apply/revoke timing, lifecycle hooks, config reapply |
|
||||
| `system` | `DebugLogger` | `[DEBUG] [system]` | Memory/disk/CPU/load/temp collection, mount probing, USB detection |
|
||||
| `monitor` | `Pinger.debug` | `[DEBUG] [pinger]` | Health ping URLs, retry attempts, response codes |
|
||||
| `settings` | `Settings.debug` | `[DEBUG] [settings]` | Load/save sizes, storage path ops, geo/integration state changes |
|
||||
| `scheduler` | `Scheduler.debug` | `[DEBUG] [sched]` | Job registration, execution timing, daily schedule calculations |
|
||||
| `web` | `cfg.Logging.Level` | `[DEBUG] [web]` | HTTP requests, auth decisions, session management, storage API ops |
|
||||
| `api` | `Router.debug` | `[DEBUG] [api]` | API routing, handler entry points, request details |
|
||||
| `selfupdate` | `Updater.debug` | `[DEBUG] [selfupdate]` | Version checks, update preconditions, docker pull timing |
|
||||
| `assets` | `Syncer.debug` | `[DEBUG] [assets]` | Manifest fetch, hash comparison, file download timing |
|
||||
| `storage` | logger-based | `[DEBUG] [storage]` | Disk scanning, formatting, attach, drive migration |
|
||||
| `metrics` | logger-based | `[DEBUG] [metrics]` | Per-container log scanning, error/warning counts |
|
||||
| `appexport` | `Exporter.debug` | `[DEBUG] [appexport]` | Export/import steps, crypto operations, bundle scanning |
|
||||
|
||||
---
|
||||
|
||||
### 13. Geo-Restriction
|
||||
### 14. Geo-Restriction
|
||||
|
||||
Country-based access control via **Cloudflare WAF Custom Rules**. The controller manages WAF rules in the `http_request_firewall_custom` phase to block requests from non-allowed countries. Rules are identified by a `[felhom-geo]` description prefix — other WAF rules are never touched.
|
||||
|
||||
@@ -1223,7 +1267,7 @@ All mutating endpoints trigger an async Cloudflare sync. The `/api/geo/` path ac
|
||||
|
||||
---
|
||||
|
||||
### 14. App-to-App Integrations
|
||||
### 15. App-to-App Integrations
|
||||
|
||||
Generic framework for connecting deployed applications to each other. Provider apps declare available integrations in `.felhom.yml`, and users enable/disable them via toggle switches on the provider's deploy/settings page ("Beállítások").
|
||||
|
||||
|
||||
Reference in New Issue
Block a user