From 5b7f261ba6c5ad11fce5b4ce1be88dbdbd1f911a Mon Sep 17 00:00:00 2001
From: kisfenyo <nagyfenyvesi.viktor@gmail.com>
Date: Wed, 18 Feb 2026 21:22:29 +0100
Subject: [PATCH] docs: add attach existing drive wizard to README

Document the new v0.15.0 attach wizard: bind-mount approach,
API endpoints, file tree, and roadmap entry.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 controller/README.md | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/controller/README.md b/controller/README.md
index 4b598bc..fdca48c 100644
--- a/controller/README.md
+++ b/controller/README.md
@@ -378,6 +378,24 @@ A step-by-step UI at `/settings/storage/init`:
 
 Safety guards: system disk detection, mount path conflict check, confirmation required, progress channel for real-time UI feedback.
 
+#### Attach Existing Drive Wizard (`internal/storage/attach.go`)
+
+A step-by-step UI at `/settings/storage/attach` for drives that already have a filesystem (e.g., a previously used ext4 drive). Unlike the init wizard, this does **not** format the drive — existing data is preserved.
+
+**Problem solved:** Mounting a whole drive at `/mnt/<name>` would mix existing user data with the controller's directory structure (`storage/`, `Dokumentumok/`, backup repos). The bind-mount approach isolates the controller's working directory from other data on the drive.
+
+1. **Scan** — Lists available disks, filtered to partitions that have an existing filesystem (FSType != "")
+2. **Mount raw** — Partition is mounted read-only at a hidden staging path (`/mnt/.felhom-raw/<label>`)
+3. **Browse** — Directory browser shows the drive's contents. User can navigate and create a new folder (e.g., `felhom_data`)
+4. **Configure** — User enters a mount name and display label. Warning: mount path is immutable until detached
+5. **Finalize** — Bind-mounts the selected subfolder at `/mnt/<name>`. Two fstab entries are created (both with `nofail`):
+   - Raw mount: `UUID=<uuid> /mnt/.felhom-raw/<x> <fstype> defaults,nofail,noatime 0 2`
+   - Bind mount: `/mnt/.felhom-raw/<x>/<subfolder> /mnt/<name> none bind,nofail 0 0`
+6. Sets permissions (`chown 1000:1000`), creates `storage/` and `Dokumentumok/` subdirectories
+7. Auto-registers the storage path in settings.json + syncs FileBrowser mounts
+
+Cancel at any point cleans up the temporary raw mount. The bind mount path (`/mnt/<name>`) is a real mount point, so all existing code (disk usage, IsMountPoint checks, etc.) works unchanged.
+
 #### Storage Path Registry (`internal/settings/settings.go`)
 
 Multiple external storage paths supported with:
@@ -602,6 +620,7 @@ controller/
 │   ├── storage/
 │   │   ├── scan.go, scan_linux.go   # Disk detection via lsblk + blkid
 │   │   ├── format.go, format_linux.go  # Partition, format, mount pipeline
+│   │   ├── attach.go, attach_linux.go  # Attach existing FS drive (raw mount + bind mount)
 │   │   ├── safety.go, safety_linux.go  # System disk detection, mount guards, fstab ops
 │   │   ├── migrate.go              # App data migration (rsync with progress)
 │   │   └── *_other.go              # Non-Linux stubs for cross-compilation
@@ -634,7 +653,7 @@ controller/
 │       ├── server.go               # HTTP server, routing, static files
 │       ├── auth.go                 # Session auth, login/logout, session cleanup
 │       ├── handlers.go             # Page handlers (dashboard, stacks, deploy, backups, etc.)
-│       ├── storage_handlers.go     # Storage API handlers (scan, format, migrate, cleanup)
+│       ├── storage_handlers.go     # Storage API handlers (scan, format, attach, migrate, cleanup)
 │       ├── alerts.go               # State-based alert generation
 │       ├── funcmap.go              # Template functions (state colors, Hungarian formatting)
 │       ├── embed.go                # go:embed for templates + Chart.js
@@ -770,6 +789,12 @@ All daily jobs use Europe/Budapest timezone. Skip-if-running prevents concurrent
 | GET | `/api/storage/scan` | Scan available disks |
 | POST | `/api/storage/init` | Format and mount a disk |
 | GET | `/api/storage/init/status` | Format progress |
+| POST | `/api/storage/attach/mount-raw` | Temp-mount partition for browsing |
+| GET | `/api/storage/attach/browse?path=` | List directories on raw mount |
+| POST | `/api/storage/attach/mkdir` | Create folder on raw mount |
+| POST | `/api/storage/attach` | Finalize attach (bind mount + fstab) |
+| GET | `/api/storage/attach/status` | Attach progress |
+| POST | `/api/storage/attach/cancel` | Cleanup temp raw mount |
 | POST | `/api/storage/migrate` | Start app data migration |
 | GET | `/api/storage/migrate/status` | Migration progress |
 
@@ -834,6 +859,7 @@ See `docker-compose.yml` for the full volume configuration.
 - [x] 3-layer backup system (DB dumps + restic + cross-drive)
 - [x] Per-app backup restore with auto stop/restart
 - [x] Storage management (scan, format, mount, registry)
+- [x] Attach existing drive wizard (v0.15.0) — bind-mount subfolder from pre-formatted drive, directory browser
 - [x] App data migration between storage paths
 - [x] Central hub reporting
 - [x] Email notifications via hub relay
@@ -859,7 +885,7 @@ See `docker-compose.yml` for the full volume configuration.
 
 | Node | Hardware | Domain | Status |
 |------|----------|--------|--------|
-| demo-felhom | Acemagic GK3PLUS N100, 16G RAM, 512G SSD + 1TB HDD | demo-felhom.eu | Controller v0.14.1 (pending OS reinstall) |
+| demo-felhom | Acemagic GK3PLUS N100, 16G RAM, 512G SSD + 1TB HDD | demo-felhom.eu | Controller v0.15.0 |
 | pi-customer-1 | Raspberry Pi 3B+, 1G RAM, 32G SD | pi-customer-1.local | Not yet tested |
 
 ## Related Repositories