Guía de inicio (Alex) — español¶

Página de empezar aquí para el equipo. Sitio de documentación: docs.rafaelgonzalezalbes.com

English version

Qué es esta plataforma¶

Rafael montó un DevOps self-hosted en un VPS (servidor en la nube). En lugar de GitHub + GitHub Actions + Jira, usamos:

Herramienta	URL	Para qué
Forgejo	git.rafaelgonzalezalbes.com	Git, repos, pull requests
Woodpecker	ci.rafaelgonzalezalbes.com	CI/CD — tests y deploy automático
Plane	pm.rafaelgonzalezalbes.com	Tickets, Kanban, sprints
Uptime Kuma	status.rafaelgonzalezalbes.com	Monitorización de servicios
Docs	docs.rafaelgonzalezalbes.com	Esta documentación
Portfolio público	rafaelgonzalezalbes.com	Web pública (IONOS)

Solo Rafael y Alex tienen cuenta. El registro público está desactivado.

URLs que debes guardar¶

Servicio	URL	Cómo entrar
Documentación	docs.rafaelgonzalezalbes.com	Sin login (URL del equipo, no indexada en Google)
Git	git.rafaelgonzalezalbes.com	Usuario `alex` + tu contraseña
CI	ci.rafaelgonzalezalbes.com	Sign in with Forgejo (misma cuenta `alex`)
Issues	pm.rafaelgonzalezalbes.com	Invitación por email de Rafael
Monitorización	status.rafaelgonzalezalbes.com	Login (Rafael te da credenciales)
Web pública	rafaelgonzalezalbes.com	Público

Tu acceso y permisos¶

Área	Tu rol
Organización Forgejo `infra`	Admin — repo de plataforma `infra/devops`
Organización Forgejo `bioscan`	Admin — repos de producto (ej. `bioscancheck`)
Repo `rafael.gonzalez.albes/portfolio`	Escritura + revisar PRs
Woodpecker	Admin (con Rafael) — ver todos los pipelines
Plane workspace `rafael-gonzalez-albes`	Miembro — crear y mover tickets
SSH al VPS	Opcional — usuario Linux `alex.rodriguez.vera` si Rafael configuró tu clave

Haz esto una sola vez:

Forgejo — git.rafaelgonzalezalbes.com, usuario alex. Debes ver las orgs infra y bioscan y el repo portfolio.
Woodpecker — ci.rafaelgonzalezalbes.com → Sign in with Forgejo → autorizar. Debes ver infra/devops y rafael.gonzalez.albes/portfolio.
Plane — aceptar invitación. Proyecto Portfolio: tickets PORT. Prefijo PORT (ej. PORT-12).
Uptime Kuma — status.rafaelgonzalezalbes.com — revisar monitores (git, ci, pm, docs, web).

CI falla al clonar repo privado

Si Woodpecker falla en el paso clone (código 128), avisa a Rafael. Suele arreglarse refrescando OAuth y el flag private del repo.

Flujo de trabajo diario¶

flowchart LR
  Plane[Ticket Plane PORT-N] --> Rama["rama feature/PORT-N-descripcion"]
  Rama --> PR[PR en Forgejo]
  PR --> CI[Woodpecker build + test]
  CI -->|merge a main| Deploy[SFTP a IONOS]
  CI -->|comentario| Plane

Pasos¶

Crear o elegir ticket en Plane (PORT-… para portfolio, BIOS-… para BioScanCheck en el futuro).
Rama: feature/PORT-42-descripcion-corta
Push a Forgejo, abrir PR, título: [PORT-42] Resumen corto
Esperar Woodpecker en verde en el PR.
Merge a main → el portfolio se despliega solo en rafaelgonzalezalbes.com.
En el commit de merge: fixes PORT-42 para cerrar el ticket.

Reglas completas: Team workflow (inglés).

Columnas Kanban (Plane)¶

Backlog → Ready → In Progress → In Review → CI Green → QA → Done

Columna	Significado
In Review	PR abierto
CI Green	Woodpecker pasó
Done	Mergeado y desplegado

Repositorios para clonar¶

# Portfolio (React + Vite) — app principal con CI activo
git clone https://git.rafaelgonzalezalbes.com/rafael.gonzalez.albes/portfolio.git

# Plataforma DevOps (docs, scripts, docker) — consultar con Rafael antes de cambiar
git clone https://git.rafaelgonzalezalbes.com/infra/devops.git

# BioScanCheck — código del producto (CI/CD pendiente)
git clone https://git.rafaelgonzalezalbes.com/bioscan/bioscancheck.git

Usuario/contraseña de Forgejo, o clave SSH en Forgejo → Settings → SSH keys.

Configuración en tu PC¶

Mínimo (trabajar en portfolio)¶

cd portfolio
npm install
npm run dev          # http://localhost:5173
npm test
npm run lint

Opcional — scripts de plataforma (Windows + WSL)¶

cd infra-devops
cp local/.env.example local/.env   # Rafael rellena secretos — no commitear
bash scripts/setup-local-ssh.sh    # añade host ssh bioscan-vps
ssh bioscan-vps                      # comprobar servidor

Opcional — Cursor MCP (agentes IA)¶

Permite a Cursor crear tickets, listar PRs, ver logs de CI. Ver MCP overview.

Clonar infra/devops
Copiar templates/cursor-mcp.json.example → .cursor/mcp.json
Tokens API en local/.env (Rafael te los pasa — no en git)
npm run mcp:build --prefix mcp-server

Contraseñas y secretos — resumen¶

Hay dos tipos de credenciales. Detalle completo: Secrets & connections (también con resumen en español al final).

Contraseñas de usuario (tú en el navegador)¶

App	Usuario	Dónde se guarda
Forgejo	`alex`	Base de datos Forgejo en el VPS (hash)
Plane	tu email	Base de datos Plane
Kuma	tu usuario	SQLite en el VPS
Woodpecker	—	Sin contraseña — entras con Forgejo OAuth

No están en git.

Secretos de máquina (CI y deploy)¶

Qué	Dónde
SFTP IONOS, API Plane para CI	Woodpecker → secretos del repo portfolio
SSH deploy + clave SOPS plataforma	Woodpecker → secretos del repo `infra/devops` (solo Rafael configura)
Tokens para scripts locales	`local/.env` en el PC (gitignored)
OAuth plataforma, bridge Plane↔Forgejo	Archivos cifrados `secrets/*.enc.env` en git (SOPS)

Qué tienes tú vs qué tiene Rafael¶

	Alex	Rafael
Login Forgejo / Plane / Kuma	Sí	Sí
Push código, PRs, ver CI	Sí	Sí
Clave age / SOPS (deploy plataforma)	No	Sí
Contraseña SFTP IONOS en Woodpecker	No (CI ya la tiene)	Sí

Puedes desarrollar sin conocer la contraseña SFTP — Woodpecker la usa en el pipeline.

Reglas de seguridad¶

Nunca commitear .env, contraseñas, claves SSH.
Nunca pegar secretos en chat o tickets.
Token personal Forgejo (para MCP): Forgejo → Settings → Applications.

Cómo se conectan las aplicaciones¶

flowchart TB
  subgraph tu_pc [Tu PC]
    Dev[Alex / Rafael]
    Cursor[Cursor + MCP]
  end

  subgraph vps [VPS]
    T[Traefik HTTPS]
    Git[Forgejo]
    CI[Woodpecker]
    PM[Plane]
    Bridge[plane-forge-bridge]
  end

  IONOS[IONOS hosting web]

  Dev -->|login| T
  T --> Git & CI & PM
  Dev -->|OAuth| CI
  CI -->|clona repos| Git
  CI -->|SFTP deploy| IONOS
  CI -->|comentarios CI| PM
  Git <-->|webhooks| Bridge
  PM <-->|webhooks| Bridge
  Cursor -->|OAuth / API| PM & Git & CI

Conexión	Cómo
Tú → Git / CI / Plane	HTTPS + tu contraseña (o OAuth para CI)
Woodpecker → Forgejo	Token OAuth al clonar repos privados
Woodpecker → IONOS	Secretos SFTP en Woodpecker
Woodpecker → Plane	Script `notify-plane-ci.sh` + API key en secretos
Forgejo ↔ Plane	Servicio `bridge` — sincroniza PRs y estados
Cursor → herramientas	MCP con tokens en tu PC

Qué está vivo hoy¶

Proyecto	CI/CD	Deploy	Prefijo Plane
Portfolio	Sí — verde en `main`	IONOS → web pública	`PORT`
infra/devops	Sí — auto-deploy plataforma	VPS `/opt/devops`	—
BioScanCheck	Planificado	VPS + IONOS después	`BIOS`

Qué revisar en esta documentación¶

Página	Para qué
Secrets & connections	Contraseñas, secretos, conexiones entre apps
Team workflow	Ramas, PRs, CI
Access control	Público vs privado
Portfolio	Cómo se despliega el portfolio
Monitoring	Uptime Kuma

Comprobaciones:

[ ] La búsqueda y el menú lateral funcionan
[ ] Los diagramas Mermaid se ven
[ ] Los enlaces a git, ci, pm abren bien
[ ] Esta página en español se lee bien

Ayuda¶

Necesitas	Contacta
Login Forgejo / Woodpecker / Plane	Rafael
Secretos Woodpecker, SFTP, SSH VPS	Rafael
Invitación Plane	Rafael
CI roto tras cambio de infra	Rafael — o Access control