diff --git a/README.md b/README.md index d73d093..b839df1 100644 --- a/README.md +++ b/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: diff --git a/ai/tasks/done/TASK-073-env-selection-docker-and-runbook-for-rcon.md b/ai/tasks/done/TASK-073-env-selection-docker-and-runbook-for-rcon.md new file mode 100644 index 0000000..024f74f --- /dev/null +++ b/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. diff --git a/backend/.env.example b/backend/.env.example index 19d01a2..ea8390e 100644 --- a/backend/.env.example +++ b/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 diff --git a/backend/README.md b/backend/README.md index 1391377..9f1ea8c 100644 --- a/backend/README.md +++ b/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 diff --git a/docker-compose.yml b/docker-compose.yml index aee3860..81da411 100644 --- a/docker-compose.yml +++ b/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: