Complete TASK-073 provider env runbook

README.md

@@ -77,6 +77,20 @@ El repositorio ya incluye:
 - `docker-compose.yml`
 - `backend/.env.example`
 
+Selección de proveedor por entorno hoy:
+
+- desarrollo:
+  - `HLL_BACKEND_LIVE_DATA_SOURCE=a2s`
+  - `HLL_BACKEND_HISTORICAL_DATA_SOURCE=public-scoreboard`
+- producción realista en esta fase:
+  - `HLL_BACKEND_LIVE_DATA_SOURCE=rcon`
+  - `HLL_BACKEND_HISTORICAL_DATA_SOURCE=public-scoreboard`
+
+Esto refleja el estado real de la repo: el proveedor RCON ya existe para el
+estado live de `/api/servers`, pero el histórico sigue dependiendo del
+scoreboard público porque no hay todavía una canalización persistente basada
+en eventos/logs RCON.
+
 Primer arranque:
 
 ```powershell
@@ -113,6 +127,50 @@ Recreacion de imagenes tras cambios:
 docker compose up --build
 ```
 
+## Runbook de proveedores
+
+Verificacion minima del proveedor activo:
+
+```powershell
+Invoke-WebRequest http://localhost:8000/health | Select-Object -Expand Content
+```
+
+La respuesta incluye `live_data_source` y `historical_data_source`.
+
+Modo desarrollo recomendado:
+
+```powershell
+docker compose up --build
+```
+
+Modo live con RCON en Docker Compose:
+
+```powershell
+$env:HLL_BACKEND_LIVE_DATA_SOURCE='rcon'
+$env:HLL_BACKEND_HISTORICAL_DATA_SOURCE='public-scoreboard'
+$env:HLL_BACKEND_RCON_TARGETS='[
+  {
+    "name": "Comunidad Hispana #01",
+    "host": "203.0.113.10",
+    "port": 28015,
+    "password": "replace-me",
+    "external_server_id": "comunidad-hispana-01",
+    "region": "ES",
+    "game_port": 7777,
+    "query_port": 7778
+  }
+]'
+docker compose up -d backend frontend
+```
+
+Buenas practicas:
+
+- no versionar credenciales reales en `backend/.env.example`
+- preferir exportarlas como variables de entorno del host o del secreto del
+  despliegue
+- mantener `HLL_BACKEND_HISTORICAL_DATA_SOURCE=public-scoreboard` hasta tener
+  una ingesta historica RCON realmente persistida
+
 ## Operaciones historicas con Docker
 
 Refresh historico puntual dentro del contenedor backend:

ai/tasks/done/TASK-073-env-selection-docker-and-runbook-for-rcon.md

@@ -0,0 +1,73 @@
+# TASK-073-env-selection-docker-and-runbook-for-rcon
+
+## Goal
+Dejar documentado y operativo el cambio de fuente por entorno, incluyendo Docker/Compose y el runbook necesario para usar public-scoreboard en desarrollo y RCON en producción.
+
+## Context
+Una vez exista la capa de abstracción y el proveedor RCON, hace falta cerrar la parte operativa:
+- variables de entorno
+- selección de proveedor
+- Docker/Compose
+- documentación clara para desarrollo y despliegue
+
+## Steps
+1. Revisar el estado final de la abstracción y de ambos proveedores.
+2. Documentar claramente:
+   - modo dev con public-scoreboard
+   - modo prod con RCON
+3. Añadir o ajustar la configuración Docker/Compose necesaria para seleccionar proveedor por entorno.
+4. Documentar variables sensibles y buenas prácticas para no versionar credenciales.
+5. Asegurar que el runbook cubra:
+   - arranque en dev
+   - arranque en Docker
+   - despliegue en prod con RCON
+   - verificación básica de qué proveedor está activo
+6. No convertir esta task en una guía de infraestructura final completa.
+7. Mantener la documentación realista y alineada con lo implementado.
+8. Al completar la implementación:
+   - dejar el repositorio consistente
+   - hacer commit
+   - hacer push al remoto si el entorno lo permite
+
+## Files to Read First
+- AGENTS.md
+- README.md
+- backend/README.md
+- docker-compose.yml
+- backend/app/config.py
+- backend/app/source_provider.py
+- backend.env.example
+
+## Expected Files to Modify
+- README.md
+- backend/README.md
+- docker-compose.yml
+- backend.env.example o archivo equivalente
+- opcionalmente docs/rcon-production-mode.md
+
+## Constraints
+- No documentar infraestructura inexistente.
+- No exponer credenciales reales.
+- No hacer cambios destructivos.
+- Mantener el trabajo centrado en selección por entorno y runbook.
+
+## Validation
+- La documentación explica con claridad cómo usar dev vs prod.
+- Docker/Compose refleja la selección por entorno de forma razonable.
+- Queda claro cómo verificar qué proveedor está activo.
+- Los cambios quedan committeados y se hace push si el entorno lo permite.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados o creados.
+- Preferir menos de 220 líneas cambiadas.
+
+## Outcome
+- Se anadieron las variables de seleccion de proveedor y placeholders RCON a `backend/.env.example`.
+- `docker-compose.yml` ahora propaga explicitamente la seleccion de proveedor y la configuracion RCON para backend e historical-runner.
+- `README.md` y `backend/README.md` incluyen un runbook realista para dev, Docker y live con RCON.
+- La verificacion operativa recomendada queda apoyada en `/health`, que expone los proveedores activos.
+
+## Validation Notes
+- `docker compose config` resolvio correctamente la configuracion final.
+- La documentacion mantiene el limite actual del producto: RCON solo para live y `public-scoreboard` para historico.
+- No se documentaron credenciales reales ni infraestructura no implementada en la repo.

