free-games-claimer/SETUP.md

# Epic Games Free Games Claimer - Setup Guide

## 🚀 Quick Start (Docker Compose)

### Voraussetzungen

- Docker & Docker Compose
- Epic Games Account (Email, Passwort, optional 2FA)

### 1. docker-compose.yml erstellen

```yaml
services:
  # FlareSolverr für Cloudflare Bypass
  flaresolverr:
    image: ghcr.io/flaresolverr/flaresolverr:latest
    container_name: flaresolverr
    ports:
      - "8191:8191"
    environment:
      - LOG_LEVEL=info
      - LOG_HTML=false
      - CAPTCHA_SOLVER=none
    restart: unless-stopped
    networks:
      - fgc-network

  # Free Games Claimer
  free-games-claimer:
    image: git.sky-net.it/nocci/free-games-claimer:latest
    # ODER: build: .  # Selbst bauen für neueste Version
    container_name: fgc
    ports:
      - "6080:6080"  # noVNC (Web-Browser für Login)
      # - "5900:5900"  # VNC (optional)
    volumes:
      - fgc-data:/fgc/data
      - fgc-browser:/home/fgc/.cache/browser
      - fgc-playwright:/home/fgc/.cache/ms-playwright
    environment:
      # Epic Games Login
      - EG_EMAIL=deine@email.com
      - EG_PASSWORD=dein_passwort
      - EG_OTPKEY=          # Optional: 2FA Secret (Base32)
      
      # Login-Modus
      - EG_MODE=new         # "new" für API-Modus, "legacy" für Browser
      
      # FlareSolverr Integration
      - FLARESOLVERR_URL=http://flaresolverr:8191/v1
      
      # Browser-Einstellungen
      - SHOW=0              # 0=headless, 1=visible (für Debugging)
      - WIDTH=1920
      - HEIGHT=1080
      
      # Timeouts
      - TIMEOUT=60          # Standard-Timeout in Sekunden
      - LOGIN_TIMEOUT=180   # Login-Timeout (länger für Captchas)
      
      # Optional: Notifications
      # - NOTIFY=apprise://...
      
      # Keep-Alive (Container läuft weiter nach Durchlauf)
      - KEEP_ALIVE_SECONDS=86400
    networks:
      - fgc-network
    depends_on:
      - flaresolverr
    restart: unless-stopped

networks:
  fgc-network:
    driver: bridge

volumes:
  fgc-data:
  fgc-browser:
  fgc-playwright:
```

### 2. Environment-Variablen setzen

**WICHTIG:** Ersetze die Platzhalter:

```bash
# .env Datei erstellen (nicht versionieren!)
cat > .env << EOF
EG_EMAIL=deine@email.com
EG_PASSWORD=dein_passwort
EG_OTPKEY=              # Optional, wenn 2FA aktiv
NOTIFY=                 # Optional, für Benachrichtigungen
EOF
```

### 3. Starten

```bash
# Container starten
docker compose up -d

# Logs ansehen
docker compose logs -f fgc

# Container stoppen
docker compose down
```

---

## 🔐 Erster Login (WICHTIG!)

### Mit FlareSolverr (Empfohlen)

FlareSolverr löst Cloudflare Challenges automatisch:

1. Container starten (FlareSolverr läuft mit)
2. Erster Login wird automatisch versucht
3. Falls Captcha: FlareSolverr versucht es zu lösen
4. Nach Erfolg: Tokens werden gespeichert

### Ohne FlareSolverr (Manuell)

Falls Cloudflare Captchas nicht automatisch lösbar sind:

```bash
# Container mit visible Browser starten
docker compose up -d

# noVNC im Browser öffnen
http://localhost:6080

# Manuell bei Epic Games einloggen
# Cookies/Tokens werden automatisch gespeichert!
```

**Beim nächsten Start:** Kein Login nötig (gespeicherte Session)!

---

## 📋 Environment-Variablen

### Epic Games Login

| Variable | Beschreibung | Beispiel |
|----------|-------------|----------|
| `EG_EMAIL` | Epic Games Account Email | `user@example.com` |
| `EG_PASSWORD` | Epic Games Passwort | `secret123` |
| `EG_OTPKEY` | 2FA Secret (Base32) | `JBSWY3DPEHPK3PXP` |
| `EG_PARENTALPIN` | Parental Control PIN | `1234` |

### Login-Modus

| Variable | Beschreibung | Werte |
|----------|-------------|-------|
| `EG_MODE` | Login-Methode | `new` (API), `legacy` (Browser) |

### Browser & Display

| Variable | Beschreibung | Default |
|----------|-------------|---------|
| `SHOW` | Visible Browser | `0` (headless) |
| `WIDTH` | Browser Breite | `1920` |
| `HEIGHT` | Browser Höhe | `1080` |
| `BROWSER_DIR` | Browser Profil Pfad | `/fgc/data/browser` |

### Timeouts

