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:

docker --version
docker-compose --version

---

📦 Paso 1: Transferir archivos

Opción A: Clonar desde Gitea (cuando esté disponible)

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

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

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

# 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

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

curl http://localhost:5051/health

Respuesta esperada:

{
  "service": "clara",
  "status": "ok",
  "timestamp": "2025-12-23T20:XX:XX"
}

Test 2: Verificar PostgreSQL

docker exec -it clara-postgres psql -U postgres -d tzzr -c "\dt"

Deberías ver la tabla: clara_log

Test 3: Test completo

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:

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:

ln -s /etc/nginx/sites-available/clara /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

Opción B: SSL con Let's Encrypt

certbot --nginx -d clara.tzzrdeck.me

---

🔒 Paso 6: Firewall

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

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:

{
  "ok": true,
  "id": 1,
  "h_entrada": "abc123test"
}

Verificar:

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

---

📊 Monitoreo

Ver logs

docker-compose logs -f clara
docker-compose logs -f postgres

Estadísticas

# 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

docker-compose ps
docker stats --no-stream

---

💾 Backup

Backup manual

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

# 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

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

docker-compose restart clara
docker-compose restart postgres

Reconstruir desde cero

docker-compose down -v
docker-compose up -d --build

---

📝 Mantenimiento

Actualizar CLARA

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

Limpiar logs antiguos

docker system prune -a
journalctl --vacuum-time=30d

Rotar logs de PostgreSQL

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