backend/.env.example

@@ -3,6 +3,10 @@ HLL_BACKEND_PORT=8000
 HLL_BACKEND_STORAGE_PATH=/app/data/hll_vietnam_dev.sqlite3
 HLL_BACKEND_ALLOWED_ORIGINS=http://127.0.0.1:8080,http://localhost:8080
 HLL_BACKEND_REFRESH_INTERVAL_SECONDS=120
+HLL_BACKEND_LIVE_DATA_SOURCE=a2s
+HLL_BACKEND_HISTORICAL_DATA_SOURCE=public-scoreboard
+HLL_BACKEND_RCON_TIMEOUT_SECONDS=10
+HLL_BACKEND_RCON_TARGETS=
 HLL_HISTORICAL_CRCON_PAGE_SIZE=50
 HLL_HISTORICAL_CRCON_TIMEOUT_SECONDS=15
 HLL_HISTORICAL_CRCON_DETAIL_WORKERS=8

backend/README.md

@@ -316,6 +316,25 @@ $env:HLL_BACKEND_RCON_TARGETS='[
 ]'
 ```
 
+Runbook operativo minimo:
+
+- desarrollo:
+  - `HLL_BACKEND_LIVE_DATA_SOURCE=a2s`
+  - `HLL_BACKEND_HISTORICAL_DATA_SOURCE=public-scoreboard`
+- produccion live con RCON:
+  - `HLL_BACKEND_LIVE_DATA_SOURCE=rcon`
+  - `HLL_BACKEND_HISTORICAL_DATA_SOURCE=public-scoreboard`
+  - definir `HLL_BACKEND_RCON_TARGETS` fuera de la repo
+
+Verificacion minima del proveedor activo:
+
+```powershell
+Invoke-WebRequest http://127.0.0.1:8000/health | Select-Object -Expand Content
+```
+
+La respuesta incluye `live_data_source` y `historical_data_source`, util para
+confirmar si la instancia esta usando `a2s` o `rcon` para live.
+
 ## Criterio de estructura
 
 - `__init__.py` declara el paquete `app` y reexporta las utilidades publicas

docker-compose.yml

@@ -5,6 +5,11 @@ services:
     container_name: hll-vietnam-backend
     env_file:
       - ./backend/.env.example
+    environment:
+      HLL_BACKEND_LIVE_DATA_SOURCE: ${HLL_BACKEND_LIVE_DATA_SOURCE:-a2s}
+      HLL_BACKEND_HISTORICAL_DATA_SOURCE: ${HLL_BACKEND_HISTORICAL_DATA_SOURCE:-public-scoreboard}
+      HLL_BACKEND_RCON_TIMEOUT_SECONDS: ${HLL_BACKEND_RCON_TIMEOUT_SECONDS:-10}
+      HLL_BACKEND_RCON_TARGETS: ${HLL_BACKEND_RCON_TARGETS:-}
     ports:
       - "8000:8000"
     volumes:
@@ -18,6 +23,11 @@ services:
     command: ["python", "-m", "app.historical_runner", "--hourly"]
     env_file:
       - ./backend/.env.example
+    environment:
+      HLL_BACKEND_LIVE_DATA_SOURCE: ${HLL_BACKEND_LIVE_DATA_SOURCE:-a2s}
+      HLL_BACKEND_HISTORICAL_DATA_SOURCE: ${HLL_BACKEND_HISTORICAL_DATA_SOURCE:-public-scoreboard}
+      HLL_BACKEND_RCON_TIMEOUT_SECONDS: ${HLL_BACKEND_RCON_TIMEOUT_SECONDS:-10}
+      HLL_BACKEND_RCON_TARGETS: ${HLL_BACKEND_RCON_TARGETS:-}
     depends_on:
       - backend
     volumes: