Dato 2025 (State of DevOps):
• 83% menos tiempo en onboarding
• 47% menos incidentes críticos
• 60% más rápido en resolución de problemas
• 83% menos tiempo en onboarding
• 47% menos incidentes críticos
• 60% más rápido en resolución de problemas
Formatos clave de documentación operativa
Estos son los formatos base que se vuelven tu “sistema operativo” de operaciones y DevOps:
- Servidor / dispositivo: Qué es, dónde vive, cómo se accede, cómo se cuida.
- SOP (Procedimiento Operativo Estándar): Cómo hacer algo repetible sin pensar demasiado.
- Runbook: Qué hacer cuando todo está explotando.
- Documentación de API: Cómo se habla con tu plataforma de forma estable.
- ADR: Por qué tomaste decisiones técnicas que te van a perseguir años.
- Onboarding técnico: Cómo alguien nuevo puede ser útil sin romper producción.
Formato documentación de servidores y dispositivos (plantilla extendida)
# web-prod-01
## Información básica
- Tipo: Servidor virtual (AWS EC2 t3.large)
- Rol: Frontend web / API pública
- Ambiente: Producción
- Criticidad: Alta
- Tier de servicio: Tier 1 (impacto directo en facturación)
- Ubicación: eu-west-1
- Horario pico: Lunes a domingo 18:00–23:59 (AR)
- Responsable técnico: Equipo Infra – admin@newsbm-tech.com
- Responsable funcional: Equipo Producto News – producto@newsbm-tech.com
- Stakeholders clave: CTO, Head de Producto
- Fecha creación: 15/03/2024
- Última revisión de esta documentación: 10/12/2025
## Especificaciones técnicas
- CPU: 2 vCPU
- RAM: 8 GB
- Almacenamiento: 100 GB SSD
- Sistema operativo: Ubuntu 22.04 LTS
- IP pública: 203.0.113.45
- IP privada: 10.0.12.34
- Hostname: web-prod-01.newsbm-tech.com
- Domain principal: https://newsbm-tech.com
- Balanceador de carga: ALB-prod-newsbm
- Grupo de seguridad / firewall: sg-web-prod
## Dependencias
### Dependencias internas
- Servicio: api-auth (cluster k8s prod)
- URL interna: http://api-auth.internal.svc.cluster.local
- Documentación: docs/apis/api-auth.md
- Servicio: db-main (RDS PostgreSQL 16)
- Endpoint: db-main-prod.abc123.rds.amazonaws.com
- ADR asociado: ADR-007-migracion-postgres16.md
### Dependencias externas
- Proveedor pagos: AcmePay
- Base URL: https://api.acmepay.com
- SLA contractual: 99.9 por ciento uptime
- Contacto soporte: support@acmepay.com
## Monitoreo y alertas
- Herramientas:
- Métricas: Prometheus más Grafana
- Logs: Loki más Grafana
- Alertas: Alertmanager
- Dashboards clave:
- web-prod-latency
- web-prod-errors
- web-prod-traffic
- Alertas importantes:
- 5xx mayor a 2 por ciento por 5 minutos
- Latencia p95 mayor a 800 ms por 5 minutos
- Uso de disco mayor a 80 por ciento
- Reinicios del proceso web mayores a 3 en 10 minutos
- Rutas de healthcheck:
- Nginx: https://newsbm-tech.com/health
- Aplicación: https://newsbm-tech.com/internal/health
## Puertos abiertos
| Puerto | Protocolo | Servicio | Notas |
|--------|-----------|----------------|---------------------------------|
| 22 | TCP | SSH | Solo claves RSA; sin root login |
| 80 | TCP | HTTP a HTTPS | Redirección forzada |
| 443 | TCP | HTTPS Nginx | Certificado Let's Encrypt |
## Seguridad
- Acceso SSH:
- Usuario: ubuntu
- Autenticación: solo clave privada
- Doble factor en consola AWS: obligatorio
- Actualizaciones:
- Parches de seguridad: semanal
- Actualización de kernel: coordinada con ventana de mantenimiento
- Backups:
- Snapshots de EBS: diarios 02:00 UTC, retención 7 días
- Verificación de restore: trimestral
## Acceso (credenciales siempre guardadas en 1Password)
- SSH: usuario ubuntu más clave privada
- Consola AWS: https://console.aws.amazon.com/ec2/
- Acceso de solo lectura:
- Usuario: web-prod-reader
- Permisos: logs más métricas
## Procedimientos comunes
### Reinicio seguro del servicio web
1. Anunciar en canal de Slack #infra:
- "Reinicio web-prod-01 por mantenimiento, impacto cero si balanceador en verde"
2. Conectarse por SSH:
- ssh ubuntu@203.0.113.45
3. Verificar estado previo:
- systemctl status nginx
4. Aplicar reinicio controlado:
- sudo systemctl restart nginx
5. Verificar healthcheck:
- curl -I https://newsbm-tech.com/health
6. Si todo está ok:
- Registrar en canal #infra con hora y motivo
### Reinicio completo del host
1. Validar:
- No hay despliegues en curso
- No hay incidentes abiertos SEV-1 o SEV-2
2. Ejecutar:
- sudo reboot
3. Verificar que el host vuelve y se registra en sistema de monitoreo
4. Confirmar que el balanceador marca el target como healthy
## Comandos útiles
- Ver uso de disco:
- df -h
- Ver procesos ordenados por consumo CPU:
- top o htop
- Ver últimos logs de Nginx:
- journalctl -u nginx -n 100
- Ver errores de aplicación:
- docker logs web-app --tail 200
## Riesgos conocidos
- Tráfico se dispara durante grandes eventos deportivos
- Dependencia fuerte de AcmePay; si cae, se frena facturación
- Build de frontend pesado, puede impactar tiempos de despliegue
## Historial de cambios relevantes
- 2025-01-10: Migración a PostgreSQL 16 (ver ADR-007)
- 2024-11-02: Cambio de Nginx a ALB como balanceador principal
- 2024-08-21: Activación de TLS 1.2 como mínimoPlantilla SOP (Procedimiento Operativo Estándar) – extendida
# SOP-DEPLOY-PROD: Despliegue a Producción
## Metadatos
- Sistema o servicio: Plataforma NewsBM Tech
- Entorno: Producción
- Versión del documento: 1.3
- Fecha última revisión: 10/12/2025
- Owner del SOP: DevOps Lead
- Frecuencia de uso estimada: semanal
## Propósito
Garantizar despliegues seguros y repetibles a producción, minimizando riesgo de downtime y errores humanos.
## Alcance
Incluye:
- Despliegue de cambios de aplicación en contenedores Docker
- Actualización de configuraciones menores de Nginx
Excluye:
- Cambios de esquema de base de datos mayores
- Migraciones de infraestructura (nuevas VPC, nuevos clusters, etc)
## Roles y responsables
- Ejecutor: DevOps Engineer de guardia
- Aprobador técnico: Tech Lead del equipo correspondiente
- Observador opcional: Representante de Producto (para features grandes)
## Requisitos previos (checklist)
- [ ] Pull request principal aprobado
- [ ] Todos los checks de CI pasan en main
- [ ] Backup reciente (menos de 24 horas) confirmado
- [ ] Ventana de mantenimiento comunicada en #anuncios-internos
- [ ] No hay incidentes abiertos SEV-1 o SEV-2
- [ ] Se cuenta con plan de rollback documentado
## Comunicación previa
1. Avisar en canal #deploys:
- "Iniciando despliegue a producción para servicio X, ventana estimada 20 minutos."
2. Etiquetar:
- On-call de infra
- Tech Lead del servicio impactado
## Paso a paso técnico
1. Conectarse al servidor o runner de despliegue
2. Actualizar código:
- git fetch origin
- git checkout main
- git pull origin main
3. Construir contenedores:
- docker compose build
4. Desplegar servicios necesarios:
- docker compose up -d --no-deps web
- (si aplica) docker compose up -d --no-deps worker
5. Verificar estado de contenedores:
- docker ps
6. Verificar healthcheck de la aplicación:
- curl -I https://newsbm-tech.com/health
7. Revisar logs rápidos post despliegue:
- docker logs web-app --tail 100
## Validaciones post-despliegue
- Verificar en métricas:
- Errores 5xx no aumentan
- Latencia mediana y p95 estables
- Verificar funcionalmente:
- Login de usuario
- Consulta de artículos
- Flujo de pago (en sandbox o test controlado)
## Criterios de éxito
- Despliegue completado sin errores en menos de 30 minutos
- Sin aumento significativo de errores 5xx
- Sin quejas relevantes de usuarios en primeras 2 horas
## Rollback
Comando base:
- docker compose up -d --no-deps web-old
Pasos:
1. Avisar en #deploys que se va a aplicar rollback y motivo
2. Ejecutar rollback
3. Verificar healthcheck
4. Confirmar con métricas que el sistema se estabiliza
5. Documentar causa y acciones en ticket de incidentes o postmortem
## Comunicación posterior
1. Avisar en #deploys:
- "Despliegue completado con éxito, versión X.Y.Z en producción."
2. Si hubo problemas:
- Resumen corto del incidente
- Link al ticket de seguimiento
## Registro y evidencia
- Registrar:
- Hora de inicio y fin de despliegue
- Persona que ejecutó
- Versión desplegada (commit hash)
- Ubicación del registro:
- docs/procedimientos/deploy-log.md o herramienta equivalente
## Riesgos y notas
- Riesgo: cambios de base de datos sin migraciones backward compatible
- Mitigación: validar siempre migraciones con ambiente staging
- Nota: cualquier cambio de timeout o configuración de Nginx debe coordinarse con equipo backendRunbook de incidente: “Sitio caído 5xx” – versión completa
# RUNBOOK: Error 5xx masivo
## Síntomas
- Grafana alerta error 5xx mayor a 5 por ciento
- Usuarios reportan "Error interno del servidor"
- Páginas principales no cargan o devuelven error al iniciar sesión
## Definición de uso de este runbook
Usar este runbook cuando:
- El porcentaje de respuestas 5xx supera 5 por ciento en producción
- El problema impacta a más de 10 por ciento de los usuarios activos
- No hay cambios recientes obvios que expliquen el incidente (si los hay, seguir también el SOP de deploy)
## Severidad y objetivos
- Severidad: SEV-1
- Objetivo de recuperación (TTR): menos de 30 minutos
- Tiempo máximo para primera actualización a negocio: 10 minutos
## Comunicación inicial (primeros 5 minutos)
1. Crear hilo en canal de incidentes (por ejemplo, #incidentes):
- "Iniciando incidente SEV-1: alta tasa de errores 5xx en producción."
2. Asignar roles:
- Comandante del incidente
- Operador técnico principal
- Scribe (quien toma notas)
3. Fijar mensaje con:
- Hora de inicio
- Servicios afectados
- Persona responsable del update hacia negocio
## Diagnóstico rápido (primeros 5 a 10 minutos)
1. Verificar que el sitio realmente está caído:
- curl -I https://newsbm-tech.com
2. Ver estado de Nginx:
- systemctl status nginx
3. Ver últimos logs de Nginx:
- journalctl -u nginx -n 50
4. Ver estado de contenedores:
- docker ps
5. Ver métricas mínimas:
- Latencia
- 5xx
- Tráfico por endpoint
## Diagnóstico ampliado (según resultados)
- Si Nginx está caído:
- Intentar reinicio controlado:
- sudo systemctl restart nginx
- Revisar si hay errores de configuración reciente
- Si Nginx está arriba pero la app responde mal:
- Ver logs de aplicación:
- docker logs web-app --tail 200
- Revisar si hay excepciones repetidas
- Chequear conexiones a base de datos
- Si el problema parece ser base de datos:
- Consultar estado del RDS o cluster:
- conexión, replicación, CPU, locks
- Validar si hubo migraciones recientes
- Si parece problema de dependencia externa:
- Verificar status de proveedor (status page)
- Aplicar mecanismos de degradación graciosa si existen
## Soluciones (orden sugerido)
A) Reiniciar únicamente Nginx
- sudo systemctl restart nginx
B) Verificar espacio en disco
- df -h
C) Reiniciar servicio de aplicación (si está trabado)
- docker restart web-app
D) Activar versión anterior estable (si existe)
- docker compose up -d --no-deps web-old
E) Escalar a base de datos (si el cuello está ahí)
- Ajustar tamaño temporalmente
- Reducir consultas pesadas si se identifica alguna
F) Escalar:
- Contactar a la persona on-call de backend
- Contactar a base de datos o SRE si existe rol separado
## Comunicación durante el incidente
- Actualización mínima cada 15 minutos en canal de incidentes:
- Qué sabemos
- Qué estamos probando
- Próximos pasos
- En caso de incidente prolongado:
- Mensaje simplificado al negocio:
- Usuarios afectados
- Funcionalidades impactadas
- Tiempo estimado de resolución si existe
## Cierre del incidente
1. Confirmar estabilidad:
- Errores 5xx por debajo de 1 por ciento por al menos 30 minutos
- Latencia y tráfico normales
2. Comunicar en canal de incidentes:
- "Incidente resuelto, monitoreando 30 minutos adicionales."
3. Cambiar estado del incidente en herramienta de gestión (Jira, Linear, etc) a "Resuelto pendiente de postmortem"
## Postmortem
- Debe generarse un documento de postmortem en menos de 72 horas
- Formato mínimo:
- Línea de tiempo
- Causa raíz
- Qué funcionó bien
- Qué se puede mejorar
- Acciones concretas con responsables y fechas
## No hacer
- No aplicar cambios de configuración grandes en medio del incidente
- No reiniciar la base de datos sin validar backups
- No modificar el balanceador sin entender el tráfico actualDocumentación de API (estilo OpenAPI) – plantilla extendida
# API Noticias NewsBM Tech
Base URL: https://api.newsbm-tech.com/v1
Estado: Estable
Owner técnico: Equipo Backend Noticias
Contacto: backend@newsbm-tech.com
## Autenticación
- Tipo: Bearer Token
- Header requerido:
- Authorization: Bearer token
- Expiración de token: 1 hora
- Endpoint de obtención de token:
- POST /auth/token
## Versionado
- Versión actual: v1
- Politica:
- Cambios compatibles se mantienen en la misma versión
- Cambios que rompen compatibilidad generan nueva versión (v2, v3, etc)
- Deprecación:
- Endpoints obsoletos se marcan con cabecera:
- Deprecation: true
- Se avisa con al menos 90 días de anticipación
## Recursos principales
### GET /articles
Lista paginada de artículos publicados.
Respuesta exitosa:
- Código: 200
- Contenido:
{
"data": [
{
"id": 1,
"title": "Ejemplo 1",
"slug": "ejemplo-1",
"published_at": "2025-01-01T10:00:00Z"
}
],
"meta": {
"total": 142,
"page": 1,
"limit": 20
}
}
Parámetros de consulta:
- page (opcional, por defecto 1)
- limit (opcional, por defecto 20, máximo 100)
- q (opcional, búsqueda por título o contenido)
- category (opcional)
### GET /articles/:id
Obtiene el detalle de un artículo.
Respuesta exitosa:
- Código: 200
- Cuerpo:
{
"id": 1,
"title": "Ejemplo 1",
"slug": "ejemplo-1",
"body": "Contenido del artículo...",
"author": "Autor X",
"tags": ["deportes", "argentina"],
"published_at": "2025-01-01T10:00:00Z"
}
Errores frecuentes:
- 404: artículo no encontrado
- 401: token no enviado o inválido
## Errores y formato de respuesta
Formato estándar de error:
{
"error": {
"code": "string",
"message": "Descripción legible para humanos",
"details": {
"campo": "detalle adicional"
},
"correlation_id": "uuid"
}
}
Ejemplos:
- 400:
- code: "VALIDATION_ERROR"
- 401:
- code: "UNAUTHORIZED"
- 429:
- code: "RATE_LIMIT_EXCEEDED"
## Límite de peticiones
- Límite actual: 1000 solicitudes por hora por token
- Headers:
- X-RateLimit-Limit
- X-RateLimit-Remaining
- X-RateLimit-Reset
## Contrato de estabilidad
- Campos existentes no se eliminan sin proceso de deprecación
- Nuevos campos siempre son opcionales
- Se evita cambiar semántica de campos sin nueva versión
## Ejemplo de uso con curl
- Listar artículos:
curl -H "Authorization: Bearer TOKEN" \
"https://api.newsbm-tech.com/v1/articles?page=1&limit=10"
- Ver detalle:
curl -H "Authorization: Bearer TOKEN" \
"https://api.newsbm-tech.com/v1/articles/1"ADR – Decisión de Arquitectura (plantilla extendida)
# ADR-007: Migración a PostgreSQL 16
## Metadatos
- Estado: Aceptado
- Fecha: 10/01/2025
- Autores: Equipo Backend, Equipo Data
- Revisión: CTO
## Contexto
Necesitamos soporte JSON nativo con buen rendimiento, capacidades de consultas complejas
y extensiones para analítica ligera sin salir de la base principal.
Limitaciones actuales:
- MySQL que usamos tiene soporte JSON limitado y menos eficiente
- Algunas consultas se vuelven difíciles de optimizar
- Queremos unificar motor de base de datos entre servicios nuevos
## Problema
Elegir un motor de base de datos principal que:
- Soporte JSON y consultas complejas
- Sea suficientemente maduro y conocido por la industria
- Tenga buena integración con nuestro stack y nube actual
## Opciones consideradas
1. MySQL 8
- Ventajas:
- Amplio uso en la industria
- El equipo ya tiene experiencia
- Desventajas:
- Soporte JSON menos flexible
- Menos extensiones para casos analíticos
2. PostgreSQL 16
- Ventajas:
- JSONB muy potente
- Extensiones como PostGIS, funcionalidades adicionales
- Buen rendimiento en consultas complejas
- Desventajas:
- Equipo con menos experiencia previa
- Migración de tooling existente
3. MongoDB
- Ventajas:
- Modelo documento muy flexible
- Desventajas:
- No relacional, implica cambio de paradigma
- Aumenta complejidad operativa
## Decisión
Adoptar PostgreSQL 16 como base de datos principal para servicios nuevos y migraciones planificadas.
## Consecuencias positivas
- Mejor rendimiento en consultas complejas con JSONB
- Menor necesidad de servicios adicionales para analítica ligera
- Aprovechamiento de extensiones del ecosistema PostgreSQL
## Consecuencias negativas
- Curva de aprendizaje para equipo acostumbrado a MySQL
- Necesidad de revisar y adaptar migraciones y tooling
- Migración gradual de servicios existentes
## Plan de implementación
- Fase 1:
- Crear instancias de prueba de PostgreSQL 16
- Actualizar librerías de conexión en servicios nuevos
- Fase 2:
- Migrar servicio de noticias a PostgreSQL
- Actualizar pipelines de migración y backup
- Fase 3:
- Deprecar gradualmente esquemas de MySQL ya migrados
## Métricas de éxito
- Disminución de tiempos de respuesta en consultas complejas
- Reducción de incidentes relacionados con consultas y bloqueos
- Satisfacción del equipo de desarrollo con las nuevas capacidades
## Referencias y enlaces
- Ticket: PROJ-1234
- PR principal: https://github.com/org/repo/pull/42
- Documentación PostgreSQL: https://www.postgresql.org/docs/16/Formato guía de onboarding técnico
# ONBOARDING-DEV: Primeros 7 días en NewsBM Tech
## Metadatos
- Rol objetivo: Backend Developer
- Última actualización: 10/12/2025
- Owner del documento: Líder Técnico Backend
## Día 1: Setup básico
- [ ] Recibir accesos:
- Correo corporativo
- GitHub o repositorio código
- Jira o herramienta de tickets
- Slack o chat interno
- [ ] Leer:
- docs/onboarding/vision-producto.md
- docs/onboarding/arquitectura-alto-nivel.md
- [ ] Configurar entorno:
- Clonar repos principales
- Levantar aplicación en local
- Ejecutar tests
## Día 2: Conocer el sistema
- [ ] Leer documentación:
- docs/infraestructura/servidores/web-prod-01.md
- docs/apis/api-noticias.md
- [ ] Acompañamiento:
- Participar de una daily
- Reunión corta con Tech Lead para revisar dudas
## Día 3: Primeras tareas
- [ ] Tomar una tarea pequeña de mantenimiento
- [ ] Hacer PR y seguir el flujo estándar
- [ ] Documentar al final del día:
- Qué costó entender
- Qué documentación faltó
## Día 4 a 5: Profundizar en un área
- [ ] Elegir foco:
- Pagos
- Publicación de noticias
- Suscripciones
- [ ] Leer SOPs y runbooks relevantes
- [ ] Hacer pairing con alguien del equipo
## Día 6 a 7: Aportar a la documentación
- [ ] Proponer mejora a:
- Un SOP
- Un runbook
- O la guía de onboarding
- [ ] Abrir PR con cambios sugeridos
- [ ] Registrar feedback:
- Qué documentación fue más útil
- Qué agregarían para futuros ingresosEstructura de carpetas recomendada (2025)
docs/
├── README.md # Explica cómo está organizada la documentación
├── plantillas/ # Plantillas reutilizables (SOP, runbooks, ADR, etc)
│ ├── SOP-plantilla.md
│ ├── RUNBOOK-plantilla.md
│ ├── ADR-plantilla.md
│ └── ONBOARDING-plantilla.md
├── infraestructura/
│ ├── README.md
│ └── servidores/
│ ├── web-prod-01.md
│ ├── web-staging-01.md
│ └── bastion-host.md
├── aplicaciones/
│ ├── noticias/
│ │ ├── arquitectura.md
│ │ └── decisiones-clave.md
│ └── pagos/
│ └── arquitectura.md
├── procedimientos/
│ ├── SOP-deploy-prod.md
│ └── SOP-backup-restore.md
├── runbooks/
│ ├── RUNBOOK-web-5xx.md
│ ├── RUNBOOK-db-connection-errors.md
│ └── RUNBOOK-cache-caida.md
├── apis/
│ ├── api-noticias.md
│ └── api-pagos.md
├── adr/
│ ├── ADR-001-eleccion-cloud.md
│ ├── ADR-007-migracion-postgres16.md
│ └── ADR-010-cache-global-redis.md
└── onboarding/
├── guia-general.md
├── onboarding-dev-backend.md
└── onboarding-devops.mdChecklist rápida: ¿este documento sirve o estorba?
- ¿Tiene fecha de última actualización visible?
- ¿Tiene responsable claro (owner) con nombre o rol?
- ¿Responde a una pregunta real?
- Ejemplos: “¿Cómo despliego X?”, “¿Qué hago si Y se cae?”
- ¿Se puede usar en menos de 5 minutos bajo estrés?
- ¿Está en la carpeta correcta de
docs/? - ¿Tiene ejemplos concretos (comandos, JSON, capturas si aplican)?
- ¿Marca claramente lo que está obsoleto o pendiente de revisar?
Si al menos 5 de estas respuestas son "sí", el documento ya es útil. Si menos de 3, es ruido o está incompleto.
Convenciones de nombres para documentos
Formato recomendado:
SOP-sistema-accion.md→SOP-API-PAGOS-DEPLOY.mdRUNBOOK-servicio-tipo-incidente.md→RUNBOOK-WEB-5XX.mdADR-numero-decision-corta.md→ADR-007-migracion-postgres16.mdONBOARDING-rol.md→ONBOARDING-DEV-BACKEND.md
Regla básica: si el nombre no se entiende en 3 segundos, es muy largo o muy genérico.
Ciclo de vida de la documentación
- Draft: idea inicial, incompleta pero ya útil para alguien.
- Revisión: otra persona del equipo la prueba como si no supiera nada.
- Aprobado: se usó al menos una vez en un caso real (deploy, incidente, onboarding).
- Obsoleto: se marca como obsoleto y se linkea a la versión nueva actualizada.
Se recomienda revisar documentos críticos (SOP de deploy, runbooks de incidentes, onboarding) cada 3 a 6 meses o después de un incidente importante.
Cómo empezar en tu empresa en 1 semana
- Lista 3 sistemas críticos:
- Ejemplo: web pública, API de pagos, base de datos principal.
- Crea o actualiza:
- 1 documento de servidor crítico (formato de servidores arriba).
- 1 SOP de despliegue a producción.
- 1 runbook de incidente frecuente (5xx, base de datos, cache).
- Pide a alguien del equipo que use cada documento sin explicaciones extra.
- Anota dónde se trabó o tuvo que adivinar y mejora el documento.
Objetivo: que el equipo no dependa de la memoria de una sola persona para operar sistemas críticos.
Conclusión: Empieza hoy
Regla de oro: La mejor documentación es la que existe, no la perfecta que nunca se escribió y no sirve de nada.
Elige un servidor crítico, un procedimiento doloroso o un runbook que te haya salvado la vida esta semana y documéntalo con los formatos de arriba. En 30 minutos tendrás el 80 por ciento del valor.
Hazlo hoy y en una semana tu equipo te lo va a agradecer.