steve/eagle-viewer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update readme: disk caching, refresh endpoint, Docker setup

Browse Source
This commit is contained in:
Steven (Zen) 2026-08-15 12:41:29 -06:00
parent ad45d9a6b9
commit 075f585612
1 changed files with 42 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
readme.md
View File

@ -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