pirate-station/.planning/PROJECT.md

Pirate Station

What This Is

A self-hosted file server for Raspberry Pi, exposed to the internet via frpc/rathole. Provides a polished web UI for a small group of trusted users to upload, download, and manage files in a shared space. Account management happens exclusively through a CLI tool on the Pi.

Core Value

Users can securely access and manage files on the Pi from anywhere via the web, with the server completely isolated to its designated storage directory.

Requirements

Validated

(None yet — ship to validate)

Active

• CLI tool for account management (create/delete users, change passwords)
• User authentication with hashed passwords and JWT sessions
• Web login interface
• File browser with folder navigation
• File upload (including drag-and-drop)
• File download
• File deletion
• Folder creation and deletion
• File and folder renaming
• Modern, polished responsive web UI
• Docker container isolated to mounted volume only

Out of Scope

• Self-registration — admin creates accounts via CLI only
• Web-based admin panel — all user management via CLI
• File preview/streaming — just upload, download, manage
• Per-user private folders — shared space model
• Tailscale integration — using frpc/rathole instead
• Mobile app — web-only

Context

• Deployment: Raspberry Pi at home, exposed via frpc/rathole tunnel
• Users: Small trusted group (family/friends), each with individual accounts
• File access: Shared space, everyone sees all files
• Isolation requirement: Docker container must only affect the mounted directory, never touch anything else on the Pi

Constraints

• Platform: Raspberry Pi — lightweight, low memory footprint required
• Stack: Go backend — small binary, efficient for Pi's resources
• Containerization: Docker — must run fully isolated with volume mount
• Network: Works behind frpc/rathole tunnel (not Tailscale)
• Security: Internet-exposed, so authentication must be solid (no plain passwords)

Key Decisions

Decision	Rationale	Outcome
Go backend	Lightweight for Pi, single binary, good HTTP handling	— Pending
CLI-only user management	Simpler, more secure (no web admin surface)	— Pending
Shared file space	Simpler than per-user isolation, trusted group	— Pending
JWT sessions	Stateless auth, works well with Go	— Pending

---

Last updated: 2026-02-03 after initialization