Add README
This commit is contained in:
@@ -0,0 +1,233 @@
|
||||
# tiptoi-sync
|
||||
|
||||
Web-App zum Suchen, Herunterladen und Synchronisieren von tiptoi-Büchern auf den tiptoi-Stift. Läuft als selbst-gehosteter Server (z. B. auf einem Raspberry Pi oder Rock Pi) und ist über den Browser erreichbar – auch vom Smartphone aus.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
- **Barcode-Scanner** – Buch per Kamera-Scan (QR/EAN) suchen
|
||||
- **Freitextsuche** – nach Titel oder Artikelnummer suchen
|
||||
- **Download** – GME-Datei + Cover automatisch von Ravensburger herunterladen
|
||||
- **Bibliothek** – alle heruntergeladenen Bücher in der Übersicht
|
||||
- **Stift-Sync** – tiptoi-Stift per USB anschließen, Bücher direkt aus der App auf den Stift kopieren
|
||||
- **Stift-Status** – zeigt welche Bücher bereits auf dem Stift sind und welche fehlen
|
||||
- **PWA** – kann auf dem Homescreen installiert werden (Android/iOS)
|
||||
|
||||
---
|
||||
|
||||
## Architektur
|
||||
|
||||
```
|
||||
Browser / PWA
|
||||
│ HTTP
|
||||
▼
|
||||
┌─────────────────────────────────┐
|
||||
│ Bun + Elysia (Port 3000) │
|
||||
│ │
|
||||
│ /api/search → Ravensburger│
|
||||
│ /api/download → GME + Cover │
|
||||
│ /api/downloads → Bibliothek │
|
||||
│ /api/pen/detect → lsblk │
|
||||
│ /api/pen/files → Stift-Inhalt│
|
||||
│ /api/pen/sync → Dateien kop.│
|
||||
│ /api/pen/eject → umount │
|
||||
│ │
|
||||
│ /* → SolidJS SPA │
|
||||
└─────────────────────────────────┘
|
||||
│ │
|
||||
/data/ USB
|
||||
(GME-Dateien) tiptoi-Stift
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
- [Bun](https://bun.sh) ≥ 1.0
|
||||
- Node.js (nur für den Client-Build, via Bun verfügbar)
|
||||
- Docker + Docker Compose (für Deployment)
|
||||
|
||||
---
|
||||
|
||||
## Entwicklung (lokal)
|
||||
|
||||
```bash
|
||||
git clone <repo>
|
||||
cd tiptoi-sync
|
||||
bun install
|
||||
|
||||
# Server + Client parallel starten
|
||||
bun run dev
|
||||
```
|
||||
|
||||
- Client: `http://localhost:5173` (Vite Dev Server mit HMR)
|
||||
- Server: `http://localhost:3000`
|
||||
|
||||
Der Vite Dev Server proxied `/api/*` automatisch zum Server.
|
||||
|
||||
---
|
||||
|
||||
## Deployment
|
||||
|
||||
### Docker (empfohlen)
|
||||
|
||||
```bash
|
||||
# Image bauen
|
||||
docker compose build
|
||||
|
||||
# Starten
|
||||
docker compose up -d
|
||||
|
||||
# Logs
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
Die App ist danach unter `http://<server-ip>:3000` erreichbar.
|
||||
|
||||
Heruntergeladene GME-Dateien werden im Verzeichnis `./data/` gespeichert (persistentes Volume).
|
||||
|
||||
### Arm64 (Rock Pi, Raspberry Pi) – Cross-Build von x86
|
||||
|
||||
Auf der x86-Entwicklungsmaschine (mit **Podman**):
|
||||
|
||||
```bash
|
||||
# QEMU einmalig installieren
|
||||
sudo apt install qemu-user-static # Debian/Ubuntu
|
||||
sudo dnf install qemu-user-static # Fedora
|
||||
|
||||
# Image bauen und direkt auf den Server laden
|
||||
podman build --platform linux/arm64 -t tiptoi-sync:latest . \
|
||||
&& podman save --format docker-archive tiptoi-sync:latest \
|
||||
| ssh user@rockpi 'docker load'
|
||||
|
||||
# docker-compose.yml auf den Server kopieren und starten
|
||||
scp docker-compose.yml user@rockpi:~/tiptoi-sync/
|
||||
ssh user@rockpi 'mkdir -p ~/tiptoi-sync/data && cd ~/tiptoi-sync && docker compose up -d'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## USB-Automount (Headless Debian/Armbian)
|
||||
|
||||
Damit der tiptoi-Stift beim Einstecken automatisch gemountet wird (kein Desktop nötig):
|
||||
|
||||
### 1. Mount-Scripts installieren
|
||||
|
||||
```bash
|
||||
sudo tee /usr/local/bin/usb-mount.sh > /dev/null << 'EOF'
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
DEV="$1"
|
||||
DEVPATH="/dev/$DEV"
|
||||
FSTYPE=$(blkid -o value -s TYPE "$DEVPATH" 2>/dev/null || true)
|
||||
[ -z "$FSTYPE" ] && exit 0
|
||||
LABEL=$(blkid -o value -s LABEL "$DEVPATH" 2>/dev/null | tr ' /\\' '___' || true)
|
||||
UUID=$(blkid -o value -s UUID "$DEVPATH" 2>/dev/null || echo "$DEV")
|
||||
NAME="${LABEL:-$UUID}"
|
||||
MOUNTPOINT="/media/$NAME"
|
||||
mkdir -p "$MOUNTPOINT"
|
||||
mount "$DEVPATH" "$MOUNTPOINT"
|
||||
logger -t usb-mount "Gemountet: $DEVPATH → $MOUNTPOINT ($FSTYPE)"
|
||||
EOF
|
||||
sudo chmod +x /usr/local/bin/usb-mount.sh
|
||||
|
||||
sudo tee /usr/local/bin/usb-umount.sh > /dev/null << 'EOF'
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
DEV="$1"
|
||||
MOUNTPOINT=$(findmnt -n -o TARGET "/dev/$DEV" 2>/dev/null || true)
|
||||
if [ -n "$MOUNTPOINT" ]; then
|
||||
umount "$MOUNTPOINT"
|
||||
rmdir "$MOUNTPOINT" 2>/dev/null || true
|
||||
logger -t usb-mount "Ausgeworfen: /dev/$DEV ($MOUNTPOINT)"
|
||||
fi
|
||||
EOF
|
||||
sudo chmod +x /usr/local/bin/usb-umount.sh
|
||||
```
|
||||
|
||||
### 2. Systemd-Service-Template
|
||||
|
||||
```bash
|
||||
sudo tee /etc/systemd/system/usb-mount@.service > /dev/null << 'EOF'
|
||||
[Unit]
|
||||
Description=USB-Mount %i
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
RemainAfterExit=yes
|
||||
ExecStart=/usr/local/bin/usb-mount.sh %i
|
||||
ExecStop=/usr/local/bin/usb-umount.sh %i
|
||||
EOF
|
||||
```
|
||||
|
||||
### 3. udev-Regel
|
||||
|
||||
```bash
|
||||
sudo tee /etc/udev/rules.d/99-usb-mount.rules > /dev/null << 'EOF'
|
||||
ACTION=="add", SUBSYSTEMS=="usb", SUBSYSTEM=="block", ENV{ID_FS_TYPE}!="", \
|
||||
TAG+="systemd", ENV{SYSTEMD_WANTS}+="usb-mount@%k.service"
|
||||
|
||||
ACTION=="remove", SUBSYSTEMS=="usb", SUBSYSTEM=="block", \
|
||||
TAG+="systemd", RUN+="/bin/systemctl stop --no-block usb-mount@%k.service"
|
||||
EOF
|
||||
```
|
||||
|
||||
### 4. Aktivieren
|
||||
|
||||
```bash
|
||||
sudo udevadm control --reload-rules
|
||||
sudo systemctl daemon-reload
|
||||
```
|
||||
|
||||
### Testen
|
||||
|
||||
```bash
|
||||
# Stift einstecken, dann:
|
||||
journalctl -t usb-mount -f
|
||||
|
||||
# Manuell testen (Gerätname aus lsblk)
|
||||
sudo systemctl start usb-mount@sdb.service
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Umgebungsvariablen
|
||||
|
||||
| Variable | Standard | Beschreibung |
|
||||
|---|---|---|
|
||||
| `DOWNLOAD_DIR` | `./downloads` | Verzeichnis für GME-Dateien und Cover |
|
||||
| `STATIC_DIR` | *(leer)* | Pfad zum gebauten Client (`client/dist`). Wenn gesetzt, liefert der Server die SPA aus. |
|
||||
|
||||
---
|
||||
|
||||
## Projektstruktur
|
||||
|
||||
```
|
||||
tiptoi-sync/
|
||||
├── client/ # SolidJS PWA (Vite)
|
||||
│ └── src/
|
||||
│ ├── pages/
|
||||
│ │ ├── ScanPage.tsx # Barcode-Scanner + Suche
|
||||
│ │ └── DownloadsPage.tsx # Bibliothek + Stift-Sync
|
||||
│ └── components/
|
||||
│ └── QrScanner.tsx
|
||||
├── server/ # Bun + Elysia API
|
||||
│ └── src/
|
||||
│ └── index.ts
|
||||
├── Dockerfile
|
||||
├── docker-compose.yml
|
||||
└── 99-usb-mount.rules # udev-Regel (Referenz)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Hinweise
|
||||
|
||||
- Der **Stift muss vom Host-System gemountet** werden (udev-Automount, s. o.). Der Docker-Container greift über `rshared`-Volume-Mount darauf zu.
|
||||
- **Android-Direktsync** (Stift per USB-OTG ans Handy) ist technisch nicht möglich – Browser haben keinen Zugriff auf USB-Mass-Storage-Geräte.
|
||||
- Zum **sicheren Auswerfen** aus der Web-Oberfläche muss der Container mit `privileged: true` laufen (siehe `docker-compose.yml`).
|
||||
Reference in New Issue
Block a user