MicroNAS/CLAUDE.md

CLAUDE.md

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. It manages SMB shares, NFS exports, and quotas by editing host config files and reloading the daemons. Home/LAN use only.

Files

• app.py — Flask backend (API + share/export/quota logic).
• index.html — Bootstrap single-page UI.
• docker-compose.yml — optional dev/test sandbox only.
• PLANNING.md — roadmap and feature list.

How it runs (target)

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), so it must run on the host. Docker stays only as a test sandbox.

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.
  • All routes require auth (single-user HTTP Basic Auth from an env var).
• Config edits must be safe: parse into blocks and rewrite whole files for edit/delete — do not blindly append.
• LAN-only. Do not add internet-facing features.

Out of scope

Backups (handled by 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.