# 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*