Initial commit: MicroNAS share manager (Phase 1)

PLANNING.md

@@ -0,0 +1,96 @@
+# Fileshare Web — Planning
+
+A lightweight web GUI to manage file shares on a single home server — like a
+minimal NAS control panel for a Proxmox LXC/VM. Manages **SMB shares**,
+**NFS exports**, and **quotas** by editing the host config files and reloading
+the daemons.
+
+**Design principle: keep it small.** Single box, home/LAN use only, no database,
+no auth framework, dependency-light. If a feature needs heavy machinery, it's
+out of scope.
+
+---
+
+## Deployment decision
+
+Run **directly on the LXC/VM as a `systemd` service** (Flask behind `gunicorn`).
+**Not** Docker.
+
+Reason: this app's whole job is to manipulate *host* services (`smbd`, `nfsd`,
+`/etc/exports`, `exportfs`, `setquota`). Containerizing it means bind-mounting
+host config, running privileged, and fighting the kernel NFS server — all the
+downsides of running on the host with none of the isolation benefit. Docker is
+kept only as an optional dev/test sandbox.
+
+**Network:** LAN-only. Never expose to the internet. Reach it via local network
+or Tailscale. Auth is a safety net, not an internet-facing defense.
+
+**Backups:** Out of scope. Handled at the Proxmox layer (Proxmox Backup Server
+on a second client). This app does not implement backup.
+
+---
+
+## Current state (baseline)
+
+- `app.py` — Flask API: list/create SMB & NFS shares, set quotas.
+- `index.html` — Bootstrap UI with SMB / NFS / Quotas tabs.
+- `docker-compose.yml` — test sandbox.
+
+### Known issues to fix
+- `parse_smb()` is called (`app.py:13`) but never defined → `/api/shares` 500s.
+- `subprocess.run(cmd, shell=True)` with f-string input (`app.py:82`) → command
+  injection as root.
+- `add_smb_share` writes raw user input into `smb.conf` → config injection via
+  newlines.
+- No authentication on any route.
+- Config is append-only (`open(..., 'a')`) → no working delete/edit; UI Delete
+  buttons are wired to nothing.
+- No input validation on names or paths (path traversal, share of `/`).
+
+---
+
+## Roadmap
+
+### Phase 1 — Correctness & safety (must-have)
+- [ ] Implement `parse_smb()` so `/api/shares` works.
+- [ ] Remove all `shell=True`; use argument-list `subprocess` calls.
+- [ ] Validate input:
+  - share/user names: `^[A-Za-z0-9_-]+$`
+  - paths must resolve under `/srv`
+  - reject anything else with a clear error.
+- [ ] Simple login: HTTP Basic Auth, single user + password from env var,
+      protecting all routes.
+- [ ] `systemd` unit + `gunicorn`, plus README run instructions.
+
+### Phase 2 — Dashboard & health (the main goal)
+A landing page that shows the state of the server at a glance:
+- [ ] **Daemon status** — is `smbd` running? is `nfsd` running? (green/red).
+- [ ] **Disk usage** — free / used / total for `/srv` (and per-disk if simple).
+- [ ] **All shares in one view** — every SMB share and NFS export, their paths,
+      and who can access them.
+- [ ] **Per-share data used** — size on disk of each share's path (`du`).
+- [ ] **Quota usage** — for each user with a quota: used vs limit, with a
+      progress bar (e.g. "12 GB / 50 GB").
+- [ ] Auto-refresh or a manual refresh button.
+
+### Phase 3 — Full management (complete the CRUD)
+- [ ] Working **delete** for SMB & NFS (parse config into blocks, rewrite the
+      whole file — not append-only).
+- [ ] **Edit** existing shares.
+- [ ] Enable/disable a share without deleting it.
+
+### Phase 4 — Nice-to-have
+- [ ] **WebDAV** support. Preferred approach: don't build it in Flask — have the
+      app drop an Apache/nginx WebDAV config snippet, same pattern as SMB/NFS,
+      so it reuses the existing architecture.
+- [ ] Simple in-browser file browser for `/srv`.
+- [ ] Toast notifications instead of `alert()`.
+
+---
+
+## Out of scope (intentionally)
+- Backups (Proxmox Backup Server handles this).
+- Multi-user accounts / roles (single admin login is enough).
+- Database (config files are the source of truth).
+- Internet exposure / TLS termination (LAN + Tailscale only).
+- Clustering / multi-host management.