Archive: System v4 - Estado al 2024-12-24

v4-archive/clara/DEPLOYMENT.md

@@ -0,0 +1,207 @@
+# CLARA - Deployment Guide
+
+## Despliegue rápido con Docker Compose
+
+### 1. Configuración
+
+```bash
+# Copiar archivo de ejemplo
+cp .env.example .env
+
+# Editar con tus credenciales
+nano .env
+```
+
+### 2. Generar H_INSTANCIA
+
+```bash
+# Generar hash único para la instancia DECK
+echo -n "deck-seed-$(date +%s)-$(hostname)" | sha256sum | cut -d' ' -f1
+```
+
+Copiar el resultado a `.env` como `H_INSTANCIA`.
+
+### 3. Configurar credenciales R2
+
+Obtener de Cloudflare R2:
+- Account ID
+- Access Key ID
+- Secret Access Key
+
+Actualizar en `.env`:
+```
+R2_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
+R2_ACCESS_KEY=<access-key-id>
+R2_SECRET_KEY=<secret-access-key>
+```
+
+### 4. Iniciar servicios
+
+```bash
+# Construir y levantar
+docker-compose up -d
+
+# Ver logs
+docker-compose logs -f clara
+
+# Verificar estado
+curl http://localhost:5051/health
+```
+
+### 5. Verificar base de datos
+
+```bash
+# Conectar a PostgreSQL
+docker exec -it clara-postgres psql -U postgres -d tzzr
+
+# Ver tabla
+\d clara_log
+
+# Ver registros
+SELECT * FROM clara_summary LIMIT 10;
+```
+
+## Endpoints API
+
+### Health Check
+```bash
+curl http://localhost:5051/health
+```
+
+### Ingest (recibir contenedor)
+```bash
+curl -X POST http://localhost:5051/ingest \
+  -H "X-Auth-Key: $H_INSTANCIA" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "id": "uuid-contenedor",
+    "archivo_hash": "sha256-archivo",
+    "origen": {
+      "dispositivo": "uuid-dispositivo",
+      "timestamp_captura": "2025-12-23T20:00:00Z"
+    },
+    "archivo": {
+      "tipo": "image/jpeg",
+      "categoria": "imagen"
+    }
+  }'
+```
+
+### Query (consultar por hash)
+```bash
+curl http://localhost:5051/query/sha256-archivo \
+  -H "X-Auth-Key: $H_INSTANCIA"
+```
+
+### List (listar contenedores)
+```bash
+curl "http://localhost:5051/list?limit=10&offset=0" \
+  -H "X-Auth-Key: $H_INSTANCIA"
+```
+
+## Despliegue en DECK (72.62.1.113)
+
+### Opción 1: Docker Compose (Recomendado)
+
+```bash
+# SSH al servidor
+ssh root@72.62.1.113
+
+# Clonar repositorio
+git clone http://69.62.126.110:3000/tzzr/clara.git
+cd clara
+
+# Configurar
+cp .env.example .env
+nano .env
+
+# Iniciar
+docker-compose up -d
+```
+
+### Opción 2: Servicio systemd
+
+Ver `clara.service` para configuración systemd.
+
+## Nginx Reverse Proxy
+
+```nginx
+server {
+    listen 80;
+    server_name clara.tzzrdeck.me;
+
+    location / {
+        proxy_pass http://localhost:5051;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+## Monitoreo
+
+### Logs
+```bash
+# Docker Compose
+docker-compose logs -f clara
+
+# Si usa systemd
+journalctl -u clara -f
+```
+
+### Métricas
+```bash
+# Número de contenedores
+docker exec -it clara-postgres psql -U postgres -d tzzr -c "SELECT COUNT(*) FROM clara_log;"
+
+# Último contenedor recibido
+docker exec -it clara-postgres psql -U postgres -d tzzr -c "SELECT * FROM clara_summary ORDER BY id DESC LIMIT 1;"
+```
+
+## Backup
+
+```bash
+# Backup de PostgreSQL
+docker exec clara-postgres pg_dump -U postgres tzzr > clara_backup_$(date +%Y%m%d).sql
+
+# Restaurar
+cat clara_backup_20251223.sql | docker exec -i clara-postgres psql -U postgres tzzr
+```
+
+## Troubleshooting
+
+### Error: "unauthorized"
+Verificar que `X-Auth-Key` en el request coincida con `H_INSTANCIA` en `.env`.
+
+### Error: "r2_upload_failed"
+Verificar credenciales de R2 y que el bucket existe.
+
+### Error: "connection refused" al PostgreSQL
+```bash
+# Verificar que el contenedor está corriendo
+docker ps | grep postgres
+
+# Ver logs
+docker logs clara-postgres
+```
+
+## Seguridad
+
+1. **Firewall**: Solo exponer puerto 5051 a IPs confiables (PACKET)
+2. **Auth**: Usar `H_INSTANCIA` largo y aleatorio
+3. **HTTPS**: Usar reverse proxy con SSL (Let's Encrypt)
+4. **Backup**: Configurar backups automáticos a R2
+
+## Próximos pasos
+
+Después de desplegar CLARA:
+1. Configurar PACKET para enviar a `https://clara.tzzrdeck.me/ingest`
+2. Implementar MASON para enriquecimiento
+3. Implementar FELDMAN para consolidación
+4. Configurar backups automáticos
+
+---
+
+*Actualizado: 2025-12-23*