Add GitHub Pages documentation site
This commit is contained in:
parent
2000265646
commit
7b043850fe
@ -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.<module>`), 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/<module>`. 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/<name>` 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.
|
||||
@ -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/<pkg>.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:
|
||||
|
||||
@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -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/<app>/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 <id>`). |
|
||||
| `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.
|
||||
@ -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`.
|
||||
@ -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:<port>` 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.”
|
||||
@ -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/<name>/` (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 <name>` automatically creates a `config` section under `lxcapps.<name>` 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/<name>/rootfs`.
|
||||
- Template lookup order: CLI `--template` → `/usr/share/secubox/lxc/templates/<name>` → 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.
|
||||
@ -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://<router>:<port>` (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.
|
||||
@ -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.
|
||||
@ -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/<id>/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 <id>`
|
||||
- `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).
|
||||
@ -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.
|
||||
@ -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 <name>` auto-resolves `luci-app-<name>`, `--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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user