eagle-viewer/readme.md

# Eagle Viewer

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

- 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

- Lists all Eagle libraries on the NAS
- Dark grid UI with adjustable thumbnail size
- Folder tree sidebar
- Search by name or tag
- Lightbox on click
- "Open original" streams the file (mp4, png, pdf, etc.) via HTTP with range support

## Caching

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

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.

## Refreshing a library

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
npm install
node server.js
```

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

[http://zen.local:9000/steve/eagle-viewer](http://zen.local:9000/steve/eagle-viewer)