v1: cleanup, dead code removal, docs update

app.py:
- Move warnings import to top-level imports
- Remove MICRONAS_SECRET env var (undocumented, unnecessary)
- Inline secret key derivation cleanly

CLAUDE.md:
- Remove stale quotas mention
- Add WebDAV, setup.html, favicon to file layout
- Document /etc/micronas/ permissions requirements
- Document <Location> vs <Directory> for WebDAV DAV On

PLANNING.md:
- Mark Phase 5 complete with all shipped items
- Add v1 complete marker and future ideas section

README.md:
- Simplify dev/test section (remove complex hash snippet)
- Fix double blank line

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
marcandClaude Sonnet 4.6 committed 2026-06-20 19:20:24 +02:00
1 parent c992e3f1d1
commit 9f060660a1
4 files changed
+50 -43

No files matched your search

+23 -25
View File
@@ -5,48 +5,46 @@ Project context for Claude Code. See `PLANNING.md` for the full roadmap.
## What this is
A lightweight web GUI to manage file shares on a single home server (Proxmox
LXC/VM) — a minimal NAS control panel. Manages **SMB shares**, **NFS exports**,
**quotas**, and **system users** by editing host config files and reloading
**WebDAV shares**, and **system users** by editing host config files and reloading
daemons. Home/LAN use only.
## File layout
- `app.py` — Flask backend: all API routes, auth, business logic.
- `templates/index.html` — main SPA shell (Jinja2); no inline JS or CSS.
- `templates/login.html` — login form.
- `templates/setup.html` — first-time setup form (shown when no credentials exist).
- `static/css/app.css` — custom dark theme (GitHub-palette CSS variables).
- `static/img/favicon.svg` — app icon (drive bays with green LEDs).
- `static/js/utils.js` — shared helpers: `esc()`, `showToast()`, `apiFetch()`.
- `static/js/dashboard.js` — dashboard: status, IPs, shares, active connections, restart buttons.
- `static/js/shares.js` — SMB/NFS CRUD (create, edit, delete, toggle). Edit modal is async (fetches users+groups for dropdowns).
- `static/js/users.js` — user CRUD + password modal + group management (loadGroups, createGroup, addMember, removeMember). Caches user list in `_cachedUsers` for group table.
- `static/js/main.js` — page init and 30 s auto-refresh (calls loadDashboard, loadShares, loadUsers, loadGroups).
- `micronas.service` — systemd unit (gunicorn, reads `/etc/micronas.env`).
- `static/js/dashboard.js` — status dots, IPs, shares overview, active SMB connections, restart buttons.
- `static/js/shares.js` — SMB/NFS/WebDAV CRUD. Edit modal is async (fetches users+groups for dropdowns).
- `static/js/users.js` — user CRUD + password modal + group management + admin credential change modal.
- `static/js/main.js` — page init and 30 s auto-refresh.
- `micronas.service` — systemd unit (gunicorn `-w 1`, reads `/etc/micronas/micronas.env`).
## How it runs
Directly on the LXC/VM as a `systemd` service, Flask behind `gunicorn`.
**Not** in Docker for production — the app manipulates host services
(`smbd`, `nfsd`, `/etc/exports`, `exportfs`, `setquota`).
Directly on the LXC/VM as a `systemd` service, Flask behind `gunicorn -w 1`.
Single worker is required — credential updates mutate `_creds` in-process.
**Not** in Docker for production — the app manipulates host services directly.
Auth uses **Flask sessions** with a secret key derived from `MICRONAS_PASS`.
Credentials come from `/etc/micronas.env` (`MICRONAS_USER`, `MICRONAS_PASS`).
Auth uses **Flask sessions**. Credentials stored hashed (PBKDF2-HMAC-SHA256)
in `/etc/micronas/micronas.env`. First run redirects to `/setup`.
WebDAV htpasswd at `/etc/micronas/webdav.passwd` (group `www-data`, mode 640).
Config directory `/etc/micronas/` must be mode 750, owned `root:www-data`.
## Conventions & constraints
- **Keep it simple.** No database, no auth framework, dependency-light.
Config files (`/etc/samba/smb.conf`, `/etc/exports`) are the source of truth.
- **Security basics are non-negotiable even for home use:**
- Never use `subprocess.run(..., shell=True)` with user input. Use argument
lists.
- Validate all input: names `^[A-Za-z0-9_-]+$`; paths must resolve under
`/srv`.
- Never use `subprocess.run(..., shell=True)` with user input. Use argument lists.
- Validate all input: names `^[A-Za-z0-9_-]+$`; paths must resolve under `/srv`.
- All routes require a valid session (`require_auth` decorator).
- **Config edits are safe:** `_parse_smb_conf()` / `_write_smb_conf()` and
`_parse_exports()` / `_write_exports()` parse into blocks and rewrite the
whole file — never blindly append for edit/delete/toggle operations.
- **Config edits are safe:** parse into blocks, rewrite whole file — never
blindly append for edit/delete/toggle operations.
- WebDAV config uses `<Location>` blocks for `DAV On` (not `<Directory>`) —
required for Alias-mapped paths in Apache 2.4.
- LAN-only. Do not add internet-facing features.
## Out of scope
Backups (Proxmox Backup Server), multi-user roles, databases, internet exposure,
multi-host management.
## Working agreement
- Work in the phases defined in `PLANNING.md`; pause after each phase for the
user to test.
- Explain changes briefly. Don't add heavy dependencies without asking.
Backups, multi-user roles, databases, internet exposure, multi-host management,
disk quotas (ZFS-backed LXC doesn't support `setquota`).