t-youtube/docs/configuration.md

t-youtube Configuration Guide

Environment Variables

Backend (.env)

# 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

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

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:

  sqlite3 t_youtube.db "CREATE INDEX IF NOT EXISTS idx_x ON table(column);"
  

Daily Sync Configuration

Cron Job

# 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

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

# VPS
ssh caddy-vps "sudo systemctl reload caddy"

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

Monitoring & Health

Health Check

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

ls -lh /volume1/docker/t-youtube/backend/t_youtube.db