2026-06-09 16:20:26 +10:00
1 changed files with 221 additions and 13 deletions
@@ -28,30 +28,49 @@ A lightweight, self-contained Docker web application that connects to your [Immi
 - **Older Device Friendly** — Vanilla HTML/CSS/JS, no heavy frameworks
 - **Docker Containerised** — Single container, minimal footprint

-## 🚀 Quick Start
+---
+
+## 🚀 Deployment
+
+### Prerequisites
+
+- A running [Immich](https://immich.app/) server
+- An Immich API key (see below)
+- Docker and Docker Compose (recommended) — or Node.js 18+ for running from source

 ### 1. Get your Immich API Key

 1. Open your Immich web interface
 2. Click your profile picture → **Account Settings** → **API Keys**
 3. Create a new key with `asset.read` and `album.read` permissions
+4. Copy the key — you'll need it for the next step

-### 2. Run with Docker Compose
+### 2. Deploy with Docker Compose (recommended)

 ```bash
 git clone https://gitea.hideawaygaming.com.au/jessikitty/frambe.git
 cd frambe
 ```

-Edit `docker-compose.yml` and set your `IMMICH_URL` and `IMMICH_API_KEY`, then:
+Edit `docker-compose.yml` and set your `IMMICH_URL` and `IMMICH_API_KEY`:
+
+```yaml
+environment:
+  - IMMICH_URL=http://your-immich-server:2283
+  - IMMICH_API_KEY=your-api-key-here
+```
+
+Then start the container:

 ```bash
 docker compose up -d
 ```

-Open `http://your-server:3030` in a browser on your tablet/screen.
+Frambe is now running at `http://your-server:3030`.

-### 3. Run with Docker directly
+### 3. Deploy with Docker Run
+
+If you prefer not to use Compose:

 ```bash
 docker build -t frambe .
@@ -64,6 +83,104 @@ docker run -d \
  frambe
 ```

+### 4. Run from Source (development)
+
+```bash
+git clone https://gitea.hideawaygaming.com.au/jessikitty/frambe.git
+cd frambe
+npm install
+```
+
+Create a `.env` file from the example:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your Immich URL and API key, then start the server:
+
+```bash
+npm start
+```
+
+Frambe will be available at `http://localhost:3000`.
+
+### Port Mapping
+
+The internal server runs on port **3000**. The Docker Compose config maps this to external port **3030** by default. You can change this in `docker-compose.yml`:
+
+```yaml
+ports:
+  - "8080:3000"    # Access Frambe on port 8080 instead
+```
+
+---
+
+## 🔄 Upgrading
+
+### Docker Compose (recommended)
+
+```bash
+cd frambe
+git pull
+docker compose build
+docker compose up -d
+```
+
+Your configuration in `docker-compose.yml` is preserved — only the application code is rebuilt.
+
+### Docker Run
+
+```bash
+cd frambe
+git pull
+docker stop frambe
+docker rm frambe
+docker build -t frambe .
+docker run -d \
+  --name frambe \
+  -p 3030:3000 \
+  -e IMMICH_URL=http://your-immich-server:2283 \
+  -e IMMICH_API_KEY=your-api-key \
+  --restart unless-stopped \
+  frambe
+```
+
+### From Source
+
+```bash
+cd frambe
+git pull
+npm install
+npm start
+```
+
+### Switching to a Specific Version
+
+Frambe uses git tags for releases. To pin to a specific version:
+
+```bash
+git fetch --tags
+git checkout v1.4.0        # Replace with desired version
+docker compose build && docker compose up -d
+```
+
+To switch back to the latest:
+
+```bash
+git checkout main
+git pull
+docker compose build && docker compose up -d
+```
+
+### Upgrade Notes
+
+- **All upgrades are non-destructive** — Frambe stores no persistent data on disk. All configuration is via environment variables.
+- **No database migrations** — there is no database. Session tokens are in-memory and will reset on restart (users simply log in again).
+- **Check the changelog below** before upgrading major versions for any new required environment variables.
+
+---
+
 ## 🔑 Authentication

 ### Admin Dashboard Login
@@ -87,6 +204,8 @@ environment:
  - FRAMBE_API_TOKEN=your-secret-token-here
 ```

+---
+
 ## 🔌 REST API

 When `FRAMBE_API_TOKEN` is configured, the following endpoints are available:
@@ -130,6 +249,8 @@ rest_command:

 Authentication can also be provided via `x-api-token` header or `?token=` query parameter.

+---
+
 ## 🔗 Zero-Touch URL Parameters

 Skip the setup screen entirely by passing query parameters. This is ideal for dedicated frames — just bookmark the URL on each tablet:
@@ -143,9 +264,11 @@ Skip the setup screen entirely by passing query parameters. This is ideal for de

 You can find album and person UUIDs in Immich's web interface URL bar when viewing an album or person.

+---
+
 ## ⚙️ Configuration

-All settings are via environment variables:
+All settings are via environment variables. Set them in `docker-compose.yml`, pass with `docker run -e`, or put them in a `.env` file when running from source.

 | Variable | Default | Description |
 |---|---|---|
@@ -160,6 +283,7 @@ All settings are via environment variables:
 | `SHOW_DATE` | `true` | Display date overlay |
 | `SHOW_EXIF` | `true` | Display photo metadata |
 | `SHOW_PROGRESS` | `true` | Display progress bar |
+| `INCLUDE_VIDEOS` | `true` | Include video assets in slideshow |
 | `REFRESH_INTERVAL` | `300` | Seconds between source refresh checks (new photos) |
 | `ALBUM_ID` | *(empty)* | Auto-start with specific album (env-based) |
 | `SHOW_FAVORITES_ONLY` | `false` | Auto-start with favorites (env-based) |
@@ -168,6 +292,8 @@ All settings are via environment variables:
 | `FRAMBE_API_TOKEN` | *(empty)* | API token for REST endpoint access (leave empty for open access) |
 | `PORT` | `3000` | Internal server port (Docker maps externally via compose) |

+---
+
 ## 🎮 Controls

 ### Touch / Mouse
@@ -182,6 +308,8 @@ All settings are via environment variables:
 - `I` — Toggle info overlay
 - `Esc` — Exit to album selection

+---
+
 ## 📱 Tablet Setup Tips

 1. Open the frame URL in your tablet's browser (use a `?album=` or `?person=` URL for zero-touch)
@@ -189,14 +317,94 @@ All settings are via environment variables:
 3. Enable kiosk mode or guided access to lock to the app
 4. Disable screen timeout in your device settings

-## 📋 Version History
+---

- **1.4.0** — Admin login (username/password), API token auth for external access (Home Assistant), REST endpoints (`GET /api/clients`, `POST /api/clients/:id/command`)
- **1.3.0** — Admin dashboard with real-time WebSocket frame management, video support, person/face support
- **1.2.1** — Fix port mapping (3030:3000 external:internal), fix URL param auto-launch not starting slideshow
- **1.2.0** — URL params (`?album=`, `?person=`, `?favorites`, `?random`), person/face support, periodic auto-refresh, app icon, default port changed to 3030
- **1.1.0** — Rebrand to Frambe
- **1.0.0** — Initial release: album browser, slideshow with crossfade, clock/date/EXIF overlays, touch & keyboard controls, Docker deployment
+## 🏗️ Architecture
+
+```
+┌──────────────┐         ┌──────────────┐         ┌──────────────┐
+│   Browser    │  HTTP   │    Frambe    │   API   │    Immich     │
+│  (Tablet)    │◄────────►│  (Node.js)  │◄────────►│   Server     │
+└──────────────┘  :3030  └──────────────┘  :2283  └──────────────┘
+                              ▲
+                    ┌─────────┴─────────┐
+                    │  REST API / WS    │
+                    │  (Home Assistant) │
+                    └───────────────────┘
+```
+
+The Node.js backend acts as a secure proxy — your Immich API key never reaches the browser. The frontend periodically polls the backend for new photos so albums stay up to date without restarting.
+
+---
+
+## 🏷️ Versioning
+
+Frambe follows [Semantic Versioning](https://semver.org/):
+
+- **Major** (`X.0.0`) — Large feature overhauls, breaking changes, or major UI redesigns
+- **Minor** (`0.X.0`) — New features, functionality additions, or significant improvements
+- **Patch** (`0.0.X`) — Bug fixes, small tweaks, and minor corrections
+
+### Branches
+
+| Branch | Purpose |
+|---|---|
+| `main` | Stable releases — production-ready code |
+| `dev` | Development — latest features, may be unstable |
+
+### Changelog
+
+#### v1.4.0 — Admin Auth & REST API
+- ✅ Admin dashboard login with username/password authentication (env-based)
+- ✅ Session management with HttpOnly cookies (24-hour expiry, automatic cleanup)
+- ✅ API token authentication for external access (Home Assistant, scripts, curl)
+- ✅ REST endpoint: `GET /api/clients` — list all connected frames
+- ✅ REST endpoint: `POST /api/clients/:id/command` — send commands to frames
+- ✅ Multiple auth methods: Bearer token, `x-api-token` header, `?token=` query param
+- ✅ Auth status endpoint: `GET /api/auth/status`
+- ✅ Backwards compatible — auth is opt-in, disabled by default
+- 🆕 New env vars: `ADMIN_USERNAME`, `ADMIN_PASSWORD`, `FRAMBE_API_TOKEN`
+
+#### v1.3.0 — Admin Dashboard & Video Support
+- ✅ Real-time admin dashboard at `/admin` with WebSocket communication
+- ✅ Live frame management: start, stop, next, prev, sleep, wake, refresh
+- ✅ Remote source switching: change album, person, random, or favorites per frame
+- ✅ Remote config: adjust slideshow interval, toggle clock/date/EXIF/progress per frame
+- ✅ Frame naming and rename support (persists by IP)
+- ✅ Video playback support in slideshow (with `INCLUDE_VIDEOS` toggle)
+- ✅ Person / face recognition photo source via Immich's people API
+- ✅ Connection status indicators and auto-reconnect
+
+#### v1.2.1 — Bug Fixes
+- 🐛 Fixed port mapping (3030:3000 external:internal)
+- 🐛 Fixed URL parameter auto-launch not starting the slideshow
+
+#### v1.2.0 — Zero-Touch Launch & Auto-Refresh
+- ✅ URL query parameters for zero-touch launch (`?album=`, `?person=`, `?favorites`, `?random`)
+- ✅ Person / face support — display photos of a specific person
+- ✅ Periodic auto-refresh — new photos appear without restarting
+- ✅ App icon for home screen bookmarks
+- ✅ Default external port changed to 3030
+- 🆕 New env var: `REFRESH_INTERVAL`
+
+#### v1.1.0 — Rebrand
+- ✅ Rebranded to Frambe
+
+#### v1.0.0 — Initial Release
+- ✅ Album browser with Immich API integration
+- ✅ Full-screen slideshow with smooth crossfade transitions
+- ✅ Double-buffered image loading for seamless display
+- ✅ Background blur behind non-covering images
+- ✅ Clock, date, and EXIF metadata overlays
+- ✅ Progress bar showing time until next photo
+- ✅ Touch controls (left/centre/right tap zones)
+- ✅ Keyboard controls (arrows, space, F, I, Esc)
+- ✅ Screen wake lock to prevent display sleep
+- ✅ Configurable via environment variables
+- ✅ Docker containerised deployment
+- ✅ Vanilla HTML/CSS/JS frontend — no frameworks, works on older devices
+
+---

 ## 📄 License