docs: documentacion completa para humanos y agentes IA
- README reescrito: ejemplos CLI corregidos (flags van en el subcomando scrape), webapp+doctor documentados, requisitos por OS, cookies, datos generados, migracion de maquina - CLAUDE.md actualizado: conteo de tests, refs de linea reparadas, scripts nuevos, checklist de actualizacion de docs - AGENTS.md nuevo: entrada estandar para cualquier agente de codigo (mapa de modulos, comandos, reglas de oro, punteros a docs) - docs/GETTING-STARTED.md: de cero a webapp por OS con troubleshooting - docs/CONFIG.md: referencia completa de las ~25 claves de config - docs/COOKIES.md: adquisicion, import (web/navegador/CLI), rotacion y seguridad - docs/backlog.md reemplaza OPPORTUNITIES.md (distilado: shipped vs pendiente) - auditorias movidas a docs/audits/ y CLIPPER-COMPARISON-AUDIT.md versionado
This commit is contained in:
urieljareth
@@ -0,0 +1,159 @@
|
||||
# Getting Started — máquina nueva desde cero
|
||||
|
||||
De un equipo vacío a la webapp corriendo y el primer scrape hecho. Una sección por OS; salta a la tuya. Todo lo demás (arquitectura, CLI completo, config) está en el [README](../README.md).
|
||||
|
||||
Regla transversal: **todos los comandos se ejecutan desde la raíz del repo** (`yt-channel-scraper/`), porque las rutas de `config.yaml` se resuelven relativas al directorio de trabajo.
|
||||
|
||||
## Windows
|
||||
|
||||
### 1. Python
|
||||
|
||||
PowerShell:
|
||||
|
||||
```powershell
|
||||
winget install Python.Python.3.12
|
||||
# cierra y reabre la terminal para que entre en PATH; verifica:
|
||||
python --version
|
||||
```
|
||||
|
||||
### 2. Obtener el código
|
||||
|
||||
```powershell
|
||||
git clone <URL-del-gitea> yt-channel-scraper
|
||||
cd yt-channel-scraper
|
||||
```
|
||||
|
||||
### 3. Entorno + dependencias
|
||||
|
||||
```powershell
|
||||
# Opción A: uv (recomendado; respeta uv.lock)
|
||||
winget install astral-sh.uv
|
||||
uv sync --all-extras
|
||||
|
||||
# Opción B: venv + pip
|
||||
python -m venv .venv
|
||||
.venv\Scripts\activate
|
||||
pip install -e ".[dev,web,analysis]"
|
||||
```
|
||||
|
||||
Extras: `dev` (tests), `web` (webapp), `analysis` (gráficos). Puedes instalar solo los que uses.
|
||||
|
||||
### 4. ffmpeg y node (opcionales)
|
||||
|
||||
- **ffmpeg**: solo necesario para `yt-scraper audio` / job de audio → `winget install Gyan.FFmpeg`.
|
||||
- **node**: yt-dlp lo usa para resolver challenges de YouTube → `winget install OpenJS.NodeJS.LTS`.
|
||||
|
||||
Reabre la terminal tras instalar y verifica con `ffmpeg -version` / `node -v`.
|
||||
|
||||
### 5. Configuración
|
||||
|
||||
```powershell
|
||||
copy config.example.yaml config.yaml
|
||||
notepad config.yaml
|
||||
```
|
||||
|
||||
Cambia al menos `channel_url` (URL `/videos` de tu canal). Referencia de todas las claves: [CONFIG.md](CONFIG.md).
|
||||
|
||||
### 6. Cookies (recomendado)
|
||||
|
||||
Sin cookies funciona, pero con sesión de YouTube reduce los bot-checks y desbloquea vídeos de membresía. Resumen: exporta `cookies.txt` desde tu navegador con la extensión "Get cookies.txt LOCALLY" (logueado a youtube.com) y arrástralo a la webapp, o usa `--cookies`. Guía completa: [COOKIES.md](COOKIES.md).
|
||||
|
||||
### 7. Primer scrape (sin descargar nada)
|
||||
|
||||
```powershell
|
||||
.venv\Scripts\activate # si usaste venv; con uv: uv run yt-scraper ...
|
||||
yt-scraper scrape --dry-run --limit 10
|
||||
yt-scraper scrape --limit 3 # primeras 3 notas en data/markdown/<Canal>/
|
||||
```
|
||||
|
||||
### 8. Arrancar la webapp
|
||||
|
||||
Doble clic en `start-server.bat`. La primera vez pasa por `scripts/doctor.ps1`, que instala lo que falte (Python 3.12 vía winget + `pip install -e ".[web]"`) y delega en `scripts/start-server.ps1`: busca puerto libre (8000–8100), arranca uvicorn, registra el PID en `.run/server.info`, comprueba `/healthz` y abre el navegador. Para parar: `stop-server.bat`.
|
||||
|
||||
Manual (debug): `python -m uvicorn yt_scraper.webapp.app:app --host 127.0.0.1 --port 8000`.
|
||||
|
||||
## macOS (Apple Silicon)
|
||||
|
||||
### 1. Homebrew + Python
|
||||
|
||||
```bash
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
brew install [email protected] ffmpeg node
|
||||
```
|
||||
|
||||
Todas las dependencias Python publican wheels arm64; no hay compilación.
|
||||
|
||||
### 2-3. Código y entorno
|
||||
|
||||
```bash
|
||||
git clone <URL-del-gitea> yt-channel-scraper
|
||||
cd yt-channel-scraper
|
||||
|
||||
# Opción A: uv
|
||||
brew install astral-sh.uv && uv sync --all-extras
|
||||
|
||||
# Opción B: venv + pip
|
||||
python3.12 -m venv .venv && source .venv/bin/activate
|
||||
pip install -e ".[dev,web,analysis]"
|
||||
```
|
||||
|
||||
### 4. ffmpeg / node
|
||||
|
||||
Ya instalados en el paso 1 (si los saltaste: `brew install ffmpeg node`).
|
||||
|
||||
### 5-6. Config y cookies
|
||||
|
||||
```bash
|
||||
cp config.example.yaml config.yaml
|
||||
$EDITOR config.yaml # cambia channel_url
|
||||
```
|
||||
|
||||
Cookies: [COOKIES.md](COOKIES.md).
|
||||
|
||||
### 7. Primer scrape
|
||||
|
||||
```bash
|
||||
yt-scraper scrape --dry-run --limit 10
|
||||
yt-scraper scrape --limit 3
|
||||
```
|
||||
|
||||
### 8. Arrancar la webapp
|
||||
|
||||
```bash
|
||||
make setup # primera vez: scripts/bootstrap.sh prepara todo lo que falte
|
||||
make serve # arranca uvicorn y abre el navegador
|
||||
make stop # para el servidor
|
||||
```
|
||||
|
||||
Equivalente sin Makefile: `scripts/bootstrap.sh && scripts/start-server.sh` / `scripts/stop-server.sh`.
|
||||
|
||||
## Linux (Debian/Ubuntu)
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install -y python3 python3-venv python3-pip git ffmpeg nodejs # nodejs si el repo lo empaqueta; si no, usa nodesource
|
||||
```
|
||||
|
||||
El resto es idéntico a macOS: `git clone` → `uv sync --all-extras` (o venv + `pip install -e ".[dev,web,analysis]"`) → `cp config.example.yaml config.yaml` → `yt-scraper scrape --dry-run` → `make serve`. En distros sin `make`: `scripts/bootstrap.sh` + `scripts/start-server.sh`.
|
||||
|
||||
Si tu distro trae Python < 3.10, instala uno moderno (pyenv, deadsnakes PPA en Ubuntu, o `brew` en Linux) — el paquete exige `>=3.10`.
|
||||
|
||||
## Verificación final
|
||||
|
||||
```bash
|
||||
uv run python -m pytest -q # debe pasar la suite completa (~240 tests, sin red)
|
||||
yt-scraper channels list # tras el primer scrape: tu canal con sus vídeos
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Síntoma | Causa | Arreglo |
|
||||
|---|---|---|
|
||||
| `ModuleNotFoundError: yt_scraper` tras mover/renombrar el repo | La instalación editable apunta a la ruta vieja | `pip install -e ".[dev,web,analysis]"` otra vez (o recrea el venv: `uv sync --all-extras`) |
|
||||
| `yt-scraper: command not found` | Venv sin activar, o instalaste sin `-e` | Activa el venv, o usa `uv run yt-scraper ...`, o `python -m yt_scraper.cli` |
|
||||
| Los paths apuntan a sitios raros (`data/` vacío en otro lado) | Comandos ejecutados fuera de la raíz del repo | `cd` a la raíz; las rutas son relativas al CWD |
|
||||
| `file cannot be loaded because running scripts is disabled` al lanzar un `.ps1` | PowerShell ExecutionPolicy restringido | `powershell -ExecutionPolicy Bypass -File scripts\start-server.ps1`, o `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` |
|
||||
| "puerto ocupado" / el navegador abre otra app | Resto de un servidor anterior en el puerto | Borra `.run/server.info` (estado obsoleto) o usa `stop-server.bat` / `make stop`; el arranque busca puerto libre 8000–8100 |
|
||||
| `uv: command not found` o trampolines rotos tras actualizar uv/Python | Los shims del venv quedaron inconsistentes | Ejecuta vía módulo: `uv run python -m pytest -q`, `python -m yt_scraper.cli` |
|
||||
| Tests de red fallan / scrape con muchos `error` seguidos | Rate-limit de YouTube (sin cookies es más frecuente) | Espera; revisa `delay` en [CONFIG.md](CONFIG.md); añade cookies ([COOKIES.md](COOKIES.md)) |
|
||||
| `ffmpeg no encontrado` en `yt-scraper audio` | ffmpeg no está en PATH | `winget install Gyan.FFmpeg` / `brew install ffmpeg` / `apt install ffmpeg`, y reabre la terminal |
|
||||
Reference in New Issue
Block a user