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

# Despliegue de CLARA en DECK

**Servidor:** DECK (72.62.1.113 / tzzrdeck.me)
**Fecha:** 2025-12-23
**Preparado por:** ARCHITECT

---

## 📋 Pre-requisitos

### En el servidor DECK debe estar instalado:
- Docker (versión 20.10 o superior)
- Docker Compose (versión 2.0 o superior)
- Acceso a internet para pull de imágenes

### Verificar:
```bash
docker --version
docker-compose --version
```

---

## 📦 Paso 1: Transferir archivos

### Opción A: Clonar desde Gitea (cuando esté disponible)
```bash
ssh root@72.62.1.113
cd /opt
git clone https://git.tzzr.me/tzzr/clara.git
cd clara
```

### Opción B: Transferir paquete manualmente
```bash
# Desde ARCHITECT (69.62.126.110)
cd /home/orchestrator
tar czf clara-deployment.tar.gz clara-deployment/

# Transferir a DECK
scp clara-deployment.tar.gz root@72.62.1.113:/opt/

# En DECK
ssh root@72.62.1.113
cd /opt
tar xzf clara-deployment.tar.gz
mv clara-deployment clara
cd clara
```

### Opción C: Via HTTP (si SSH no está disponible)
```bash
# En ARCHITECT - crear servidor temporal
cd /home/orchestrator
python3 -m http.server 8888

# En DECK - descargar
wget http://69.62.126.110:8888/clara-deployment.tar.gz
tar xzf clara-deployment.tar.gz
mv clara-deployment /opt/clara
cd /opt/clara
```

---

## ⚙️ Paso 2: Configurar credenciales

El archivo `.env` ya está configurado con las siguientes credenciales:

```bash
# Ver configuración actual
cat .env
```

### Credenciales configuradas:

- **H_INSTANCIA:** `87f6bdbf490b82435e9e804c115570efd70d3ccb7d89a5ee1ff1dde142151165`
- **DB_PASSWORD:** `PGFRKChQrx3R27eImwRgg57syX2yWd7s+/VwCH2CQuo=`
- **R2 Endpoint:** Cloudflare R2 configurado
- **R2 Bucket:** `deck`

> ⚠️ **IMPORTANTE:** Guarda `H_INSTANCIA` en un lugar seguro. Este hash se usará para autenticación desde PACKET.

---

## 🚀 Paso 3: Iniciar servicios

```bash
cd /opt/clara

# Construir y levantar contenedores
docker-compose up -d

# Ver logs en tiempo real
docker-compose logs -f clara

# Verificar que los contenedores están corriendo
docker-compose ps
```

Deberías ver:
```
NAME                 STATUS              PORTS
clara-service        Up X minutes        0.0.0.0:5051->5051/tcp
clara-postgres       Up X minutes        0.0.0.0:5433->5432/tcp
```

---

## ✅ Paso 4: Verificar instalación

### Test 1: Health Check
```bash
curl http://localhost:5051/health
```

**Respuesta esperada:**
```json
{
  "service": "clara",
  "status": "ok",
  "timestamp": "2025-12-23T20:XX:XX"
}
```

### Test 2: Verificar PostgreSQL
```bash
docker exec -it clara-postgres psql -U postgres -d tzzr -c "\dt"
```

**Deberías ver la tabla:** `clara_log`

### Test 3: Test completo
```bash
chmod +x test_clara.sh
./test_clara.sh
```

---

## 🌐 Paso 5: Configurar acceso externo (Opcional)

### Opción A: Nginx Reverse Proxy

Crear `/etc/nginx/sites-available/clara`:

```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;

        # Para archivos grandes
        client_max_body_size 100M;
    }
}
```

Activar:
```bash
ln -s /etc/nginx/sites-available/clara /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx
```

### Opción B: SSL con Let's Encrypt
```bash
certbot --nginx -d clara.tzzrdeck.me
```

---

## 🔒 Paso 6: Firewall

```bash
# Permitir puerto 5051 (o 80/443 si usas Nginx)
ufw allow 5051/tcp
ufw reload

# O si usas Nginx con SSL
ufw allow 'Nginx Full'
```

---

## 📱 Paso 7: Configurar PACKET

En la app PACKET, configurar:

**URL de CLARA:**
```
https://clara.tzzrdeck.me/ingest
# O si no tienes Nginx:
http://72.62.1.113:5051/ingest
```

**Autenticación (Header):**
```
X-Auth-Key: 87f6bdbf490b82435e9e804c115570efd70d3ccb7d89a5ee1ff1dde142151165
```

