Skip to content

Onboarding

Jump to bottom
AnderProgramming edited this page Jul 17, 2026 · 1 revision

Guía de "primer día" para un nuevo integrante del equipo: cómo clonar, correr localmente, entender la arquitectura, hacer un cambio y abrir un PR. Para el detalle de cada pieza, esta página enlaza a las páginas especializadas de la wiki en vez de repetir su contenido.

1. Clonar y correr localmente

git clone https://1.n-la-c.app/repo-github
cd linker1
mvn -q clean package -DskipTests
LD_OFFLINE=true LINKER_PORT=8080 java -jar target/linker1-1.0-jar-with-dependencies.jar
  • LD_OFFLINE=true evita que la app falle al arrancar por falta de LD_SDK_KEY (ver Feature Flags) — sin una key real de LaunchDarkly, todos los flags evalúan a su valor por defecto.
  • Sin MYSQL_* configurado, /healthz responderá 503 (esperado en local) pero el resto de la app funciona con normalidad — el healthcheck es exclusivamente contra MySQL, no contra el almacenamiento real (SQLite). Ver Observability.
  • Sin OTEL_EXPORTER_OTLP_ENDPOINT, la telemetría se genera igual pero no se exporta a ningún lado (degradación silenciosa por diseño) — ver Postmortem #1 para por qué esto importa.
  • Prueba rápida: curl -s http://localhost:8080/ (200), y curl -s -X POST http://localhost:8080/link -H 'Content-Type: application/json' -d '{"url":"https://example.com"}' debería devolver un id de 8 caracteres.

2. Correr los tests

mvn test
mvn jacoco:report && start target/site/jacoco/index.html   # cobertura, en Windows

El pipeline exige 100% de líneas cubiertas (ver Testing Strategy) — cualquier línea nueva sin test hará fallar mvn verify en CI, no solo mvn test.

3. Entender la arquitectura antes de tocar código

Orden recomendado de lectura para alguien nuevo:

  1. 12 Factor App — por qué el proyecto está estructurado como está (env vars, stateless, logs como stream).
  2. Cloud Architecture — dónde vive todo en OCI. Nota: esta página describe el modelo original de VM única; desde julio 2026 la producción real usa blue/green con un Load Balancer compartido — ver docs/DEPLOYMENT.md en el repo para el flujo actual y exacto.
  3. CI/CD Pipeline — qué corre en cada push/PR.
  4. Observability — cómo ver logs/métricas/traces de una instancia real.

4. Hacer un cambio: flujo de trabajo

  1. Rama desde main: git checkout -b fix/lo-que-sea o feature/lo-que-sea.
  2. TDD: test que falla primero (red), implementación mínima para pasarlo (green), refactor si hace falta.
  3. mvn test en verde localmente antes de hacer push.
  4. Push + abrir PR contra main. main tiene branch protection: 1 aprobación requerida + CI en verde antes de poder mergear (ver DevSecOps Practices).
  5. Un CODEOWNER es asignado automáticamente como reviewer.
  6. Una vez aprobado y mergeado, el deploy a producción es automático — no hay ningún paso manual en la consola de OCI para desplegar (ver la sección siguiente).

5. "0 operaciones manuales en la consola de OCI" — qué es cierto hoy

Esta es una restricción explícita del curso: cualquier cosa que un nuevo integrante necesite hacer para operar Linker1 debe tener un camino por CLI/pipeline, no un clic en la consola web de OCI. Estado real, auditado directamente contra el código (no asumido):

Operación Camino sin consola Nota
Desplegar una nueva versión Automático: push a main dispara bluegreen.yml Sin intervención humana
Crear/destruir la VM terraform apply/destroy (infra/), ejecutado por el pipeline No hay VMs creadas a mano desde la consola
Acceder a la VM (debug) oci bastion session create-managed-ssh vía OCI CLI Ver docs/DEPLOYMENT.md para el comando exacto
Rollback scripts/rollback.sh, disparado por el job rollback del pipeline Automático ante fallo de validate-prod/health check
Repuntar OCI_INSTANCE_OCID tras un deploy Gap conocido, real: gh variable set OCI_INSTANCE_OCID a mano El workflow intenta hacerlo automáticamente, pero una política a nivel de organización bloquea que GITHUB_TOKEN escriba variables del repo (403 Resource not accessible by integration, confirmado, no es un bug nuestro). El job emite un ::warning:: con el comando exacto a correr — ver docs/DEPLOYMENT.md.
Gestión de secrets gh secret set / gh variable set (GitHub CLI) No usa OCI Vault — ver DevSecOps Practices para el detalle de ese gap
Ver dashboards/métricas Grafana Cloud UI (coralavocado2395.grafana.net) Esto es observación, no operación — no cuenta contra la restricción, pero si hace falta importar el dashboard por primera vez, ese paso sí es manual (una vez) — ver Observability

El único gap operativo real hoy es el de OCI_INSTANCE_OCID de la fila de arriba, y está documentado como tal (no oculto ni presentado como "ya resuelto").

6. Dónde pedir ayuda / qué leer si algo falla

  • CI falla en un PR: revisa el job específico en GitHub Actions; CI/CD Pipeline explica qué valida cada uno.
  • Deploy falla en main: docs/DEPLOYMENT.md tiene la tabla de failure paths del blue/green y qué se limpia automáticamente en cada caso.
  • Algo se rompió en producción antes y no sabes si ya pasó: revisa Postmortems — es razonablemente probable que un incidente similar ya esté documentado ahí, con causa raíz y fix.
  • No sabes si algo es un bug tuyo o un problema de infraestructura/permisos compartida: pregunta en el canal del equipo antes de asumir — varios de los postmortems documentados aquí (política de escritura de GITHUB_TOKEN, TF_COMPARTMENT_ID) parecían bugs de código al principio y resultaron ser configuración/permisos a nivel de organización.

Clone this wiki locally