system-docs/v4-archive/clara/DEPLOYMENT.md

CLARA - Deployment Guide

Despliegue rápido con Docker Compose

1. Configuración

# Copiar archivo de ejemplo
cp .env.example .env

# Editar con tus credenciales
nano .env

2. Generar H_INSTANCIA

# 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

# 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

# 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

curl http://localhost:5051/health

Ingest (recibir contenedor)

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)

curl http://localhost:5051/query/sha256-archivo \
  -H "X-Auth-Key: $H_INSTANCIA"

List (listar contenedores)

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)

# 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

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

# Docker Compose
docker-compose logs -f clara

# Si usa systemd
journalctl -u clara -f

Métricas

# 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

# 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

# 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