1

Home

husbando_enjoyer edited this page 2026-01-18 17:37:02 +01:00

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.
  • #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