Small Web Gallery

Leichter Proxy/Fotorahmen fuer alte Tablets.
Der Dienst holt Bilder aus einem Nextcloud-Album (DAV), skaliert sie serverseitig herunter und zeigt sie in einer sehr kleinen Slideshow-Webseite an.

Features

• Sehr wenig JavaScript im Client (geeignet fuer alte WebViews)
• Bilder serverseitig skaliert und als JPEG gecacht
• Mehrere Tablet-Accounts mit eigenem Nextcloud-Zugang und Album
• Intervall und Accounts über separates Menü einstellbar
• Nextcloud-Zugangsdaten pro Account in SQLite

1) Setup lokal

npm install
cp .env.example .env

.env anpassen:

• ADMIN_USER und ADMIN_PASSWORD setzen (für Menü/API)
• optional NC_ALBUM als Standard-Album für neue Accounts

Starten:

npm start

Konfiguration im Menü: http://<server-ip>:8787/menu

Pro Tablet eine eigene kurze URL:

http://<server-ip>:8787/<slug>

Beispiel: http://192.168.1.50:8787/wohnzimmer

Die alte Form /frame/<slug> leitet automatisch weiter.

2) Deployment nach /opt/small-web-gallery

sudo mkdir -p /opt/small-web-gallery
sudo rsync -av --delete ./ /opt/small-web-gallery/
cd /opt/small-web-gallery
sudo npm ci --omit=dev
sudo cp .env.example .env
sudo nano .env

2b) Deployment ohne Node-Installation (Docker)

Wenn auf dem Host kein node/npm installiert ist:

cp .env.example .env
nano .env
docker compose up -d --build
docker compose logs -f

3) Systemd Service

Service installieren:

sudo cp /opt/small-web-gallery/deploy/small-web-gallery.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now small-web-gallery
sudo systemctl status small-web-gallery

4) Endpunkte

Tablet (slug)

• GET /<slug> - Slideshow-Seite (z. B. /wohnzimmer)
• GET /frame/<slug> - Weiterleitung auf /<slug>
• GET /api/next/<slug> - Nächstes Bild
• GET /img/<id>?slug=...&w=...&h=...&q=... - Optimiertes JPEG

Admin

• GET /menu - Konfig-Menü (Login-Formular, Session-Cookie; Basic Auth weiterhin möglich)

• POST /menu/login - Anmeldung fürs Menü

• GET /api/accounts - Alle Accounts (Basic Auth)

• POST /api/accounts - Neuen Account anlegen

• GET /PUT /DELETE /api/accounts/:id - Account verwalten

• GET /api/accounts/:id/albums - Alben für einen Account

• GET /health - Basisstatus

Hinweise

• Der Dienst lauscht auf 0.0.0.0:<PORT> und ist damit in allen erreichbaren internen Netzen nutzbar. Zugriff von aussen per Packetfilter/Firewall absichern.
• Jeder Tablet-Account hat einen eigenen Slug, Nextcloud-Zugang und Album.
• Der Slug ist die kurze URL fürs Tablet, z. B. /wohnzimmer → http://<server>:8787/wohnzimmer.
• Die Frame-URL wird im Menü angezeigt und kann pro Tablet in der Kiosk-App hinterlegt werden.
• Bei internem Zertifikat: IGNORE_TLS=true setzen.
• Der Proxy kennt die Nextcloud-App-Passwörter; die Tablets nicht.
• Zugangsdaten werden in SQLite gespeichert (CREDENTIALS_DB_PATH, Standard ./cache/credentials.sqlite).
• /menu ist per Login-Formular geschützt (Session-Cookie, 7 Tage). Die Account-API akzeptiert weiterhin HTTP Basic Auth (ADMIN_USER/ADMIN_PASSWORD).
• /health gibt ohne Auth nur einen Minimalstatus zurück.
• Beim Upgrade wird ein bestehendes Single-Setup automatisch als Account default migriert.

Sicherheit

