88 lines
4.5 KiB
Markdown
88 lines
4.5 KiB
Markdown
# Workflows
|
||
|
||
## Setup
|
||
1. **Normalize permissions**
|
||
```bash
|
||
./secubox-tools/fix-permissions.sh --local
|
||
```
|
||
2. **Install git hooks** (pre-push validator)
|
||
```bash
|
||
./secubox-tools/install-git-hooks.sh
|
||
```
|
||
3. **Run the baseline validation** (7 checks)
|
||
```bash
|
||
./secubox-tools/validate-modules.sh
|
||
```
|
||
4. **Cache the SDK and validate via local-build**
|
||
```bash
|
||
./secubox-tools/local-build.sh validate
|
||
```
|
||
5. **Inspect module status & docs** using `DOCUMENTATION-INDEX.md`, `MODULE_STATUS.md`, and each module’s README before editing.
|
||
|
||
## Build Packages
|
||
- **Single module via SDK**
|
||
```bash
|
||
make package/luci-app-<module>/compile V=s
|
||
```
|
||
- **Local CI-equivalent build**
|
||
```bash
|
||
./secubox-tools/local-build.sh build luci-app-<module>
|
||
# or build all architectures
|
||
./secubox-tools/local-build.sh build
|
||
```
|
||
- **Firmware images** (preload SecuBox packages)
|
||
```bash
|
||
./secubox-tools/local-build.sh build-firmware mochabin
|
||
```
|
||
|
||
## Run / Validate on a Device
|
||
1. Copy the package or run the standardized deploy script:
|
||
```bash
|
||
ROUTER=root@192.168.8.191 ./deploy-module-template.sh system-hub
|
||
# For other modules: replace system-hub, script backs up, copies JS/CSS/RPCD/menu/ACL, fixes perms, clears cache, restarts rpcd/uhttpd.
|
||
```
|
||
2. Fix remote permissions & restart services (safety net):
|
||
```bash
|
||
./secubox-tools/fix-permissions.sh --remote root@192.168.8.191
|
||
```
|
||
3. Functional smoke tests:
|
||
```bash
|
||
ssh root@router "ubus list | grep luci.<module>"
|
||
ssh root@router "ubus call luci.<module> status"
|
||
ssh root@router "/etc/init.d/rpcd restart && /etc/init.d/uhttpd restart"
|
||
```
|
||
4. Clear LuCI cache if manual copy: `rm -f /tmp/luci-indexcache /tmp/luci-modulecache/*`.
|
||
|
||
## Linting & Formatting
|
||
- JSON: `jsonlint root/usr/share/luci/menu.d/*.json root/usr/share/rpcd/acl.d/*.json`
|
||
- Shell scripts: `shellcheck root/usr/libexec/rpcd/* secubox-tools/*.sh`
|
||
- Ubux objects: `./secubox-tools/validate-module-generation.sh luci-app-<module>`
|
||
|
||
## CI Overview
|
||
- **build-openwrt-packages.yml** – Multi-arch SDK builds (.ipk/.apk) triggered on push/PR/tags/workflow_dispatch.
|
||
- **test-validate.yml** – Runs validation scripts, shellcheck, JSON lint.
|
||
- **build-secubox-images.yml** – Builds firmware images per device profile.
|
||
Use `Actions > Run workflow` with inputs (package name, OpenWrt version, architectures) to trigger manual builds.
|
||
|
||
## Release & Deploy
|
||
1. **Tag release**
|
||
```bash
|
||
git tag -a v1.x.y -m "Release notes"
|
||
git push origin v1.x.y
|
||
```
|
||
2. **Use deploy modules script** for router installs; for combined releases, run `deploy-system-hub.sh`, `deploy-secubox-dashboard.sh`, or other `deploy-*.sh` wrappers which copy relevant files, call `fix-permissions`, clear caches, and restart services.
|
||
3. **Post-deploy validation**: `ubus list`, `logread | grep -i error`, open the LuCI tab in a private browser window to bypass cache.
|
||
4. **Rollback plan**: `deploy-module-template.sh` creates backups under `/root/luci-backups/<timestamp>`; restore manually via `scp` if needed.
|
||
|
||
## Debugging Cookbook (Top Issues)
|
||
1. **HTTP 404 for view** – Menu path mismatch; fix `root/usr/share/luci/menu.d/*.json` to match `htdocs/.../view/<module>/<view>.js`, redeploy, flush LuCI cache.
|
||
2. **RPC -32000 Object not found** – RPCD script name or permissions wrong; rename to `luci.<module>`, ensure 755, restart `rpcd`.
|
||
3. **403 on CSS/JS** – File deployed with 600/700 perms; run `./secubox-tools/fix-permissions.sh --remote` targeting the router.
|
||
4. **Design regression** – Missing CSS variables or dark mode selectors; re-import `system-hub/common.css`, replace hardcoded colors with `var(--sh-*)`, add `[data-theme="dark"]` overrides.
|
||
5. **Menu not showing** – ACL missing the module or dependencies unsatisfied; update ACL JSON and confirm `depends.acl` in menu entry includes your package.
|
||
6. **Build fails in CI** – Run `./secubox-tools/local-build.sh full` locally; check for missing Makefile fields or JSON syntax errors.
|
||
7. **ubus returns malformed JSON** – Ensure RPCD handlers call `json_init`, `json_add_*`, `json_dump` for every branch.
|
||
8. **LuCI JS error “factory yields invalid constructor”** – API modules must export `baseclass.extend`, not plain objects; instantiate via `.new()` in views when necessary.
|
||
9. **Device storage full** – Pre-deploy check `df -h | grep overlay`; remove `/tmp/*.ipk` or `/root/luci-backups/*` as suggested in `QUICK-START.md`.
|
||
10. **Permissions drift after manual SCP** – Always run `./secubox-tools/fix-permissions.sh --remote <router>` after copying files outside the deploy scripts.
|