Engineering Handbook

Handbook de estudio técnico — 35 categorías (Docker, Kubernetes, Terraform, Observabilidad, System Design, Bases de datos, Redes, y más), servidas por una app propia con buscador full-text y navegación secuencial entre temas.

Ver en vivo →

Por qué este repo es más que contenido

Este no es un sitio estático — es un caso real de CI/CD de punta a punta, con tres entornos desplegados de verdad (no un diagrama teórico):

• develop: preview rápido en Docker, con state de Terraform en Terraform Cloud.
• staging/production: Kubernetes (k3s), con RBAC acotado por Service Account y namespaces aislados por entorno.
• Cada entorno con su propio workspace de Terraform Cloud (nunca compartido — evita colisión de state entre entornos).
• RBAC separado en capa de bootstrap: el CI nunca tiene permisos para gestionar su propio RBAC (evita escalación de privilegios).
• Gate manual real antes de producción: main protegido, solo se actualiza mergeando un Pull Request.
• Build + push de imagen automatizado en cada deploy (GitHub Actions, tag por commit SHA — no latest, así cada entorno es trazable a un commit exacto).

flowchart TB
    devpush["push a develop"] --> devwf["Docker + Terraform Cloud<br/>(VM independiente)"]
    stgpush["push a staging"] --> k8s["Kubernetes (k3s)<br/>namespace + workspace propio"]
    prmerge["merge de PR a main"] --> prodk8s["Kubernetes (k3s)<br/>namespace + workspace propio, aislado de staging"]

    bootstrap["RBAC (bootstrap manual,<br/>kubeconfig admin)"] -. acota permisos .-> k8s
    bootstrap -. acota permisos .-> prodk8s

Loading

La arquitectura completa — topología del cluster, mapa de las 7 credenciales usadas y su alcance exacto, el flujo mecánico de un deploy paso a paso, y los incidentes reales resueltos en el camino — está documentada como un capítulo más del handbook: 35-Implementation-Map.

Tecnologías involucradas

Frontend / App Next.js (App Router) · TypeScript · React · Tailwind CSS · Fuse.js (búsqueda) · remark/rehype (pipeline de markdown) · Mermaid.js (diagramas)

Infraestructura como código Terraform · Terraform Cloud (state remoto, workspaces por entorno)

Contenedores y orquestación Docker · Docker Compose · Kubernetes (k3s) · GitHub Container Registry (GHCR)

CI/CD GitHub Actions · runners self-hosted · branch protection como gate de release

Seguridad y control de acceso RBAC de Kubernetes (ServiceAccounts, Roles, RoleBindings) acotado por namespace · separación de capas bootstrap (admin) vs. deploy (CI) para evitar escalación de privilegios

Sistemas y redes Linux (RHEL family) · systemd · cloud-init · Flannel (CNI) · NodePort / exposición de servicios

Correrlo local

docker compose up --build

Sirve en http://localhost:3333, leyendo content/ en cada request.

Estructura

• content/ — las 35 categorías, un .md por tema.
• web/ — la app (Next.js).
• infra/ — Terraform del preview en Docker (develop).
• infra-k8s/ — Terraform del deploy en Kubernetes, lo aplica el CI (identidad acotada).
• infra-k8s-bootstrap/ — RBAC y namespaces del cluster, aplicado a mano por un admin — nunca por el CI.

Roadmap

Observabilidad (OpenTelemetry + Prometheus + Grafana) planeada como próxima capa — detalle del plan en el propio Implementation Map.