# t-youtube Configuration Guide

## Environment Variables

### Backend (.env)
```bash
# Database path
DB_DIR=/volume1/docker/t-youtube/backend

# API Token (for write operations)
API_TOKEN=<your-api-token>

# DeepSeek API (for summarization)
DEEPSEEK_API_KEY=<your-key>

# YouTube Data API v3
GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
```

### Docker Compose
```yaml
version: "3"
services:
  t-youtube:
    build: .
    ports:
      - "8001:8001"
    environment:
      - DB_DIR=/backend/data
      - API_TOKEN=<your-token>
      - DEEPSEEK_API_KEY=<your-key>
    volumes:
      - ./backend/data:/backend/data
```

## API Token Management

### Generation
```bash
python3 -c "import secrets; print('api-' + secrets.token_urlsafe(32))"
```

### Frontend Setup
- First-time users see a token setup modal
- Token stored in localStorage
- Bearer token sent with all API write requests

### Backend Validation
- Middleware checks `Authorization: Bearer <token>` for POST/PATCH/DELETE on `/api/*`
- Returns 401 JSON for invalid tokens
- GET endpoints remain open to authenticated frontend users

## Database Management

### Location
- **Path**: `/volume1/docker/t-youtube/backend/t_youtube.db`
- **Type**: SQLite (aiosqlite)
- **Backup**: Copy the `.db` file before any schema changes

### Schema Migrations
- Use `sqlite3` CLI or a migration script
- Always add indexes after schema changes
- Example:
  ```bash
  sqlite3 t_youtube.db "CREATE INDEX IF NOT EXISTS idx_x ON table(column);"
  ```

### Daily Sync Configuration

#### Cron Job
```bash
# Runs every day at 3 AM
0 3 * * * /path/to/run_sync.py >> /var/log/t-youtube-sync.log 2>&1
```

#### Fetcher Settings
- **RSS**: Free, unlimited, ~2000 channels
- **YouTube Data API v3**: ~50 units per sync
- **Rotation**: Fetches in slices to avoid timeouts
- **Retry**: Automatic retry on failure

#### Summarizer Settings
- **Model**: `deepseek-chat` via DeepSeek API
- **Timeout**: 30 seconds per video
- **Fallback**: Video description if transcript unavailable
- **Language**: Follows content language (Chinese → Chinese summary)

## Authelia Integration

### Authentication Flow
1. User accesses protected domain
2. Caddy forwards request to Authelia (`127.0.0.1:9092`)
3. Authelia checks session/2FA
4. If no session → redirect to `auth.jimmygan.com`
5. If session exists → return 200 (allowed)

### 2FA Methods
- **WebAuthn (Primary)**: Passkey via iCloud Keychain/Bitwarden
- **TOTP (Fallback)**: Time-based one-time password

### Configuration
- **Address**: `127.0.0.1:9092`
- **Database**: SQLite (`/volume1/docker/authelia/config/db.sqlite3`)
- **LDAP Backend**: LLDAP (`lldap:3890`)
- **Session**: 1 hour expiration, 5 minute inactivity timeout

### Restart Authelia
```bash
cd /volume1/docker/authelia && /usr/local/bin/docker compose restart authelia
```

## Caddy Configuration

### VPS Caddy (Public)
- **Port**: 443
- **TLS**: Let's Encrypt (HTTP-01)
- **Authelia**: `forward_auth 100.78.131.124:9092`
- **DNS**: dnsmasq → VPS Tailscale IP `100.109.198.126`

### NAS Caddy (Local/Tailscale)
- **Port**: 8443 (fallback due to SNI bug)
- **TLS**: Cloudflare DNS-01
- **Authelia**: `forward_auth 127.0.0.1:9092`
- **SNI Bug**: Per-site `tls` blocks cause cert routing issues
- **Workaround**: Global TLS config + dnsmasq → VPS Tailscale IP

### Reloading Caddy
```bash
# VPS
ssh caddy-vps "sudo systemctl reload caddy"

# NAS
cd /volume1/docker/caddy && /usr/local/bin/docker compose restart caddy
```

## Monitoring & Health

### Health Check
```bash
curl -s https://yt.jimmygan.com/api/health
# Expected: {"status": "ok"}
```

### Sync Status
- Check `run_sync.py` logs in `/var/log/t-youtube-sync.log`
- Monitor DB for new videos/summaries
- Verify cron job is active: `crontab -l`

### Database Size
```bash
ls -lh /volume1/docker/t-youtube/backend/t_youtube.db
```