MicroNAS/PLANNING.md

MicroNAS — 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.

---

Project structure

MicroNAS/
├── app.py                  Flask backend (all API routes + business logic)
├── templates/
│   ├── index.html          Main SPA shell (Jinja2, no inline JS/CSS)
│   └── login.html          Login form
├── static/
│   ├── css/app.css         Custom dark theme (GitHub-palette CSS vars)
│   └── js/
│       ├── utils.js        esc(), showToast(), apiFetch()
│       ├── dashboard.js    loadDashboard()
│       ├── shares.js       SMB/NFS CRUD + edit/delete/toggle
│       ├── users.js        User CRUD + password modal
│       └── main.js         Init + auto-refresh countdown
├── micronas.service        systemd unit
├── README.md
└── PLANNING.md

---

Roadmap

Phase 1 — Correctness & safety ✅

• Implement parse_smb() so /api/shares works.
• Remove all shell=True; use argument-list subprocess calls.
• Validate input: names ^[A-Za-z0-9_-]+$; paths must resolve under /srv.
• Session-based login (custom /login page, Flask sessions, secret key derived from MICRONAS_PASS).
• systemd unit + gunicorn + README install guide.

Phase 2 — Dashboard & health ✅

• Daemon status — smbd / nfsd running? (green/red dot).
• Disk usage — free / used / total for /srv with progress bar.
• All shares in one view — SMB + NFS, paths, access, size on disk.
• Per-share data used — du -sb per share path.
• Auto-refresh every 30 s + manual refresh button.

Phase 2.5 — UX improvements ✅

• UI redesign — GitHub-dark palette, custom CSS vars, better contrast and typography.
• Toast notifications — replaced all alert().
• Frontend split into templates/ + static/css/ + static/js/.
• User management tab — list users (uid ≥ 1000), create, delete, change SMB password.
• Login page — replaces browser Basic Auth dialog.

Phase 3 — Full share management ✅

• Working delete for SMB & NFS (parse config into sections, rewrite whole file — not append-only).
• Edit existing shares — name, path, valid users (SMB); clients, ro/rw (NFS). Edit modal pre-filled with current values.
• Enable/disable a share without deleting it — SMB uses available = no; NFS comments out the export line.
• Status indicator per share row (green/red dot, reduced opacity when disabled).

Phase 4 — Nice-to-have

• WebDAV support. Preferred approach: drop an Apache/nginx config snippet — don't build it in Flask.
• Simple in-browser file browser for /srv.
• Auto-create share directory on add (with correct owner/permissions).

---

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.
• Disk quotas — removed. Linux setquota/repquota require quota support on the filesystem. The target deployment uses a ZFS-backed Proxmox LXC where this is unavailable inside the container. Per-dataset limits can be set from the Proxmox host with zfs set quota=.