# 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 python@3.12 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 |