jessikitty/frambe
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity

docs: expanded README with deployment, upgrade, and versioning sections

Browse Source
This commit is contained in:
jessikitty
2026-05-26 16:28:11 +10:00
parent 39aff8c839
commit 0c279ad00a
1 changed files with 221 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+221 -13
View File
@@ -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