From 075f5856124df03d37bf99d35e5ae1b2ee76603a Mon Sep 17 00:00:00 2001
From: "Steven (Zen)" <steve@asus>
Date: Sat, 15 Aug 2026 12:41:29 -0600
Subject: [PATCH] update readme: disk caching, refresh endpoint, Docker setup

---
 readme.md | 58 ++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 42 insertions(+), 16 deletions(-)

diff --git a/readme.md b/readme.md
index 1bc7212..2bef421 100644
--- a/readme.md
+++ b/readme.md
@@ -1,14 +1,14 @@
 # Eagle Viewer
 
-A proof-of-concept web app for browsing Eagle libraries stored on a Synology NAS, from Linux or any browser (Chromebook included).
+A web app for browsing Eagle libraries stored on a Synology NAS, from any browser (Chromebook, iPhone, Linux included).
 
 Built because Eagle only runs on Mac and Windows.
 
 ## How it works
 
-- Bulk metadata load via a single SSH `find | cat` command (~3.5s for 372 images, ~30s for 10k+)
-- Thumbnails and files served directly from the SMB mount
-- Thumbnails cached in memory after first load
+- All NAS access via SSH — metadata and thumbnails
+- Metadata and thumbnails cached to disk on first load (survives container restarts)
+- In-memory cache warms up from disk on first request each session
 
 ## Features
 
@@ -19,28 +19,54 @@ Built because Eagle only runs on Mac and Windows.
 - Lightbox on click
 - "Open original" streams the file (mp4, png, pdf, etc.) via HTTP with range support
 
-## Known limitations
+## Caching
 
-- Thumbnail cache is in-memory only — resets on server restart
-- Large libraries (10k+ images) take ~30s to load on first click (no disk cache yet)
-- "Open original" for large video files is slow over SMB — a production version would want a proper media server
+| Layer | What's cached | Survives restart? |
+|---|---|---|
+| Disk (metadata) | Library item list, folders, tags | Yes |
+| Disk (thumbnails) | Thumbnail images | Yes |
+| In-memory | Metadata (hot path after disk cache warms) | No |
 
-## Requirements
+On first click, a library is fetched from the NAS over SSH and written to disk. Every subsequent click is served from disk — instant, even after a container restart.
 
-- Node.js
-- `sshpass` installed (`sudo apt install sshpass`)
-- NAS SMB share mounted at `/run/user/1000/gvfs/smb-share:server=synologynas.local,share=steve/Eagle_Libraries`
-- SSH access to `synologynas.local`
+## Refreshing a library
 
-## Setup
+If you add new items to a library on the NAS, the disk cache will be stale. Force a refresh with:
+
+```bash
+curl -X POST http://100.88.231.3:3737/api/library/remote_photos/refresh
+```
+
+Replace `remote_photos` with the library name. This fetches fresh metadata from the NAS and updates the disk cache. Returns `{ ok: true, imageCount: N, ms: N }` when done.
+
+## Running with Docker (recommended)
+
+```bash
+cd ~/docker
+docker compose up -d eagle-viewer
+```
+
+The thumb cache is persisted at `~/docker/eagle-viewer/thumb-cache/`.
+
+## Running manually (development)
 
 ```bash
-cd ~/workspace/gitea/eagle-viewer
 npm install
 node server.js
 ```
 
-Then open [http://localhost:3737](http://localhost:3737) in your browser.
+Requires `sshpass` installed (`sudo apt install sshpass`).
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `SSH_HOST` | `synologynas.local` | NAS hostname or IP |
+| `SSH_USER` | `steve` | SSH username |
+| `SSH_PASS` | `cheong` | SSH password |
+| `NAS_BASE` | `/volume1/steve/Eagle_Libraries` | Libraries root path on NAS |
+| `CACHE_DIR` | `./.thumb-cache` | Disk cache directory |
+| `PORT` | `3737` | HTTP port |
 
 ## Gitea