| Variable | Beschreibung | Default |
|----------|-------------|---------|
| `TIMEOUT` | Standard-Timeout (Sekunden) | `60` |
| `LOGIN_TIMEOUT` | Login-Timeout (Sekunden) | `180` |
| `LOGIN_VISIBLE_TIMEOUT` | Login Button Detection (ms) | `20000` |

### FlareSolverr

| Variable | Beschreibung | Default |
|----------|-------------|---------|
| `FLARESOLVERR_URL` | FlareSolverr API URL | `http://flaresolverr:8191/v1` |

### Notifications

| Variable | Beschreibung | Beispiel |
|----------|-------------|----------|
| `NOTIFY` | Apprise Notification URL | `tgram://...` |
| `NOTIFY_TITLE` | Notification Titel | `Free Games Claimer` |

### Debugging

| Variable | Beschreibung | Default |
|----------|-------------|---------|
| `DEBUG` | Playwright Inspector | `0` |
| `DEBUG_NETWORK` | Log Network Requests | `0` |
| `DRYRUN` | Nicht wirklich claimen | `0` |
| `TIME` | Timing-Informationen | `0` |

---

## 🛠️ Troubleshooting

### Cloudflare / Captcha Probleme

**Symptom:** "Incorrect response" oder Captcha-Schleife

**Lösung 1: FlareSolverr prüfen**
```bash
docker compose logs flaresolverr
# Sollte "Serving on http://0.0.0.0:8191" zeigen
```

**Lösung 2: Manuelles Login**
```bash
# noVNC öffnen
http://localhost:6080

# Einmal manuell einloggen
# Cookies bleiben gespeichert!
```

**Lösung 3: Browser-Profil resetten**
```bash
docker volume rm fgc-browser
docker compose up -d
```

### Login schlägt fehl

**Symptom:** "Login failed" oder Timeout

**Lösung:**
1. Email/Passwort prüfen
2. 2FA: EG_OTPKEY korrekt setzen
3. Mit `SHOW=1` debuggen

### Container startet nicht

**Symptom:** Exit Code 1 oder hängt

**Logs prüfen:**
```bash
docker compose logs fgc
```

**Volumes prüfen:**
```bash
docker volume ls | grep fgc
```

---

## 📊 2FA / OTP einrichten

### Epic Games 2FA Secret auslesen

1. Epic Games Website → Account → Passwort & Sicherheit
2. Zwei-Faktor-Authentifizierung → Authentifizierungs-App
3. **NICHT** QR-Code scannen, sondern "Manuell eingeben" wählen
4. Secret kopieren (Base32, z.B. `JBSWY3DPEHPK3PXP`)

### In docker-compose.yml

```yaml
environment:
  - EG_OTPKEY=JBSWY3DPEHPK3PXP  # Dein Secret hier
```

---

## 🔄 Updates

### Image Update

```bash
# Aktuellen Container stoppen
docker compose down

# Neues Image pullen
docker compose pull

# Neu starten
docker compose up -d
```

### Selbst bauen (neueste Version)

```bash
# In docker-compose.yml: build: . statt image: ...
cd /path/to/free-games-claimer
docker compose build --no-cache
docker compose up -d
```

---

## 📁 Volumes (Persistenz)

| Volume | Inhalt | Wichtig |
|--------|--------|---------|
| `fgc-data` | JSON-Datenbank, Screenshots | ✅ Claim-Status |
| `fgc-browser` | Browser-Profil, Cookies | ✅ Login-Session |
| `fgc-playwright` | Playwright Browser | ⚡ Schnellere Starts |

**Backup:**
```bash
# Alle Volumes sichern
docker run --rm -v fgc-data:/data -v $(pwd)/backup:/backup alpine tar czf /backup/fgc-data.tar.gz -C /data .
```

**Restore:**
```bash
docker run --rm -v fgc-data:/data -v $(pwd)/backup:/backup alpine tar xzf /backup/fgc-data.tar.gz -C /data
```

---

## 🎯 Nächste Schritte

1. **Einrichten:** docker-compose.yml anpassen
2. **Starten:** `docker compose up -d`
3. **Erster Login:** noVNC oder mit FlareSolverr
4. **Automatisieren:** Cron-Job für regelmäßige Ausführung

### Cron-Job Beispiel (alle 6 Stunden)

```yaml
# In docker-compose.yml
command: >
  bash -c "
    node epic-games &&
    node gog &&
    sleep 86400
  "
```

Oder mit Host-Cron:
```bash
# Host-Cron bearbeiten
crontab -e

# Alle 6 Stunden
0 */6 * * * docker compose -f /path/to/docker-compose.yml up --rm free-games-claimer
```

---

## 🆘 Support

- **Issues:** https://git.sky-net.it/nocci/free-games-claimer/issues
- **Dokumentation:** README.md im Repository
- **FlareSolverr:** https://github.com/FlareSolverr/FlareSolverr