whattoplay/UBERSPACE.md

Uberspace Deployment

WhatToPlay wird auf einem Uberspace gehostet. Apache liefert das Frontend (SPA) aus, ein Express-Server läuft als systemd-Service und stellt die Steam API bereit.

Architektur

Browser (PWA)
    │
    ├── /           ──► Caddy ──► Apache      ──► SPA (React/Ionic)
    │                   .htaccess Rewrite        index.html
    │
    └── /api/*      ──► Express (:3000)      ──► Steam Web API
                        Prefix wird entfernt     api.steampowered.com

Voraussetzungen

• Uberspace Account (https://uberspace.de)
• SSH Zugriff (z.B. ssh wtp)
• Node.js (auf Uberspace vorinstalliert)

1. Repository klonen

ssh wtp
cd ~
git clone https://github.com/felixfoertsch/whattoplay.git

2. Backend einrichten

Dependencies installieren

cd ~/whattoplay/server
npm install

Systemd-Service erstellen

uberspace service add whattoplay 'node index.js' \
  --workdir /home/wtp/whattoplay/server \
  -e PORT=3000 \
  -e 'ALLOWED_ORIGIN=https://wtp.uber.space'

Das erstellt automatisch ~/.config/systemd/user/whattoplay.service, startet und aktiviert den Service.

Web-Backend konfigurieren

API-Requests unter /api an den Express-Server weiterleiten:

uberspace web backend set /api --http --port 3000 --remove-prefix

• --remove-prefix sorgt dafür, dass /api/steam/refresh als /steam/refresh beim Express-Server ankommt.

Service verwalten

# Status prüfen
uberspace service list
systemctl --user status whattoplay

# Logs anzeigen
journalctl --user -u whattoplay -f

# Neustarten (z.B. nach Code-Update)
systemctl --user restart whattoplay

# Stoppen / Starten
systemctl --user stop whattoplay
systemctl --user start whattoplay

3. Frontend deployen

Lokal bauen und hochladen

# .env.production anlegen (einmalig)
echo 'VITE_API_URL=https://wtp.uber.space' > .env.production
echo 'VITE_BASE_PATH=/' >> .env.production

# Build
npm run build

# Upload
rsync -avz --delete dist/ wtp:~/html/

Oder direkt auf dem Uberspace bauen

ssh wtp
cd ~/whattoplay
npm install
npm run build
cp -r dist/* ~/html/

SPA-Routing (.htaccess)

Damit React Router bei direktem Aufruf von Unterseiten funktioniert, muss eine .htaccess im Document Root liegen:

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /

  # Don't rewrite files or directories
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d

  # Don't rewrite API calls
  RewriteCond %{REQUEST_URI} !^/api/

  # Rewrite everything else to index.html
  RewriteRule . /index.html [L]
</IfModule>

Die Datei liegt bereits in public/.htaccess und wird beim Build automatisch nach dist/ kopiert.

4. Secrets (1Password)

Secrets werden über 1Password CLI (op) verwaltet. .env.1password enthält Referenzen auf 1Password-Einträge (keine echten Secrets).

Voraussetzung

1Password CLI installiert und eingeloggt auf dem Deploy-Mac:

brew install --cask 1password-cli

In 1Password einen Eintrag "WhatToPlay" im Vault "Private" anlegen mit:

• TWITCH_CLIENT_ID — Twitch Developer App Client ID
• TWITCH_CLIENT_SECRET — Twitch Developer App Client Secret

Lokale Entwicklung

npm run dev          # Startet Vite mit Secrets aus 1Password
npm run dev:no-op    # Startet Vite ohne 1Password (kein IGDB-Enrichment)

Einmalig: Server für EnvironmentFile konfigurieren

Der systemd-Service muss die Env-Datei laden, die beim Deploy geschrieben wird:

ssh wtp
mkdir -p ~/.config/systemd/user/whattoplay.service.d/
cat > ~/.config/systemd/user/whattoplay.service.d/env.conf << 'EOF'
[Service]
EnvironmentFile=%h/whattoplay.env
EOF
systemctl --user daemon-reload
systemctl --user restart whattoplay

5. Updates deployen

npm run deploy

Das Deploy-Script (deploy.sh) macht alles automatisch:

1. Frontend bauen (npm run build)
2. Frontend hochladen (rsync → ~/html/)
3. Backend hochladen (rsync → ~/whattoplay/server/)
4. Backend-Dependencies installieren
5. Secrets aus 1Password lesen und als ~/whattoplay.env auf den Server schreiben
6. Service neustarten

Manuelles Deploy (ohne 1Password)

npm run build
rsync -avz --delete dist/ wtp:~/html/
rsync -avz --delete --exclude node_modules --exclude data/igdb-cache.json server/ wtp:~/whattoplay/server/
ssh wtp "cd ~/whattoplay/server && npm install --production && systemctl --user restart whattoplay"

6. Domain (optional)

uberspace web domain add your-domain.com

DNS Records setzen:

A     @    <IP von Uberspace Server>
CNAME www  <servername>.uberspace.de

Die Server-IP findest du mit uberspace web domain list.

Aktueller Stand

Komponente	Wert
Server	larissa.uberspace.de
User	wtp
Domain	wtp.uber.space
Frontend	~/html/ → /var/www/virtual/wtp/html/ (Caddy → Apache)
Backend	~/whattoplay/server/ (Express :3000)
Service	systemd user service whattoplay
Web-Routing	/ → Apache, /api → Port 3000 (prefix remove)

Kosten

Uberspace: ab 1€/Monat (pay what you want, empfohlen ~5€)