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 3.5 — Share & dashboard polish ✅

• Permission editor in edit modal — owner, group, chmod mode per share folder. Owner/Group are dropdowns from live system users/groups.
• Group management — create/delete groups, add/remove members. Users tab.
• SMB extra settings — force user, force group, guest ok, read only, recycle bin (vfs objects = recycle, files go to .recycle inside share).
• NFS extra settings — no_root_squash, all_squash toggles.
• Server IPs on dashboard — shows all non-loopback IPv4 addresses.
• Service restart buttons — restart smbd / nfsd from the dashboard.
• Active SMB connections — live table on dashboard via smbstatus.
• Delete confirmation modal — replaces browser confirm().
• Auto-refresh countdown — 30 s timer with live seconds display.

Phase 4 — WebDAV ✅

• Apache mod_dav + mod_dav_fs managed by MicroNAS. Config written to /etc/apache2/conf-available/micronas-webdav.conf with BEGIN/END markers per share; a2enconf + systemctl reload apache2.
• Shares served at http://<server>/dav/<name> (Apache on port 80).
• Auth via htpasswd (/etc/micronas-webdav.passwd) — passwords synced automatically when creating/changing user passwords in the Users tab.
• Full CRUD: create, edit (name/path/users/permissions), delete.
• Dashboard: apache2 status dot + restart button.
• WebDAV badge in dashboard shares overview.
• @groupname fix in SMB valid users (was incorrectly rejected by VALID_NAME).

Phase 5 — Security & UX ✅

• PBKDF2 password hashing — admin credentials stored hashed (SHA-256, 260k iterations, salt$hex) in /etc/micronas/micronas.env. Legacy plaintext still accepted for migration.
• First-login setup page — /setup route shown on fresh install, no manual env editing needed.
• Admin credential change — ⚙ Settings modal in topbar; requires current password, logs out after change.
• Config directory — /etc/micronas/ with correct ownership (root:www-data, mode 750) auto-created by code.
• WebDAV browser access — Options Indexes + <Location> blocks for DAV On; directories browsable in browser.
• Favicon & logo — SVG drive-bay icon, shown in browser tab and topbar.
• www-data in owner dropdown — selectable as folder owner for WebDAV shares.

---

v1 complete 🎉

All planned phases shipped. The app manages SMB, NFS, and WebDAV shares with a dark-themed web UI, secure hashed credentials, auto-synced WebDAV passwords, group management, dashboard with live status, and a favicon.

Possible future additions

• Simple in-browser file browser for /srv.
• Auto-create share directory on add (with correct owner/permissions).
• HTTPS via Let's Encrypt / self-signed cert.

---

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=.