RUNBOOK.md

RUNBOOK — Mantenimiento Vault Obsidian OAM Errenteria Musikal

Vault: /root/wiki/

Última actualización: 2026-05-01

Responsable: Jokin (con asistencia Hermes)

---

📋 Índice

1. [Estado actual](#estado-actual)

2. [Procedimientos diarios](#procedimientos-diarios)

3. [Procedimientos semanales](#procedimientos-semanales)

4. [Solución de problemas](#solución-de-problemas)

5. [Recuperación](#recuperación)

---

Estado actual

| Componente | Estado | Última acción |

|------------|--------|---------------|

| Obsidian LiveSync | ✅ Activo | 2026-05-01 |

| CouchDB | ✅ Corriendo (Docker) | 2026-05-01 |

| Google Drive Sync | ⏳ Pendiente autorización | — |

| Frontmatter YAML | ✅ 100% (100/100) | 2026-05-01 |

| Enlaces wiki | ✅ ≥2 por página (excepto logs) | 2026-05-01 |

| Automatización | ✅ Cronjobs instalados | 2026-05-01 |

---

Procedimientos diarios

✓ Verificar sincronización (automática)

• Cron: 0 6 * /usr/local/bin/drive-sync
• Log: /var/log/drive-sync.log
• Comprobación manual:

  tail -f /var/log/drive-sync.log

  

• Si hay errores de autenticación → re-autorizar OAuth (ver sección Problemas).

✓ Lint diario (automático)

• Cron: 0 8 * /usr/local/bin/vault-lint.sh
• Log: /var/log/vault-lint.log
• Comprobación manual:

  vault-lint.sh  # ejecutar manualmente

  

---

Procedimientos semanales

Revisión manual de sources/ pendientes

Los archivos en raw/ que se descargan de Drive se convierten automáticamente a sources/. Sin embargo, algunos documentos pueden requerir:

• Tagging: completar campo tags: en frontmatter con taxonomía adecuada (ver SCHEMA.md).
• Enlaces específicos: asegurar que cada página enlaza a documentos relevantes (no solo a index).
• Actualización de index.md: nuevas fuentes deben aparecer en la sección correcta.

Checklist semanal:

• [ ] Revisar sources/ nuevos (últimos 7 días)
• [ ] Añadir tags apropiados: decreto, reglamento, procedimiento, convenio, planificacion + ámbito (laboral, organizativo, academico, normativo)
• [ ] Actualizar index.md si falta entrada
• [ ] Registrar en NOTAS-DESARROLLO.md cualquier ambigüedad detectada

Backup verification

Los backups automáticos no están configurados aún. Recomendado:

#manual weekly

tar -czf /root/backups/wiki-$(date +%Y%m%d).tar.gz /root/wiki

Considerar script de backup remoto (ej. a Drive o S3).

---

Solución de problemas

❌ Drive sync falla con invalid_scope

Causa: El token OAuth actual no incluye el scope de Drive.

Solución:

1. Ejecutar drive-sync manualmente para ver error.

2. Generar nueva URL de autorización:

   python3 /usr/local/bin/authorize-drive.py  # (script a crear) o pedir a Hermes que la genere

   

3. Abrir URL en navegador, autorizar, copiar código.

4. Ejecutar:

   python3 /usr/local/bin/exchange-code.py 

   

5. Verificar: /root/google_credentials.json ahora tiene "scope": ["...","drive"].

❌ LiveSync no sincroniza

Checks:

• [ ] CouchDB corriendo: docker ps | grep couchdb
• [ ] Puerto 5984 accesible: curl http://localhost:5984/_utils/
• [ ] Base de datos wiki existe: curl http://admin:WikiSync2026!@localhost:5984/_all_dbs
• [ ] Obsidian Desktop: Settings → Self-hosted LiveSync → estado "Connected"
• [ ] Si falla SSL (HTTPS), verificar certificado Traefik o usar HTTP interno (localhost)

❌ Archivos sin frontmatter tras nueva ingesta

Causa: El script de ingesta no ejecutó fix-frontmatter.py.

Solución:

/root/.hermes/hermes-agent/venv/bin/python3 /usr/local/bin/fix-frontmatter.py

git add -A && git commit -m "fix: frontmatter"

❌ Enlaces rotos (... destina a archivo inexistente)

Diagnóstico:

python3 -c "

import re, pathlib
vault = pathlib.Path('/root/wiki')
all_files = set(p.stem for p in vault.rglob('*.md'))
broken = []
for f in vault.rglob('*.md'):
    for m in re.findall(r'\[\[([^\]|]+)', f.read_text(errors='ignore')):
        if m not in all_files:
            broken.append((str(f), m))
for b in broken: print(b)
"

Acción: Corregir manualmente el enlace o crear el archivo destino.

---

Recuperación

Restaurar vault desde backup

Detener servicios (CouchDB, Obsidian)

systemctl stop ...  # o docker compose down en /opt/couchdb

Restaurar

tar -xzf /root/backups/wiki-YYYYMMDD.tar.gz -C /
Restaurar CouchDB si es necesario: copiar shards a /opt/couchdb/data/

Reiniciar CouchDB

docker start couchdb-obsidian

Resetear LiveSync (client Obsidian)

Si el vault local está corrupto:

1. Cerrar Obsidian.

2. Borrar ~/.config/obsidian/plugins/self-hosted-livesync/ (o /.obsidian/plugins/obsidian-livesync/ en el vault).

3. Re-abrir vault y reconfigurar conexión (ver skill obsidian-livesync-couchdb-setup).

---

Contacto de emergencia

• Hermes Agent: invocar con /Hermes en Telegram.
• Logs vault: /root/wiki/log.md
• Logs sistema: /var/log/vault-lint.log, /var/log/drive-sync.log

index SCHEMA