---

## 🧪 Paso 8: Test desde PACKET

Simular envío desde PACKET:

```bash
curl -X POST http://localhost:5051/ingest \
  -H "X-Auth-Key: 87f6bdbf490b82435e9e804c115570efd70d3ccb7d89a5ee1ff1dde142151165" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "test-uuid-001",
    "archivo_hash": "abc123test",
    "origen": {
      "dispositivo": "test-device",
      "timestamp_captura": "2025-12-23T20:00:00Z"
    },
    "archivo": {
      "tipo": "image/jpeg",
      "categoria": "imagen"
    }
  }'
```

**Respuesta esperada:**
```json
{
  "ok": true,
  "id": 1,
  "h_entrada": "abc123test"
}
```

Verificar:
```bash
curl http://localhost:5051/list \
  -H "X-Auth-Key: 87f6bdbf490b82435e9e804c115570efd70d3ccb7d89a5ee1ff1dde142151165"
```

---

## 📊 Monitoreo

### Ver logs
```bash
docker-compose logs -f clara
docker-compose logs -f postgres
```

### Estadísticas
```bash
# Número de contenedores recibidos
docker exec -it clara-postgres psql -U postgres -d tzzr -c \
  "SELECT COUNT(*) FROM clara_log;"

# Últimos 5 contenedores
docker exec -it clara-postgres psql -U postgres -d tzzr -c \
  "SELECT id, h_entrada, created_at FROM clara_log ORDER BY id DESC LIMIT 5;"
```

### Estado de contenedores
```bash
docker-compose ps
docker stats --no-stream
```

---

## 💾 Backup

### Backup manual
```bash
# PostgreSQL
docker exec clara-postgres pg_dump -U postgres tzzr > \
  /opt/clara/backups/clara_$(date +%Y%m%d_%H%M%S).sql

# Archivos de configuración
tar czf /opt/clara/backups/clara_config_$(date +%Y%m%d).tar.gz \
  /opt/clara/.env /opt/clara/docker-compose.yml
```

### Backup automático (cron)
```bash
# Editar crontab
crontab -e

# Añadir (backup diario a las 3 AM)
0 3 * * * docker exec clara-postgres pg_dump -U postgres tzzr > /opt/clara/backups/clara_$(date +\%Y\%m\%d).sql

# Backup semanal a R2 (domingos a las 4 AM)
0 4 * * 0 /opt/clara/backup_to_r2.sh
```

---

## 🔧 Troubleshooting

### Error: "unauthorized"
Verificar que el header `X-Auth-Key` coincide con `H_INSTANCIA` en `.env`.

### Error: "connection refused" a PostgreSQL
```bash
docker logs clara-postgres
docker-compose restart postgres
```

### Error: "r2_upload_failed"
Verificar credenciales R2 en `.env` y que el bucket `deck` existe.

### Reiniciar servicios
```bash
docker-compose restart clara
docker-compose restart postgres
```

### Reconstruir desde cero
```bash
docker-compose down -v
docker-compose up -d --build
```

---

## 📝 Mantenimiento

### Actualizar CLARA
```bash
cd /opt/clara
git pull  # Si está en Gitea
docker-compose down
docker-compose build --no-cache
docker-compose up -d
```

### Limpiar logs antiguos
```bash
docker system prune -a
journalctl --vacuum-time=30d
```

### Rotar logs de PostgreSQL
```bash
docker exec -it clara-postgres psql -U postgres -d tzzr -c \
  "DELETE FROM clara_log WHERE created_at < NOW() - INTERVAL '1 year';"
```

---

## 📞 Soporte

- **Logs:** `/opt/clara/docker-compose.yml`
- **Config:** `/opt/clara/.env`
- **Documentación:** https://git.tzzr.me/tzzr/clara
- **Contacto:** ARCHITECT

---

## ✅ Checklist de despliegue

- [ ] Archivos transferidos a `/opt/clara`
- [ ] `.env` configurado correctamente
- [ ] Docker Compose up y corriendo
- [ ] Health check responde OK
- [ ] PostgreSQL creó tabla `clara_log`
- [ ] Test de ingesta exitoso
- [ ] Nginx configurado (opcional)
- [ ] SSL configurado (opcional)
- [ ] Firewall configurado
- [ ] PACKET configurado con URL y Auth-Key
- [ ] Backup automático configurado
- [ ] Monitoreo activo

---

**Generado:** 2025-12-23
**ARCHITECT** - Sistema TZZR