• Admin-Zugang: /menu und /api/* erfordern Login bzw. HTTP Basic Auth. Setze starke Werte für ADMIN_USER und ADMIN_PASSWORD.
• Fotorahmen-URLs: /<slug> ist nur durch den Slug geschützt (kein Token in der URL). Slugs unvorhersehbar wählen und den Dienst nicht ungefiltert ins Internet stellen.
• Nextcloud-Zugang: App-Passwörter liegen serverseitig in SQLite (cache/credentials.sqlite). Tablets brauchen nur die Frame-URL.
• Netzwerk: Der Dienst bindet auf 0.0.0.0. Zugriff von außen per Firewall einschränken; intern reicht meist LAN/VPN.
• /health: Ohne Auth nur { ok: true }. Mit Admin-Login zusätzlich Account-Anzahl und Slug-Liste.

CI/CD (Forgejo Actions)

Optionaler Deploy per .forgejo/workflows/deploy.yml per rsync + Docker.

Repository-Variablen

Forgejo: Settings → Actions → Variables

Variable	Beschreibung	Beispiel
DEPLOY_HOST	Ziel-Host (SSH)	gallery.example.com
DEPLOY_USER	SSH-Benutzer	deploy
DEPLOY_PATH	Zielverzeichnis auf dem Host	/opt/small-web-gallery
DEPLOY_CONTAINER_IMAGE	CI-Container mit ssh/rsync	registry.example.com/deploy/debian-bookworm-ssh-rsync:latest

Repository-Secrets

Forgejo: Settings → Actions → Secrets

Secret	Beschreibung
DEPLOY_SSH_KEY	Privater SSH-Key (OpenSSH-Format, Passphrase leer)

Der passende Public Key muss auf dem Zielhost unter ~/.ssh/authorized_keys des Deploy-Users liegen.

Der Runner braucht das Label aus runs-on in der Workflow-Datei (Standard: arch) und Zugriff auf DEPLOY_CONTAINER_IMAGE.

Android Kiosk Setup (empfohlen)

Empfohlener Kiosk-Browser (leichtgewichtig, Android 5.0+):

• Webview Kiosk auf F-Droid: https://f-droid.org/packages/uk.nktnet.webviewkiosk/
• Paketname: uk.nktnet.webviewkiosk
• Beispiel-APK-Datei: uk.nktnet.webviewkiosk_126.apk

1. Auf dem Tablet eine schlanke Kiosk/WebView-App installieren.
2. Im Menü (/menu) Account anlegen und Frame-URL kopieren.
3. Start-URL im Kiosk auf die kurze URL setzen, z. B. http://<server-ip>:8787/wohnzimmer.
4. Kiosk-Optionen aktivieren:
   • Vollbild
   • Bildschirm immer an
   • Autostart bei Boot
   • URL-Navigation sperren
5. Konfiguration nur über Menü-URL vornehmen: http://<server-ip>:8787/menu

Tipp: Wenn der WebView „hängt“, App einmal neu starten. Die Frame-Seite hat zusätzlich einen periodischen Selbst-Reload.

Schnellstart mit adb

Voraussetzung: USB-Debugging am Tablet aktivieren und adb lokal installiert haben.

1. Gerät prüfen:

adb devices

2. APK installieren (oder aktualisieren):

adb install -r uk.nktnet.webviewkiosk_126.apk

3. Kiosk-App starten:

adb shell monkey -p uk.nktnet.webviewkiosk -c android.intent.category.LAUNCHER 1

4. Frame-URL aufrufen (Slug aus dem Menü):

adb shell am start -a android.intent.action.VIEW -d "http://<server-ip>:8787/<slug>"

5. Danach im Webview Kiosk einmalig setzen:
   • Start-URL: http://<server-ip>:8787/<slug>
   • Vollbild, Always-On, Autostart bei Boot aktivieren.

Optional (ADB über WLAN statt USB, solange einmal per USB gekoppelt):

adb tcpip 5555
adb connect <tablet-ip>:5555