diff --git a/docs/ARCHITECTURE_NOTES.md b/docs/ARCHITECTURE_NOTES.md deleted file mode 100644 index 27bc8c6..0000000 --- a/docs/ARCHITECTURE_NOTES.md +++ /dev/null @@ -1,94 +0,0 @@ -# SecuBox Architecture Notes - -**Version:** 1.0.0 -**Last Updated:** 2025-12-28 -**Status:** Active - -These notes capture the current repository structure, conventions, and supporting tooling after scanning the tree (`luci-app-*`, `secubox-tools/`, `secubox-app-*`, `scripts/`), the root `README.md`, and the docs set (`docs/`, `DOCS/`, `TODO-ANALYSE.md`, `secubox-tools/README.md`, `scripts/README.md`, `docs/module-status.md`, `docs/claude.md`, `docs/documentation-index.md`). Treat this file as the canonical orientation guide before extending the platform. - ---- - -## 1. Repository Layout - -- **LuCI applications (`luci-app-*`)** - Each module ships a LuCI frontend (`htdocs/luci-static/resources/...`), RPCD backend (POSIX shell in `root/usr/libexec/rpcd/luci.`), menu + ACL JSON, optional CSS, and a module-specific README. Views follow the “menu path == file path” rule stressed in the documentation. - -- **Device/service packages (`secubox-app-*`)** - Native packages that install supporting services or CLIs (e.g., `secubox-app-zigbee2mqtt` installs `/etc/config/zigbee2mqtt`, `/etc/init.d/zigbee2mqtt`, and `/usr/sbin/zigbee2mqttctl`). These expose helpers that LuCI apps consume. - -- **Themes & shared assets** - `luci-theme-secubox` carries the design system (dark palette, `sh-*`/`sb-*` classes, Inter + JetBrains Mono). Every LuCI view imports `secubox-theme/secubox-theme.css` plus module-specific CSS as needed. - -- **Tooling (`secubox-tools/`)** - Contains validation (`validate-modules.sh`), build automation (`local-build.sh`), permission repair, deployment helpers, and debug loggers. These scripts mirror GitHub Actions workflows and should be reused for new installer/test tooling. The `secubox-app` CLI now lives here as well, consuming manifests under `/usr/share/secubox/plugins/` to install and configure “apps”. - -- **Automation/scripts (`scripts/`)** - Hosts documentation publishing helpers plus existing diagnostics/smoke scripts. New repo-wide diagnostics should live alongside them. - -- **Docs** - Two mirrored trees (`docs/` and uppercase `DOCS/`) feed MkDocs and the GitHub wiki. All Markdown follows the metadata template defined in `docs/documentation-index.md`. - -- **Profiles & App Manifests** - App manifests now live under `/usr/share/secubox/plugins/`, profiles under `/usr/share/secubox/profiles/`. `luci-app-secubox` exposes both through the wizard (UI) and `secubox-app` CLI (automation). - ---- - -## 2. Target Platforms & Build System - -- **Supported OpenWrt targets:** ARM64 (aarch64-cortex-a53/a72/generic), x86_64, and legacy MIPS variants (per `secubox-tools/local-build.sh` + README badges). -- **Package formats:** `.ipk` for ≤24.10, `.apk` for 25.12/SNAPSHOT (handled automatically by `local-build.sh`). -- **CI:** GitHub workflows (`.github/workflows/build-openwrt-packages.yml`, `test-validate.yml`) validate and build all modules. Local parity is achieved via `secubox-tools/local-build.sh full`. -- **Validation:** `./secubox-tools/validate-modules.sh` runs seven structural checks (RPC naming, menu/view parity, permissions, JSON lint, etc.). `fix-permissions.sh` enforces 755 for RPCD scripts and 644 for CSS/JS. - ---- - -## 3. Configuration & Runtime Patterns - -- **UCI-first approach:** Every feature stores runtime state in `/etc/config/`. CLIs/editors mutate entries via `uci set/commit`, and procd services read from UCI (see `secubox-app-zigbee2mqtt` or `luci-app-vhost-manager`). -- **Service supervision:** Daemons use `/etc/init.d/` with `USE_PROCD=1`. Procd wrappers call helper CLIs (e.g., `/usr/sbin/zigbee2mqttctl service-run`). -- **RPCD backends:** Implemented in POSIX shell. Filename equals ubus object (`root/usr/libexec/rpcd/luci.zigbee2mqtt` => `object: 'luci.zigbee2mqtt'`). They orchestrate UCI, system utilities, Docker, etc. -- **LuCI frontends:** Built with `view.extend` and the SecuBox design components (stat cards, tab strips, forms). Each module includes `api.js` wrappers that call the matching ubus object. Auto-refresh uses `poll()` or manual timers. -- **Logging/diagnostics:** `secubox-log` helper aggregates module activity under `/var/log/seccubox.log`. Additional repo-wide diagnostics live under `scripts/diagnose.sh`. - ---- - -## 4. Network & Security Conventions - -- **Firewall & zones:** Modules such as `luci-app-client-guardian` and `luci-app-network-modes` manipulate UCI firewall sections. They always backup configs before applying and keep the LAN management path reachable. -- **Network modes:** `luci-app-network-modes` already models router/relay/AP/sniffer modes with wizards + rollback. Any future “profile” or “DMZ” work should reuse its UCI techniques and UI flow. -- **Reverse proxy:** `luci-app-vhost-manager` manages `/etc/config/vhosts`, renders nginx configs, handles basic auth, and integrates ACME. It is the baseline for any new vhost/TLS features. -- **Access control:** ACL JSON lives in `root/usr/share/rpcd/acl.d/`. `docs/permissions-guide.md` plus `DOCS/CODEX.md` enumerate the ubus permissions each module should request. - ---- - -## 5. Existing App Ecosystem (Snapshot) - -From `docs/module-status.md` and module READMEs: - -- **Core dashboards:** `luci-app-secubox`, `luci-app-system-hub`. -- **Security/monitoring:** CrowdSec, Netdata, Netifyd, WireGuard, Client Guardian, Auth Guardian. -- **Network orchestration:** Network Modes, Traffic Shaper, Bandwidth Manager, Media Flow, CDN Cache. -- **Device apps:** Zigbee2MQTT already ships as `secubox-app-zigbee2mqtt` + `luci-app-zigbee2mqtt`. -- **Reverse proxy:** `luci-app-vhost-manager`. - -These modules provide working references for RPC patterns, UI layouts, wizards, and integration with system services. - ---- - -## 6. Documentation Standards & Roadmap - -- Every Markdown file must include `Version/Last Updated/Status` headers (per `docs/documentation-index.md` and `TODO-ANALYSE.md`). -- Cross-link related docs (Quick Start ↔ Development Guidelines ↔ Codex). -- Archive stale docs under `docs/archive/`. -- `TODO-ANALYSE.md` tracks ongoing documentation work (version standardization, cross-references, architecture diagrams). Keep this file updated when touching docs. - ---- - -## 7. Key Takeaways for Future Work - -1. **Extend, don’t fork:** Build new features (Docker apps, App Store, wizard, DMZ mode) on top of existing packages (Zigbee2MQTT installer, Network Modes, VHost Manager) instead of introducing parallel systems. -2. **Reuse tooling:** Diagnostics, smoke tests, and installers should hook into `secubox-tools/` or `scripts/` so they can be invoked locally and in CI. -3. **Stay POSIX + UCI driven:** Shell scripts, UCI config, and procd remain the glue for Docker/LXC orchestration on resource-constrained routers. -4. **Document everything twice:** Update both `docs/` (MkDocs) and `DOCS/` (wiki) trees when adding guides such as the requested embedded notes. - -These notes should be revised whenever new components (App Store, wizard, profiles, DMZ, Docker/LXC frameworks) land so contributors always have an up-to-date architectural map. diff --git a/docs/development-guidelines.md b/docs/development-guidelines.md index d87ff5a..6e93ef3 100644 --- a/docs/development-guidelines.md +++ b/docs/development-guidelines.md @@ -20,6 +20,7 @@ Ce document définit les standards, bonnes pratiques et validations obligatoires 7. [Common Errors & Solutions](#common-errors--solutions) 8. [Validation Checklist](#validation-checklist) 9. [Deployment Procedures](#deployment-procedures) +10. [AI Assistant Context Files](#ai-assistant-context-files) --- @@ -167,6 +168,12 @@ graph TB #### 1. Page Header (Standard) +**REQUIREMENT:** Every module view MUST begin with this compact `.sh-page-header`. Do not introduce bespoke hero sections or oversized banners; the header keeps height predictable (title + subtitle on the left, stats on the right) and guarantees consistency across SecuBox dashboards. If no stats are needed, keep the container but supply an empty `.sh-stats-grid` for future metrics. + +**Slim variant:** When the page only needs 2‑3 metrics, use `.sh-page-header-lite` + `.sh-header-chip` (see `luci-app-vhost-manager` and `luci-app-secubox` settings). Chips carry an emoji/icon, a tiny label, and the value; colors (`.success`, `.danger`, `.warn`) communicate state. This variant replaces the bulky hero blocks from older demos. + +**Version chip:** Always expose the package version from the RPC backend (read from `/usr/lib/opkg/info/.control`) and display it as the first chip (`icon: 🏷️`). That keeps the UI and `PKG_VERSION` in sync without hunting for hard-coded strings. + **HTML Structure:** ```javascript E('div', { 'class': 'sh-page-header' }, [ @@ -1830,6 +1837,30 @@ var(--sh-hover-bg) /* Hover background */ --- +## AI Assistant Context Files + +SecuBox work is shared between Claude and Codex assistants. Keep the context folders synchronized so any agent can resume work quickly: + +| Directory | File | Usage | +|-----------|------|-------| +| `.claude/` | `HISTORY.md` | Chronological log of UI/theme changes and major deployments | +| `.claude/` | `TODO.md` | High-level backlog (UX polish, docs, automation ideas) | +| `.claude/` | `WIP.md` | Active tasks, risks, and immediate next steps | +| `.codex/` | `HISTORY.md` | Mirrors the development timeline for Codex sessions | +| `.codex/` | `TODO.md` | Tooling-focused tasks (linting, scripts, build automation) | +| `.codex/` | `WIP.md` | Status tracker for ongoing Codex efforts | + +**Maintenance rules** + +1. **Update after each session:** When finishing work, append a short bullet to HISTORY and adjust WIP/TODO so they reflect the new state. +2. **Reference deployment scripts:** Note which `secubox-tools/*.sh` script was used (dashboard vs. full deploy) so the next assistant knows how to reproduce it. +3. **Keep entries concise:** A single paragraph or bullet per update is enough; detailed specs remain in DOCS. +4. **Cross-check before big changes:** Read both folders before starting work to avoid conflicts or duplicate efforts. + +Treat these files as living handoff notes—if they drift, onboarding a new AI/teammate becomes significantly slower. + +--- + ## Conclusion Ce guide doit être consulté **AVANT** de: diff --git a/docs/documentation-index.md b/docs/documentation-index.md index f242b96..ffe4fb9 100644 --- a/docs/documentation-index.md +++ b/docs/documentation-index.md @@ -211,77 +211,32 @@ Follow this template when creating or revising documentation: #### **embedded/docker-zigbee2mqtt.md** 🔌 *Deploy Zigbee2MQTT via Docker on SecuBox (ARM64).* -**Contents:** -- Prerequisite checklist (storage, cgroups, USB coordinator, Docker packages) -- Usage of `zigbee2mqttctl` (install/check/update/status/logs) -- UCI configuration reference (`/etc/config/zigbee2mqtt`) -- Troubleshooting + rollback/uninstall steps - -**When to use:** Setting up Zigbee2MQTT before the LuCI UI is available. - -**Size:** Short (~100 lines) +Pointer: see `docs/embedded/docker-zigbee2mqtt.md` for the canonical version. #### **embedded/vhost-manager.md** 🌐 -*How to publish local services behind nginx with vhost manager + CLI helper.* +*How to publish services through nginx using the vhost manager and CLI helper.* -**Contents:** -- Overview of `luci-app-vhost-manager` UI -- CLI usage for `scripts/vhostctl.sh` (list/add/remove/reload) -- Example mapping for Zigbee2MQTT -- Troubleshooting tips (ACME, manual certs, upstream errors) - -**When to use:** Exposing Docker/LXC apps through HTTPS or integrating profiles/wizards. - -**Size:** Short (~120 lines) +Pointer: see `docs/embedded/vhost-manager.md` for the canonical version. #### **embedded/app-store.md** 🛒 -*Plugin manifest format and SecuBox App Store CLI.* +*Plugin manifest format and CLI for the SecuBox App Store.* -**Contents:** -- Manifest schema (id/type/packages/actions, wizard metadata) -- Example manifest for Zigbee2MQTT -- `secubox-app` CLI usage (list/show/install/status/update/remove) -- Notes on future LuCI App Store + profile integration - -**When to use:** Creating new app manifests or scripting installs via CLI. - -**Size:** Short (~120 lines) +Pointer: see `docs/embedded/app-store.md` for the canonical version. #### **embedded/wizard-profiles.md** 🧭 -*First-run wizard + OS-like profiles.* +*First-run wizard and OS-like profiles.* -**Contents:** -- First-run checklist (password, timezone, storage, network mode) -- Using manifest-driven app wizards -- Baseline profiles (Home, Lab, Hardened, Gateway+DMZ) and rollback mechanics - -**When to use:** Guiding new deployments or applying pre-made bundles. - -**Size:** Short (~130 lines) +Pointer: see `docs/embedded/wizard-profiles.md` for the canonical version. #### **embedded/lyrion-docker.md** 🎵 *Deploy Lyrion Media Server via Docker.* -**Contents:** -- `secubox-app-lyrion` installer usage -- UCI options (`/etc/config/lyrion`) and CLI helper commands -- VHost exposure steps and troubleshooting - -**When to use:** Hosting Lyrion through the SecuBox App Store/wizard workflow. - -**Size:** Short (~120 lines) +Pointer: see `docs/embedded/lyrion-docker.md` for the canonical version. #### **embedded/domoticz-docker.md** 🏠 *Deploy Domoticz home automation via Docker.* -**Contents:** -- `secubox-app-domoticz` usage and `domoticzctl` commands -- UCI options + wizard fields -- VHost + DMZ profile guidance - -**When to use:** Hosting Domoticz using the new App Store manifest. - -**Size:** Short (~120 lines) +Pointer: see `docs/embedded/domoticz-docker.md` for the canonical version. --- diff --git a/docs/embedded/app-store.md b/docs/embedded/app-store.md deleted file mode 100644 index b5bb180..0000000 --- a/docs/embedded/app-store.md +++ /dev/null @@ -1,101 +0,0 @@ -# SecuBox App Store & Manifests - -**Version:** 1.0.0 -**Last Updated:** 2025-12-28 -**Status:** Active - -This guide outlines the initial “SecuBox Apps” registry format and the `secubox-app` CLI helper. It currently ships with manifests for Zigbee2MQTT and Lyrion, and easily scales to other Docker/LXC/native services. - ---- - -## Manifest Layout (`plugins//manifest.json`) - -Each plugin folder contains a `manifest.json`. Example (Zigbee2MQTT): - -```json -{ - "id": "zigbee2mqtt", - "name": "Zigbee2MQTT", - "type": "docker", - "description": "Dockerized Zigbee gateway", - "packages": ["secubox-app-zigbee2mqtt", "luci-app-zigbee2mqtt"], - "ports": [{ "name": "frontend", "protocol": "http", "port": 8080 }], - "volumes": ["/srv/zigbee2mqtt"], - "network": { "default_mode": "lan", "dmz_supported": true }, - "wizard": { - "uci": { "config": "zigbee2mqtt", "section": "main" }, - "fields": [ - { "id": "serial_port", "label": "Serial Port", "type": "text", "uci_option": "serial_port", "placeholder": "/dev/ttyACM0" }, - { "id": "mqtt_host", "label": "MQTT Host", "type": "text", "uci_option": "mqtt_host", "placeholder": "mqtt://127.0.0.1:1883" }, - { "id": "mqtt_username", "label": "MQTT Username", "type": "text", "uci_option": "mqtt_username" }, - { "id": "mqtt_password", "label": "MQTT Password", "type": "password", "uci_option": "mqtt_password" }, - { "id": "base_topic", "label": "Base Topic", "type": "text", "uci_option": "base_topic" }, - { "id": "frontend_port", "label": "Frontend Port", "type": "number", "uci_option": "frontend_port" } - ] - }, - "profiles": ["home", "lab"], - "actions": { - "install": "zigbee2mqttctl install", - "check": "zigbee2mqttctl check", - "update": "zigbee2mqttctl update", - "status": "/etc/init.d/zigbee2mqtt status" - } -} -``` - -**Required keys** - -| Key | Purpose | -|-----|---------| -| `id` | Unique identifier used by the CLI (`secubox-app install `). | -| `name` / `description` | Display metadata. | -| `type` | `docker`, `lxc`, or `native`. | -| `packages` | List of OpenWrt packages to install/remove. | -| `actions.install/update/check/status` | Optional shell commands executed after opkg operations. | - -**Optional keys** - -- `ports`: Document exposed services for the App Store UI. -- `volumes`: Persistent directories (e.g., `/srv/zigbee2mqtt`). -- `network`: Defaults + whether DMZ mode is supported. -- `wizard`: Declarative form metadata (`uci.config`, `uci.section`, `fields[*].uci_option`). -- `profiles`: Tags to pre-load when applying OS-like profiles. - ---- - -## CLI Usage (`secubox-app`) - -`luci-app-secubox` installs the CLI as `/usr/sbin/secubox-app` (also available under `secubox-tools/` for development). Commands: - -```bash -# List manifests -secubox-app list - -# Inspect raw manifest -secubox-app show zigbee2mqtt - -# Install packages + run install action -secubox-app install zigbee2mqtt - -# Run status command (if defined) -secubox-app status zigbee2mqtt - -# Update or remove -secubox-app update zigbee2mqtt -secubox-app remove zigbee2mqtt -``` - -Environment variables: -- `SECUBOX_PLUGINS_DIR`: override manifest directory (default `../plugins`). - -The CLI relies on `opkg` and `jsonfilter`, so run it on the router (or within the OpenWrt SDK). It is idempotent: reinstalling an already-installed app simply confirms package state and reruns optional install hooks. - ---- - -## Future Integration - -- LuCI App Store page will consume the same manifest directory to render cards, filters, and install buttons. -- Wizards will read the `wizard.steps` metadata to present guided forms. -- Profiles can bundle manifests with specific network modes (e.g., DMZ + Zigbee2MQTT + Lyrion). - -For now, Zigbee2MQTT demonstrates the format. Additional manifests should follow the same schema to ensure the CLI and future UIs remain consistent. diff --git a/docs/embedded/docker-zigbee2mqtt.md b/docs/embedded/docker-zigbee2mqtt.md deleted file mode 100644 index 6e6af74..0000000 --- a/docs/embedded/docker-zigbee2mqtt.md +++ /dev/null @@ -1,115 +0,0 @@ -# Docker Zigbee2MQTT on OpenWrt ARM64 - -**Version:** 1.0.0 -**Last Updated:** 2025-12-28 -**Status:** Active - -This guide explains how to deploy Zigbee2MQTT on SecuBox (OpenWrt ARM64) using the new `secubox-app-zigbee2mqtt` package. The workflow follows upstream guidance from zigbee2mqtt.io while respecting OpenWrt storage constraints, UCI configuration, and procd supervision. - ---- - -## Prerequisites - -- OpenWrt 24.10.x (or newer) ARM64 build with SecuBox feeds. -- Internet connectivity to fetch Docker images. -- USB coordinator exposed as `/dev/ttyACM0` (e.g., Sonoff Zigbee 3.0 dongle). Load `kmod-usb-acm`. -- At least 200 MB free on overlay or external storage mounted at `/srv`. -- Cgroups v1/v2 enabled (verify `/sys/fs/cgroup` exists). Run `scripts/diagnose.sh` for sanity checks. - ---- - -## Installation Steps - -1. **Install the package:** - ```sh - opkg update - opkg install secubox-app-zigbee2mqtt - ``` - -2. **Bootstrap prerequisites (Docker, storage, config):** - ```sh - zigbee2mqttctl install - ``` - This command will: - - verify kernel modules, cgroups, USB device, and storage - - install `dockerd`, `docker`, `containerd`, and `kmod-usb-acm` - - create `/srv/zigbee2mqtt/data` with `configuration.yaml` - - pull `ghcr.io/koenkk/zigbee2mqtt:latest` - - enable `/etc/init.d/zigbee2mqtt` - -3. **Configure UCI (optional adjustments):** - ```sh - uci set zigbee2mqtt.main.serial_port='/dev/ttyACM0' - uci set zigbee2mqtt.main.mqtt_host='mqtt://192.168.8.10:1883' - uci set zigbee2mqtt.main.mqtt_username='secubox' - uci set zigbee2mqtt.main.mqtt_password='secret' - uci commit zigbee2mqtt - ``` - -4. **Start the service:** - ```sh - /etc/init.d/zigbee2mqtt start - ``` - The procd service executes `docker run` in foreground mode and respawns automatically. - -5. **Check logs and status:** - ```sh - zigbee2mqttctl status - zigbee2mqttctl logs -f - ``` - -6. **Upgrade to the latest image:** - ```sh - zigbee2mqttctl update - ``` - This pulls the latest container and restarts the service if enabled. - ---- - -## Files & Services - -| Path | Purpose | -|------|---------| -| `/etc/config/zigbee2mqtt` | UCI configuration (serial port, MQTT, base topic, frontend port, data path). | -| `/etc/init.d/zigbee2mqtt` | procd wrapper that invokes `zigbee2mqttctl service-run`. | -| `/usr/sbin/zigbee2mqttctl` | Management CLI for install/check/update/status/logs. | -| `/srv/zigbee2mqtt/data` | Persistent Zigbee2MQTT state (configuration.yaml, database). | - ---- - -## Troubleshooting - -| Symptom | Fix | -|---------|-----| -| `zigbee2mqttctl install` reports missing cgroups | Ensure `/sys/fs/cgroup` exists and cgroups are enabled in kernel config. | -| `/dev/ttyACM0` not found | Load `kmod-usb-acm` and reconnect the Zigbee dongle; verify with `ls -l /dev/ttyACM*`. | -| Docker fails to start due to low space | Move `/srv/zigbee2mqtt` to an external drive or free overlay space (`df -h`). | -| MQTT authentication errors | Update `mqtt_username`/`mqtt_password` via UCI and restart service. | -| Port conflict on 8080 | Change `frontend_port` in UCI, then `/etc/init.d/zigbee2mqtt restart`. | - -Run `scripts/diagnose.sh` for aggregated checks (storage, cgroups, firewall sanity). Use `scripts/smoke_test.sh` to quickly start/stop the Zigbee2MQTT service and verify Docker state. - ---- - -## Rollback / Uninstall - -1. Stop and disable the service: - ```sh - /etc/init.d/zigbee2mqtt stop - /etc/init.d/zigbee2mqtt disable - ``` -2. Remove the container image (optional): - ```sh - docker rm -f secbx-zigbee2mqtt 2>/dev/null - docker rmi ghcr.io/koenkk/zigbee2mqtt:latest - ``` -3. Remove package: - ```sh - opkg remove secubox-app-zigbee2mqtt - ``` -4. Clean data directory if no longer needed: - ```sh - rm -rf /srv/zigbee2mqtt - ``` - -Reinstall later by reinstalling the package and rerunning `zigbee2mqttctl install`. diff --git a/docs/embedded/domoticz-docker.md b/docs/embedded/domoticz-docker.md deleted file mode 100644 index 94d0b51..0000000 --- a/docs/embedded/domoticz-docker.md +++ /dev/null @@ -1,69 +0,0 @@ -# Domoticz on SecuBox (Docker) - -**Version:** 1.0.0 -**Last Updated:** 2025-12-28 -**Status:** Active - -This guide documents the Domoticz (home automation) “app” packaged as `secubox-app-domoticz` plus its manifest-driven wizard entry. - ---- - -## Installation - -```sh -opkg update -opkg install secubox-app-domoticz luci-app-vhost-manager -/domoticzctl install -/etc/init.d/domoticz start -``` - -Then open **SecuBox → Wizard → App Wizards → Domoticz** to set data/devices paths or custom ports. - ---- - -## UCI Config (`/etc/config/domoticz`) - -```uci -config domoticz 'main' - option enabled '1' - option image 'domoticz/domoticz:latest' - option data_path '/srv/domoticz' - option devices_path '/srv/devices' - option port '8080' - option timezone 'UTC' -``` - -Adjust via `uci` or the wizard: -```sh -uci set domoticz.main.port='8181' -uci commit domoticz -/etc/init.d/domoticz restart -``` - ---- - -## CLI Helper (`/usr/sbin/domoticzctl`) - -- `domoticzctl install` – checks Docker, prepares `/srv/domoticz`, pulls `domoticz/domoticz` image, enables service. -- `domoticzctl check` – rerun storage/cgroup/Docker validation. -- `domoticzctl update` – pull new image and restart if enabled. -- `domoticzctl status/logs` – interact with the Docker container. - ---- - -## VHost & Profiles - -- Use `scripts/vhostctl.sh add --domain ha.secubox.local --upstream http://127.0.0.1:` to publish the web UI via HTTPS. -- The manifest tags Domoticz for the **Gateway + DMZ** profile, ensuring DMZ isolation by default. - ---- - -## Troubleshooting - -| Issue | Fix | -|-------|-----| -| Container fails to start | Check `/srv/domoticz/config` permissions; ensure Docker is running. | -| No devices under `/srv/devices` | Mount your serial/Zigbee USB adapter and bind-mount it into the container as needed. | -| LuCI wizard fields empty | Confirm manifest at `/usr/share/secubox/plugins/domoticz/manifest.json` and rerun SecuBox wizard. | - -Domoticz now follows the same manifest-driven workflow as Lyrion/Zigbee2MQTT, paving the way for a full “SecuBox Apps Store.” diff --git a/docs/embedded/lxc-framework.md b/docs/embedded/lxc-framework.md deleted file mode 100644 index 2c5a9a4..0000000 --- a/docs/embedded/lxc-framework.md +++ /dev/null @@ -1,78 +0,0 @@ -# SecuBox LXC Framework (Preview) - -**Version:** 1.0.0 -**Last Updated:** 2025-12-28 -**Status:** Active - -This document captures the baseline LXC tooling added in Step 8. It is a foundation for future “SecuBox Apps” packaged as LXC containers (e.g., Lyrion) and explains the combined CLI/UCI workflow. - ---- - -## Components - -1. **UCI config:** `/etc/config/lxcapps` (one section per container). -2. **Storage root:** `/srv/lxc//` (rootfs, config, logs). -3. **Templates:** `/usr/share/secubox/lxc/templates/` (scripts/tarballs; default `debian`). -4. **CLI helper:** `secubox-tools/lxc/secubox-lxc` (install to `/usr/sbin/secubox-lxc`). - -`secubox-lxc` requires standard OpenWrt LXC packages (`lxc`, `lxc-templates`, `lxc-start`, etc.) and uses BusyBox-friendly syntax. - ---- - -## CLI Usage - -```bash -# List defined containers -secubox-lxc list - -# Create container using the debian template and attach to br-dmz -secubox-lxc create lyrion --bridge br-dmz --ip 192.168.50.10 - -# Start / stop lifecycle -secubox-lxc start lyrion -secubox-lxc stop lyrion - -# Show detailed config or status -secubox-lxc show lyrion -secubox-lxc status lyrion - -# Remove -secubox-lxc delete lyrion -``` - -`secubox-lxc create ` automatically creates a `config` section under `lxcapps.` capturing bridge/IP/memory metadata, so LuCI (future apps) can introspect containers in a consistent way. - ---- - -## UCI Schema (`/etc/config/lxcapps`) - -```uci -config container 'lyrion' - option bridge 'br-dmz' - option ip '192.168.50.10' - option gateway '192.168.50.1' - option dns '1.1.1.1' - option memory '1024' -``` - -This initial version does not yet tie into LuCI, but the schema is ready for future RPC endpoints and wizards (e.g., mapping profile entries to LXC containers). - ---- - -## Storage & Templates - -- Default rootfs path: `/srv/lxc//rootfs`. -- Template lookup order: CLI `--template` → `/usr/share/secubox/lxc/templates/` → fallback to system `lxc-create -t debian`. -- Bridge defaults to `br-lan`; pass `--bridge br-dmz` to isolate DMZ containers. - ---- - -## Next Steps - -This foundation enables the remaining roadmap items: - -- Expose `/etc/config/lxcapps` via `luci-app-secubox` RPC for integration with the App Store/wizard. -- Add profiles or manifests referencing specific LXC definitions (e.g., `type": "lxc"`). -- Ship ready-made templates (Lyrion, etc.) and document cgroup requirements alongside Docker apps. - -For now, use the CLI + UCI schema to experiment with LXC containers on OpenWrt ARM64 and validate storage/network assumptions. diff --git a/docs/embedded/lyrion-docker.md b/docs/embedded/lyrion-docker.md deleted file mode 100644 index be49332..0000000 --- a/docs/embedded/lyrion-docker.md +++ /dev/null @@ -1,81 +0,0 @@ -# Lyrion Media Server on SecuBox - -**Version:** 1.0.0 -**Last Updated:** 2025-12-28 -**Status:** Active - -This guide explains how to run [Lyrion Media Server](https://lyrion.org/) (formerly Jellyfin fork) inside Docker via the new `secubox-app-lyrion` package and SecuBox App Store manifest. - ---- - -## Installation Steps - -```sh -opkg update -opkg install secubox-app-lyrion luci-app-vhost-manager -lyrionctl install # checks Docker, prepares /srv/lyrion, pulls container -/etc/init.d/lyrion start -``` - -Then open **SecuBox → Wizard → App Wizards → Lyrion** to configure data/media paths and HTTP port. The manifest is stored in `/usr/share/secubox/plugins/lyrion/manifest.json` so `secubox-app list` will show it. - ---- - -## UCI Configuration (`/etc/config/lyrion`) - -```uci -config lyrion 'main' - option enabled '1' - option image 'ghcr.io/lyrion/lyrion:latest' - option data_path '/srv/lyrion' - option media_path '/srv/media' - option port '8096' - option timezone 'UTC' -``` - -Apply changes via LuCI wizard or CLI: -```sh -uci set lyrion.main.media_path='/srv/media' -uci commit lyrion -/etc/init.d/lyrion restart -``` - ---- - -## CLI Helper (`/usr/sbin/lyrionctl`) - -- `lyrionctl install` – ensures Docker packages, prepares data dir, pulls image, enables service. -- `lyrionctl check` – rerun prerequisite checks. -- `lyrionctl update` – pull latest image and restart if enabled. -- `lyrionctl status` / `lyrionctl logs [-f]`. -- `lyrionctl service-run` – invoked by procd; do not call manually. - -The Docker container exposes `http://:` (default 8096). Bind it via `luci-app-vhost-manager` to a public hostname if needed. - ---- - -## VHost Exposure - -After Lyrion is running, publish it through the VHost manager (or `scripts/vhostctl.sh`): -```sh -scripts/vhostctl.sh add \ - --domain media.secubox.local \ - --upstream http://127.0.0.1:8096 \ - --tls acme --websocket -scripts/vhostctl.sh reload -``` - -Combine with the **Gateway + DMZ** profile to place Lyrion inside a DMZ VLAN while still proxying the UI via HTTPS. - ---- - -## Troubleshooting - -| Symptom | Fix | -|---------|-----| -| `lyrionctl install` warns about `/srv/media` | Create/mount your media directory and rerun `lyrionctl install`. | -| Docker fails to start | Ensure `dockerd` is enabled; run `/etc/init.d/dockerd restart`. | -| Cannot reach UI | Check that port 8096 is free or adjust `option port`. | -| Media directory permissions | Bind-mount path with read permissions (`chmod -R 755`). | - -The manifest + wizard approach makes it easy to rebuild the container (via `secubox-app install lyrion`) while keeping UCI-driven defaults consistent across profiles. diff --git a/docs/embedded/vhost-manager.md b/docs/embedded/vhost-manager.md deleted file mode 100644 index 4117bbc..0000000 --- a/docs/embedded/vhost-manager.md +++ /dev/null @@ -1,115 +0,0 @@ -# VHost Manager & Reverse Proxy Notes - -**Version:** 1.0.0 -**Last Updated:** 2025-12-28 -**Status:** Active - -SecuBox ships `luci-app-vhost-manager` (LuCI dashboard + RPC backend) and now the `scripts/vhostctl.sh` helper so apps, wizards, and profiles can declaratively publish HTTP services behind nginx with optional TLS and HTTP auth. - ---- - -## Prerequisites - -1. **Packages**: `luci-app-vhost-manager` installed (installs RPCD script + LuCI UI) and nginx with SSL (`nginx-ssl`). -2. **Certificates**: ACME via `acme.sh` (auto) or manual PEM files for `tls manual`. -3. **Apps**: Ensure the upstream service listens on localhost or LAN (e.g., Zigbee2MQTT UI on `http://127.0.0.1:8080`). -4. **Firewall**: Allow inbound 80/443 on the WAN interface. - ---- - -## CLI (`scripts/vhostctl.sh`) - -This helper manipulates `/etc/config/vhosts` and can be invoked by future wizards/App Store installers. - -```sh -# List existing mappings -scripts/vhostctl.sh list - -# Add HTTPS reverse proxy for Zigbee2MQTT UI -scripts/vhostctl.sh add \ - --domain zigbee.home.lab \ - --upstream http://127.0.0.1:8080 \ - --tls acme \ - --websocket \ - --enable - -# Enable/disable or remove later -scripts/vhostctl.sh disable --domain zigbee.home.lab -scripts/vhostctl.sh remove --domain zigbee.home.lab - -# Reload nginx after edits -scripts/vhostctl.sh reload -``` - -Options: - -| Option | Purpose | -|--------|---------| -| `--domain` | Public hostname (required). | -| `--upstream` | Local service URL (`http://127.0.0.1:8080`). | -| `--tls off|acme|manual` | TLS strategy. Use `manual` + `--cert/--key` for custom certs. | -| `--auth-user/--auth-pass` | Enable HTTP basic auth. | -| `--websocket` | Add `Upgrade` headers for WebSocket apps. | -| `--enable` / `--disable` | Toggle without deleting. | - -The script is idempotent: running `add` with an existing domain updates the entry. - ---- - -## LuCI Dashboard - -Navigate to **Services → SecuBox → VHost Manager** to: -- View active/disabled vhosts, TLS status, certificate expirations. -- Edit or delete entries, request ACME certificates, tail access logs. -- Use the form to create entries (domain, upstream, TLS, auth, WebSocket). - -The LuCI backend writes to the same `/etc/config/vhosts` file, so changes from `vhostctl.sh` appear immediately. - ---- - -## Example: Publish Zigbee2MQTT - -1. Install Zigbee2MQTT (Docker) and confirm the UI listens on port 8080 (see `docs/embedded/zigbee2mqtt-docker.md`). -2. Map it behind HTTPS: - ```sh - scripts/vhostctl.sh add \ - --domain zigbee.secubox.local \ - --upstream http://127.0.0.1:8080 \ - --tls acme \ - --websocket - scripts/vhostctl.sh reload - ``` -3. (Optional) Use LuCI to request certificates and monitor logs. - ---- - -## DMZ Mode + VHost Workflow - -When enabling the new **Router + DMZ** network mode (admin → SecuBox → Network → Modes → DMZ): - -1. Assign `eth2` (or another physical port) as the DMZ interface and give it a subnet such as `192.168.50.1/24`. -2. Apply the mode; the backend creates a dedicated firewall zone (`dmz`) that only forwards to WAN. -3. Connect servers (e.g., Lyrion, Zigbee2MQTT UI) to the DMZ port so they can reach the internet but cannot reach the LAN. -4. Use `scripts/vhostctl.sh add ... --upstream http://192.168.50.10:32400` to expose the DMZ service through nginx with TLS. - -If something goes wrong, simply click **Rollback** in the Network Modes UI—the previous `/etc/config/network`, `/etc/config/firewall`, and `/etc/config/dhcp` are restored automatically thanks to the built-in backups. - ---- - -## Troubleshooting - -| Issue | Fix | -|-------|-----| -| `scripts/vhostctl.sh add ...` errors “Unknown option” | Ensure busybox `sh` is used (`/bin/sh`). | -| ACME cert missing | Confirm `acme.sh` installed, domain resolves to router, 80/443 reachable. | -| 502/504 errors | Check upstream service, firewall, or change `--upstream` to LAN IP. | -| TLS manual mode fails | Provide full paths to PEM files and verify permissions. | -| Changes not visible | Run `scripts/vhostctl.sh reload` or `ubus call luci.vhost-manager reload_nginx`. | - ---- - -## Automation Notes - -- Wizards/App Store can shell out to `scripts/vhostctl.sh` to register services as they are installed. -- Profiles can keep declarative manifests (domain → upstream) and call `vhostctl.sh add/remove` when switching modes. -- `/etc/config/vhosts` remains the single source of truth, consumed by the LuCI app and the RPC backend. diff --git a/docs/embedded/wizard-profiles.md b/docs/embedded/wizard-profiles.md deleted file mode 100644 index 7d6ec56..0000000 --- a/docs/embedded/wizard-profiles.md +++ /dev/null @@ -1,75 +0,0 @@ -# SecuBox Wizard & Profiles - -**Version:** 1.0.0 -**Last Updated:** 2025-12-28 -**Status:** Active - -The SecuBox hub now includes a guided setup wizard (LuCI → SecuBox → Wizard) and profile system. Use them to finish the first-run checklist, review app manifests, and apply predefined OS-like configurations (Home, Lab, Hardened, Gateway + DMZ). - ---- - -## First-Run Checklist - -The wizard queries `luci.secubox`’s `first_run_status` ubus method to determine whether critical items are configured: - -1. **Administrator password** – links to the LuCI password page. -2. **Timezone** – dropdown populated with common timezones; applying calls `apply_first_run` with `{ timezone: "Europe/Paris" }`. -3. **Storage path** – defaults to `/srv/secubox`; prepares the directory and stores it in `uci set secubox.main.storage_path`. -4. **Network mode** – uses the existing Network Modes RPC to switch between `router` and `dmz` presets. - -Each action can be run independently and is idempotent. - ---- - -## App Wizards (Manifests) - -Apps ship manifests under `/usr/share/secubox/plugins//manifest.json`. `secubox-app` (installed at `/usr/sbin/secubox-app`) uses the same manifests for CLI installs, and the wizard consumes the `wizard.fields` section to build forms. Example snippet: - -```json -{ - "id": "zigbee2mqtt", - "wizard": { - "uci": { "config": "zigbee2mqtt", "section": "main" }, - "fields": [ - { "id": "serial_port", "label": "Serial Port", "uci_option": "serial_port" }, - { "id": "mqtt_host", "label": "MQTT Host", "uci_option": "mqtt_host" } - ] - } -} -``` - -Clicking “Configure” opens a modal that writes the provided values into the specified UCI section. - ---- - -## Profiles - -Profiles are stored as JSON in `/usr/share/secubox/profiles/` and can bundle: - -- `network_mode`: target SecuBox network mode (`router`, `dmz`, …) -- `apps`: manifest IDs to install via `secubox-app install ` -- `packages`: additional packages to ensure via opkg/apk -- `uci`: array of `{config, section, option, value}` entries applied via UCI - -Baseline profiles: - -| ID | Description | Highlights | -|----|-------------|------------| -| `home` | Home router + Zigbee2MQTT | Router mode, installs Zigbee2MQTT + Netdata | -| `lab` | Monitoring lab | Router mode, ensures Netifyd & Bandwidth Manager | -| `hardened` | Security-focused | Enables CrowdSec + Client Guardian | -| `gateway_dmz` | Router + DMZ segment | Switches to DMZ mode and enables VHost manager | -| `lxc_base` | (Upcoming) baseline LXC container | Reserved for future `secubox-lxc` integrations | - -`apply_profile` automatically tars `/etc/config` to `/etc/secubox-profiles/backups/` before modifying settings, so the **Rollback last profile** button (or `rollback_profile` RPC) instantly restores prior UCI files. - ---- - -## CLI References - -- `secubox-app list|install|status` – manage app manifests (installed by `luci-app-secubox`). -- `ubus call luci.secubox list_profiles` – enumerate available profile manifests. -- `ubus call luci.secubox apply_profile '{"profile_id":"home"}'` – apply a preset programmatically. -- `secubox-app` respects `SECUBOX_PLUGINS_DIR` if you need to point to custom manifest trees. - -Combine the wizard UI with these commands to automate deployments or build higher-level orchestration (e.g., App Store pages, onboarding scripts). diff --git a/docs/embedded/zigbee2mqtt-docker.md b/docs/embedded/zigbee2mqtt-docker.md deleted file mode 100644 index 69d6af9..0000000 --- a/docs/embedded/zigbee2mqtt-docker.md +++ /dev/null @@ -1,128 +0,0 @@ -# Docker Zigbee2MQTT on OpenWrt ARM64 - -**Version:** 1.0.0 -**Last Updated:** 2025-12-28 -**Status:** Active - -This guide explains how to deploy the SecuBox Zigbee2MQTT “app” (Docker-based) on OpenWrt ARM64 targets. It uses the `secubox-app-zigbee2mqtt` package (installer, CLI, procd service) together with the LuCI frontend (`luci-app-zigbee2mqtt`). - ---- - -## Prerequisites - -1. **OpenWrt 24.10.x ARM64** (ESPRESSObin, MOCHAbin, RPi4, etc.) with ≥ 256 MB free storage (Docker image + data dir). -2. **Kernel features**: cgroups (`/sys/fs/cgroup`), USB CDC ACM (`kmod-usb-acm`). -3. **Hardware**: Zigbee coordinator presented as `/dev/ttyACM0` (e.g., SONOFF ZBDongle-E/MG21). -4. **Network**: Reachable MQTT broker (local Mosquitto or remote `mqtt://host:1883`). -5. **Package feeds**: `docker`, `dockerd`, `containerd` available (`opkg update`). - ---- - -## Installation Steps - -```sh -opkg update -opkg install secubox-app-zigbee2mqtt luci-app-zigbee2mqtt -``` - -1. **Run prerequisite installer** (checks storage, cgroups, USB, installs Docker, pulls image, enables service): - ```sh - zigbee2mqttctl install - ``` -2. **Start the service**: - ```sh - /etc/init.d/zigbee2mqtt start # enable automatically via installer - ``` -3. **LuCI configuration** (optional UI flow): Services → SecuBox → Zigbee2MQTT. Adjust serial port, MQTT host/credentials, base topics, etc., then click “Apply”. - -The installer writes persistent data under `/srv/zigbee2mqtt/data` (config + DB) and exposes the Zigbee2MQTT web UI on port `8080` by default. - ---- - -## Command-Line Reference (`/usr/sbin/zigbee2mqttctl`) - -| Command | Description | -|---------|-------------| -| `install` | Full prerequisite setup (Docker packages, data dir, image pull, enable service). | -| `check` | Rerun prerequisite checks (storage, cgroups, USB module, serial device). | -| `update` | Pull the latest Zigbee2MQTT image and restart the enabled service. | -| `status` | Show Docker container status (`docker ps` filter). | -| `logs [-f]` | Stream Docker logs for the container. | -| `service-run` / `service-stop` | Internal commands used by the procd init script; not for manual invocation. | - -All commands must be run as root. - ---- - -## UCI Configuration (`/etc/config/zigbee2mqtt`) - -```uci -config zigbee2mqtt 'main' - option enabled '1' - option serial_port '/dev/ttyACM0' - option mqtt_host 'mqtt://127.0.0.1:1883' - option mqtt_username '' - option mqtt_password '' - option base_topic 'zigbee2mqtt' - option frontend_port '8080' - option channel '11' - option image 'ghcr.io/koenkk/zigbee2mqtt:latest' - option data_path '/srv/zigbee2mqtt' - option timezone 'UTC' -``` - -Edit via `uci` or the LuCI form; commit changes to restart automatically: -```sh -uci set zigbee2mqtt.main.mqtt_host='mqtt://192.168.1.10:1883' -uci commit zigbee2mqtt -/etc/init.d/zigbee2mqtt restart -``` - ---- - -## Validation & Smoke Tests - -- Quick prerequisite check: - ```sh - zigbee2mqttctl check - ``` -- Repository smoke test (runs service start/stop + optional MQTT pub/sub): - ```sh - ./scripts/smoke_test.sh - ``` -- Diagnostics bundle (general SecuBox): - ```sh - ./scripts/diagnose.sh - ``` - ---- - -## Troubleshooting - -| Symptom | Resolution | -|---------|------------| -| `zigbee2mqttctl install` reports “/sys/fs/cgroup missing” | Enable cgroups in kernel config or upgrade to a build with cgroup support. | -| USB coordinator not detected | Ensure `kmod-usb-acm` is installed, `cdc_acm` module loaded (`lsmod | grep cdc_acm`), and device appears under `/dev/ttyACM*`. Replug the dongle. | -| Docker not starting | Check `/etc/init.d/dockerd status`. If `docker info` fails, inspect `/var/log/messages` for storage driver errors. | -| MQTT authentication failures | Set `mqtt_username`/`mqtt_password` via UCI or LuCI and restart the service. | -| Port 8080 already used | Change `frontend_port` in UCI, commit, restart service. Update vhost mappings accordingly. | - ---- - -## Uninstall / Cleanup - -```sh -/etc/init.d/zigbee2mqtt stop -/etc/init.d/zigbee2mqtt disable -docker rm -f secbx-zigbee2mqtt 2>/dev/null -opkg remove luci-app-zigbee2mqtt secubox-app-zigbee2mqtt -rm -rf /srv/zigbee2mqtt -``` - ---- - -## Next Steps - -- Use `luci-app-vhost-manager` to publish the Zigbee2MQTT UI under HTTPS (see `luci-app-vhost-manager/README.md`). -- Integrate with the forthcoming SecuBox App Store by adding a manifest entry referencing this installer. -- Combine with profiles/wizards once those components are introduced per the project roadmap. diff --git a/docs/quick-start.md b/docs/quick-start.md index d83cf24..063e735 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -167,6 +167,41 @@ ssh root@192.168.8.191 "chmod 644 /www/luci-static/resources/**/*.css" ssh root@192.168.8.191 "rm -f /tmp/luci-indexcache /tmp/luci-modulecache/* && /etc/init.d/rpcd restart && /etc/init.d/uhttpd restart" ``` +### Quick Deploy Helper +```bash +# IPK install via opkg (auto SCP + install) +./secubox-tools/quick-deploy.sh --ipk bin/packages/luci-app-secubox.ipk + +# APK install on newer images +./secubox-tools/quick-deploy.sh --apk dist/secubox-theme.apk + +# Push local source directory to /www/luci-static +./secubox-tools/quick-deploy.sh --src luci-app-secubox/htdocs --target-path /www/luci-static + +# Clone Git repo and deploy (branch optional) +./secubox-tools/quick-deploy.sh --git https://github.com/CyberMindStudio/secubox-theme.git --branch main + +# Selective push (only CSS + Settings view) +./secubox-tools/quick-deploy.sh --src luci-app-secubox/htdocs \ + --include luci-static/resources/secubox/secubox.css \ + --include luci-static/resources/view/secubox/settings.js + +# Root tree updates (rpcd, ACLs, etc.) +./secubox-tools/quick-deploy.sh --src luci-app-secubox/root --force-root + +# Legacy theme profile (mirrors deploy-theme-system.sh) +./secubox-tools/quick-deploy.sh --profile theme + +# Deploy complete LuCI app (root + htdocs) +./secubox-tools/quick-deploy.sh --profile luci-app --src luci-app-secubox + +# Browse LuCI apps and auto-pick one +./secubox-tools/quick-deploy.sh --list-apps +./secubox-tools/quick-deploy.sh --app secubox +./secubox-tools/quick-deploy.sh --src-select # interactive picker (TTY only) +``` +*Flags:* `--include` limits uploads, `--force-root` writes relative to `/`, `--profile` triggers opinionated bundles (`theme`, `luci-app`), `--app ` auto-resolves `luci-app-`, `--list-apps` prints detected apps, `--src-select` shows the same picker interactively, `--no-auto-profile` disables automatic LuCI detection when using `--src`, `--no-cache-bust` skips clearing `/tmp/luci-*`, `--no-verify` disables post-copy checksum checks, `--router root@192.168.8.191` overrides the target, and `--post "rm -rf /tmp/luci-*"` runs extra remote commands. Environment variables `ROUTER`, `TARGET_PATH`, `CACHE_BUST`, `VERIFY`, `SSH_OPTS`, and `SCP_OPTS` can be exported ahead of time. + ### Debug ```bash # Test RPCD