Añadir Home

Home.md

@@ -0,0 +1,81 @@
+1) Arquitectura rapida
+- El frontend se sirve bajo base path `/taller/` (ver `frontend/vite.config.js`).
+- nginx del frontend proxy a backend para `/taller/api/` (ver `frontend/nginx.conf`).
+- Backend expone `/health` y `/builds` (ver `backend/app/main.py`).
+- `/builds` consulta Jenkins usando `JENKINS_BASE_URL` + `JENKINS_JOB_NAME` (ver `backend/app/services/builds.py`).
+ 2) Puesta en marcha (docker compose)
+1. Copiar entorno:
+   - `cp .env.example .env`
+2. Levantar stack:
+   - `docker compose up --build`
+3. Comprobar:
+   - `http://localhost:8000/health`
+   - `http://localhost:8081/taller/`
+  
+Notas:
+- `docker-compose.yml` publica backend en `8000:8000` y frontend en `8081:8081`.
+- La red docker esta configurada con IPv6 (subnet `2001:db8::/64`); porque el VPS pues tal, solo soporta IPv6.
+
+ 3) Configuración de entorno (local vs VPS)
+- Con modificar los parámetros es suficiente, en el Job de CD están los parámetros de builds, no se puede lanzar una ejecución manualmente sin revisar estos parámetros. En caso de que el job se lance por Webhook, toma los parámetros por defecto, que son los del VPS.
+
+Variables:
+- `VITE_API_BASE`
+  - Recomendado: mantener `/taller/api` para que nginx proxye al backend.
+  - En build de frontend se inyecta vía build arg (ver `frontend/Dockerfile` y `docker-compose.yml`).
+- `JENKINS_BASE_URL`
+  - Local (ejemplo): `http://host.docker.internal:8080`
+  - VPS: `https://openbokeron.org/jenkins`
+- `JENKINS_JOB_NAME`
+  - Nombre del job en Jenkins que el backend consultará en `/builds`.
+- `JENKINS_USER` / `JENKINS_TOKEN`
+  - Si no están configurados, el backend intentará consultar sin Authorization (ver `backend/app/services/builds.py`).
+Comportamiento esperado en errores:
+- Si Jenkins no responde o falta config, `/builds` devuelve `503` con `{ "builds": [], "error": "jenkins_unavailable" }` (ver `backend/app/main.py`).
+
+ 4) CI (Jenkinsfile.ci)
+Archivo: `Jenkinsfile.ci`
+
+Hace:
+- Init: detecta autor y short commit para logging.
+- Backend: `ruff check` + `pytest` dentro de `python:3.11-slim`.
+  - Usa cachés dentro del workspace (`.cache/pip`, `.cache/pytest`) y `PYTHONDONTWRITEBYTECODE=1`.
+- Frontend: `npm install` + `npm run check` + `npm run build` dentro de `node:20-slim`.
+  - Usa cache en `.cache/npm`.
+- Post: `cleanWs()` siempre.
+
+Trazabilidad:
+- Problema de limpieza de workspace: issue #11 y solución vinculada a PR #20:
+
+
+ 5) CD / Deploy (Jenkinsfile.cd)
+Archivo: `Jenkinsfile.cd`
+Parámetros del job:
+- `JENKINS_BASE_URL`
+- `JENKINS_JOB_NAME`
+- `VITE_API_BASE`
+Hace:
+- Backend tests (python 3.11 slim).
+- Build imagenes:
+  - Backend: inyecta `APP_VERSION`, `GIT_COMMIT`, `COMMIT_AUTHOR`, `BUILD_NUMBER` como build args (ver `backend/Dockerfile`).
+  - Frontend: inyecta `VITE_API_BASE` en build (ver `frontend/Dockerfile`).
+- Deploy:
+  - Lanza `docker compose up -d` con `BACKEND_TAG` y `FRONTEND_TAG` = `APP_VERSION`.
+  - Inyecta credenciales `JENKINS_USER/JENKINS_TOKEN` desde Jenkins credentials (`jenkins-api-token`) para que el backend pueda consultar Jenkins API en runtime.
+
+ 6) Webhooks (Gitea -> Jenkins)
+Objetivo:
+- Disparar CI y/o CD automáticamente.
+
+Estado según issue #15:
+- Webhook de deploy en `main` anadido; CI en el resto de ramas estaba pendiente en ese momento.
+  - https://openbokeron.uma.es/gitea/OpenBokeron/TallerCiCd/issues/15
+Checklist de configuracion (generico):
+- Evento: push a `main` para CD (y PR/push para CI si se quiere).
+- URL: endpoint de Jenkins para disparar el job (segun plugin/config).
+- Secret: si se usa, guardarlo como secreto (no en la wiki).
+
+ 7) Troubleshooting rápido
+- “El Jenkinsfile que se ejecuta no es el de mi rama”
+  - Puede ser intencional por seguridad (ver `Seguridad`): se fuerza a usar Jenkinsfile de `main` con Remote Jenkinsfile Provider. 
+  - Referencia: comentario en PR #21