system-docs/MANUAL_USUARIO_DECK.md

# MANUAL DE USUARIO - DECK
## Sistema TZZR - Skynet v8
**Servidor:** 72.62.1.113
**Fecha:** 2025-12-30

---

# Manual de Usuario - DECK (72.62.1.113)
## PARTE 1: Introducción y Servicios

---

## 1. Introducción a DECK

### ¿Qué es DECK?

DECK es uno de los cuatro servidores principales del sistema TZZR (The Zero-Trust Resilient Resource Network), ubicado en la dirección IP **72.62.1.113**.

DECK actúa como **servidor de servicios** y aloja:
- **Agentes especializados** (Clara, Alfred, Mason, Feldman) que procesan datos e interactúan con otros sistemas
- **Servicios empresariales** (Correo, almacenamiento en la nube, contraseñas, etc.)
- **Infraestructura de datos** (PostgreSQL con pgvector, Redis)
- **Aplicaciones integradas** (ERP, CMS, notificaciones, gestor de archivos)

### Rol en la Infraestructura TZZR

El sistema TZZR consta de 4 servidores distribuidos:

| Servidor | IP | Función Principal |
|----------|----|--------------------|
| **Central** | 69.62.126.110 | Coordinación (Gitea, PostgreSQL central) |
| **DECK** | 72.62.1.113 | Servicios, Agentes, Mail (Este servidor) |
| **CORP** | 92.112.181.188 | Agentes especializados (Margaret, Jared) |
| **HST** | 72.62.2.84 | Directus, gestión de imágenes |

### Acceso SSH a DECK

Para conectarse a DECK desde la máquina central o cualquier servidor autorizado:

```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113
```

**Requisitos:**
- Tener la clave privada SSH en `~/.ssh/tzzr`
- Permisos de acceso configurados
- Conectividad de red al servidor

**Verificar conexión:**
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113 "echo 'Conexión exitosa'"
```

---

## 2. Servicios en DECK

DECK aloja tres categorías principales de servicios:

### 2.1 Microservicios TZZR (Puertos 505x)

Estos son servicios especializados del ecosistema TZZR que se comunican entre sí:

#### Clara (Puerto 5051)
- **Descripción:** Log inmutable y auditoría
- **Propósito:** Registra todas las transacciones y eventos del sistema de forma imposible de modificar
- **Uso:** Auditoría, trazabilidad, compliance
- **Estado:** Verificar con `service clara`

#### Alfred (Puerto 5052)
- **Descripción:** Automatización de flujos de trabajo
- **Propósito:** Ejecuta flujos de trabajo definidos, orquesta tareas entre servicios
- **Uso:** Automatización de procesos empresariales
- **Estado:** Verificar con `service alfred`

#### Mason (Puerto 5053)
- **Descripción:** Espacio de enriquecimiento de datos
- **Propósito:** Enriquece datos con información contextual, aplica transformaciones
- **Uso:** Procesamiento y normalización de datos
- **Estado:** Verificar con `service mason`

#### Feldman (Puerto 5054)
- **Descripción:** Validador Merkle
- **Propósito:** Verifica integridad de datos mediante árboles de Merkle
- **Uso:** Validación criptográfica, verificación de integridad
- **Estado:** Verificar con `service feldman`

### 2.2 Aplicaciones Empresariales

Servicios de aplicación usuario-final para uso cotidiano:

#### Nextcloud (Puerto 8084)
- **Descripción:** Almacenamiento en la nube y colaboración
- **URL:** https://cloud.tzzrdeck.me
- **Uso:** Compartir archivos, calendario, contactos
- **Capacidades:** Sincronización, compartir enlaces, versiones

#### Odoo (Puerto 8069)
- **Descripción:** Sistema ERP completo
- **URL:** https://odoo.tzzrdeck.me
- **Uso:** Facturación, inventario, CRM, recursos humanos
- **Usuarios:** Acceso basado en roles

#### Vaultwarden (Puerto 8085)
- **Descripción:** Gestor de contraseñas empresarial
- **URL:** https://vault.ttzrdeck.me
- **Uso:** Almacenar y gestionar contraseñas de forma segura
- **Integración:** Compatible con Bitwarden

#### Directus (Puerto 8055)
- **Descripción:** CMS y gestor de contenido headless
- **URL:** https://directus.tzzrdeck.me
- **Uso:** Crear y gestionar contenido, APIs automáticas
- **Flexible:** Base de datos agnóstica

#### Shlink (Puerto 8083)
- **Descripción:** Acortador de URLs
- **URL:** https://shlink.tzzrdeck.me
- **Uso:** Crear URLs cortas, rastreo de clics
- **Analytics:** Estadísticas de uso

#### Ntfy (Puerto 8080)
- **Descripción:** Sistema de notificaciones
- **URL:** https://ntfy.tzzrdeck.me
- **Uso:** Enviar notificaciones a través de HTTP
- **Integración:** Webhooks y push notifications

#### FileBrowser (Puerto 8082)
- **Descripción:** Gestor de archivos web
- **URL:** https://files.tzzrdeck.me
- **Uso:** Explorar, descargar, subir archivos
- **Seguridad:** Control de permisos por usuario

### 2.3 Infraestructura de Datos

#### PostgreSQL (Puerto 5432)
- **Descripción:** Base de datos principal del sistema
- **Características:** pgvector activado (búsqueda vectorial para IA)
- **Datos:** Contiene todas las bases de datos del sistema TZZR
- **Backup:** Se realiza automatizado

#### Redis (Puerto 6379)
- **Descripción:** Cache en memoria de alta velocidad
- **Uso:** Cache de sesiones, cache de consultas, pub/sub
- **Rendimiento:** Milisegundos de latencia

### 2.4 Servicios de Correo

#### Mailcow (Puerto 8180)
- **Descripción:** Servidor de correo empresarial completo
- **URL:** https://mail.tzzr.net
- **Servicios incluidos:**
  - SMTP (envío de correos)
  - IMAP/POP3 (lectura de correos)
  - Webmail integrado
  - Filtrado de spam
  - Certificados SSL automáticos
- **Componentes:**
  - Postfix: SMTP
  - Dovecot: IMAP/POP3
  - Nginx: Reverse proxy y webmail
  - MySQL: Base de datos
  - Redis: Cache

**Contenedores Mailcow:**
```
postfix-mailcow   - Servidor SMTP
dovecot-mailcow   - Servidor IMAP/POP3
nginx-mailcow     - Webmail y reverse proxy
mysql-mailcow     - Base de datos
redis-mailcow     - Cache
```

---

## 3. Context-Manager (Gestor de Contexto)

### ¿Qué es Context-Manager?

Context-Manager es una herramienta central que permite a los agentes TZZR:
- Mantener contexto persistente de conversaciones
- Acceder a bloques de contexto previamente creados
- Gestionar memoria de largo plazo
- Compartir información entre agentes

### Instalación y Configuración

Context-Manager está disponible como CLI en DECK. Para verificar su disponibilidad:

```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113 "context-manager --help"
```

### Comandos Principales

#### `context-manager --help`
Muestra ayuda sobre todos los comandos disponibles.

```bash
context-manager --help
```

**Ejemplo de salida:**
```
Context Manager CLI
==================

Comandos:
  block list          - Listar bloques de contexto
  block add           - Crear nuevo bloque
  block view <id>     - Ver contenido de bloque
  block remove <id>   - Eliminar bloque

  memory list         - Listar memorias
  memory add          - Agregar a memoria
  memory clear        - Limpiar memoria

  chat                - Iniciar chat interactivo
```

#### `context-manager block list`
Lista todos los bloques de contexto almacenados.

```bash
context-manager block list
```

**Ejemplo:**
```
ID    | Nombre              | Tipo     | Fecha Creación
------|---------------------|----------|------------------
001   | Historia Clara      | metadata | 2025-12-15 10:30
002   | Configuración TZZR  | config   | 2025-12-20 14:45
003   | Directorio RFC      | reference| 2025-12-28 09:15
```

**Campos:**
- `ID`: Identificador único del bloque
- `Nombre`: Descripción del contenido
- `Tipo`: Categoría (metadata, config, reference, etc.)
- `Fecha Creación`: Cuándo se creó el bloque

#### `context-manager block view <ID>`
Ver el contenido completo de un bloque específico.

```bash
context-manager block view 002
```

**Ejemplo:**
```
Bloque: 002
Nombre: Configuración TZZR
Tipo: config
Creado: 2025-12-20 14:45

Contenido:
---------
{
  "central_ip": "69.62.126.110",
  "servers": {
    "deck": "72.62.1.113",
    "corp": "92.112.181.188",
    "hst": "72.62.2.84"
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "tzzr_main"
  }
}
```

#### `context-manager memory list`
Lista todos los elementos guardados en memoria compartida.

```bash
context-manager memory list
```

**Ejemplo:**
```
Memoria Compartida (15 items)
=============================

1. Clara - Último estado: up
2. Alfred - Procesos pendientes: 3
3. Mason - Últimas transformaciones: 2025-12-29 16:42
4. Feldman - Validaciones en caché: 127
5. PostgreSQL - Conexiones activas: 8
```

#### `context-manager memory add`
Agregar nueva información a memoria compartida.

```bash
context-manager memory add "nombre_clave" "contenido o JSON"
```

**Ejemplo:**
```bash
context-manager memory add "configuracion_temporal" '{"modo": "mantenimiento", "fecha": "2025-12-30"}'
```

#### `context-manager chat`
Inicia una sesión de chat interactivo con Context-Manager (útil para debugging).

```bash
context-manager chat
```

### Ejemplos de Uso Práctico

#### Ejemplo 1: Verificar estado del sistema
```bash
# Ver si hay configuración de mantenimiento
context-manager block view configuracion_mantenimiento

# Revisar estado en memoria
context-manager memory list
```

#### Ejemplo 2: Crear un bloque de contexto para una tarea
```bash
# Los agentes pueden crear bloques para compartir información
context-manager block add "migracion_datos_2025" \
  --tipo "project" \
  --contenido '{"estado": "en_progreso", "agentes": ["clara", "mason"]}'
```

#### Ejemplo 3: Consultar desde un script
```bash
#!/bin/bash
# Script que usa context-manager

CONTEXTO=$(context-manager block view configuracion)
echo "Contexto actual: $CONTEXTO"

# Actualizar estado
context-manager memory add "script_estado" "completado"
```

---

## 4. Gestión de Servicios en DECK

### Comandos Generales de Estado

#### Ver estado del sistema
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker ps -a"
```

Muestra todos los contenedores (activos e inactivos).

#### Ver estadísticas del sistema
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113 "free -h"  # Memoria
ssh -i ~/.ssh/tzzr root@72.62.1.113 "df -h /"  # Disco
ssh -i ~/.ssh/tzzr root@72.62.1.113 "top -bn1" # Procesos
```

### Comandos para Servicios Específicos

#### Obtener estado de un servicio
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker ps --filter name=clara"
```

#### Ver logs de un servicio
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker logs clara-service --tail 50"
```

#### Reiniciar un servicio
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker restart clara-service"
```

#### Detener un servicio
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker stop nextcloud"
```

#### Iniciar un servicio
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker start nextcloud"
```

---

## 5. Acceso a Servicios Web

### URLs de Acceso

Todos los servicios web están disponibles bajo el dominio `tzzrdeck.me`:

| Servicio | URL | Puerto | Usuario Típico |
|----------|-----|--------|-----------------|
| Nextcloud | https://cloud.tzzrdeck.me | 8084 | Tu usuario LDAP |
| Odoo | https://odoo.tzzrdeck.me | 8069 | Tu usuario Odoo |
| Vaultwarden | https://vault.tzzrdeck.me | 8085 | Tu usuario Bitwarden |
| Directus | https://directus.tzzrdeck.me | 8055 | Tu usuario Directus |
| Shlink | https://shlink.tzzrdeck.me | 8083 | Tu usuario Shlink |
| Ntfy | https://ntfy.tzzrdeck.me | 8080 | Sin autenticación* |
| FileBrowser | https://files.tzzrdeck.me | 8082 | Tu usuario local |
| Webmail (Mailcow) | https://mail.tzzr.net | 8180 | Tu email |

*Ntfy puede usarse sin autenticación o con ella según configuración.

### Verificar Conectividad

Para verificar que un servicio está accesible:

```bash
curl -I https://cloud.tzzrdeck.me
curl -I https://mail.tzzr.net
```

Deberías recibir respuesta HTTP 200 o 302 (redirección a login).

---

## 6. Tabla de Referencia Rápida

### Puertos Principales en DECK

```
5051 - Clara (Log inmutable)
5052 - Alfred (Automatización)
5053 - Mason (Enriquecimiento)
5054 - Feldman (Validador Merkle)

5432 - PostgreSQL
6379 - Redis

8055 - Directus
8069 - Odoo
8080 - Ntfy
8082 - FileBrowser
8083 - Shlink
8084 - Nextcloud
8085 - Vaultwarden
8180 - Mailcow

22   - SSH
```

### Comandos Rápidos

```bash
# Conectar a DECK
ssh -i ~/.ssh/tzzr root@72.62.1.113

# Ver todos los servicios
docker ps -a

# Ver memoria y disco
free -h && df -h /

# Ver logs de Clara
docker logs clara-service -f

# Reiniciar Nextcloud
docker restart nextcloud
```

---

## 7. Próximas Partes del Manual

Este es el **PARTE 1** del manual. Las siguientes partes cubrirán:

- **PARTE 2:** Guía de Usuarios - Acceso a aplicaciones web
- **PARTE 3:** Gestión de Correo - Administración de Mailcow
- **PARTE 4:** Backup y Recuperación
- **PARTE 5:** Troubleshooting y Resolución de Problemas
- **PARTE 6:** Integración y APIs de Servicios TZZR

---

## 8. Soporte y Contacto

Para problemas o consultas:

1. **Verificar logs:** `docker logs <servicio>`
2. **Revisar documentación:** Contactar al equipo de ARCHITECT
3. **Escalation:** Reportar al coordinador central (CAPTAIN CLAUDE)

---

**Última actualización:** 2025-12-30
**Versión:** 1.0
**Aplicable a:** DECK (72.62.1.113)
# Manual de Usuario DECK (72.62.1.113) - PARTE 2
## PostgreSQL y Administración

**Versión:** 1.0
**Fecha:** 2025-12-30
**Sistema:** TZZR - Infraestructura Centralizada

---

## 1. PostgreSQL

### 1.1 Conexión a PostgreSQL

#### Conexión como usuario postgres
```bash
sudo -u postgres psql -d tzzr
```

#### Parámetros comunes
- **Host:** localhost (por defecto)
- **Puerto:** 5432 (por defecto)
- **Usuario:** postgres
- **Base de datos:** tzzr

#### Comandos básicos en psql
```bash
\l                          # Listar bases de datos
\c [nombre_db]              # Conectar a una base de datos
\dt                         # Listar tablas
\d [nombre_tabla]           # Describir estructura de tabla
\du                         # Listar usuarios/roles
\q                          # Salir
\h                          # Ayuda de comandos SQL
```

### 1.2 Bases de Datos

#### Base de datos: `tzzr`
Base de datos principal del sistema TZZR.

#### Base de datos: `deck`
Base de datos específica del servidor DECK.

#### Ver todas las bases de datos
```bash
sudo -u postgres psql -c "\l"
```

### 1.3 Tablas Principales del Context-Manager

El context-manager gestiona las siguientes tablas en la base de datos `tzzr`:

#### Tabla: `immutable_log`
Registro inmutable de todas las operaciones del sistema.

```bash
# Ver estructura
sudo -u postgres psql -d tzzr -c "\d immutable_log"

# Ver últimas 10 entradas
sudo -u postgres psql -d tzzr -c "SELECT * FROM immutable_log ORDER BY timestamp DESC LIMIT 10;"
```

#### Tabla: `context_state`
Estado actual del contexto del sistema.

```bash
# Ver estado actual
sudo -u postgres psql -d tzzr -c "SELECT * FROM context_state;"
```

#### Tabla: `algorithm_engine`
Configuración y estado del motor de algoritmos.

```bash
# Ver configuración
sudo -u postgres psql -d tzzr -c "SELECT * FROM algorithm_engine;"
```

#### Tabla: `agents`
Registro de agentes activos en el sistema.

```bash
# Ver agentes activos
sudo -u postgres psql -d tzzr -c "SELECT * FROM agents WHERE active = true;"
```

#### Tabla: `audit_log`
Registro de auditoría de todas las operaciones administrativas.

```bash
# Ver auditoría reciente
sudo -u postgres psql -d tzzr -c "SELECT * FROM audit_log ORDER BY timestamp DESC LIMIT 20;"
```

### 1.4 Consultas Útiles

#### Verificar integridad de la base de datos
```bash
sudo -u postgres psql -d tzzr -c "
  SELECT schemaname, tablename, pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size
  FROM pg_tables
  WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
  ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;"
```

#### Verificar conexiones activas
```bash
sudo -u postgres psql -d tzzr -c "
  SELECT pid, usename, application_name, client_addr, state
  FROM pg_stat_activity
  WHERE pid <> pg_backend_pid();"
```

#### Verificar índices
```bash
sudo -u postgres psql -d tzzr -c "
  SELECT schemaname, tablename, indexname
  FROM pg_indexes
  WHERE schemaname NOT IN ('pg_catalog', 'information_schema');"
```

---

## 2. Administración

### 2.1 Comandos Docker Útiles

#### Ver estado de contenedores
```bash
docker ps                   # Contenedores activos
docker ps -a                # Todos los contenedores
docker status               # Estado general de Docker
```

#### Gestionar contenedores
```bash
docker start [container_id]         # Iniciar contenedor
docker stop [container_id]          # Detener contenedor
docker restart [container_id]       # Reiniciar contenedor
docker logs [container_id]          # Ver logs
docker logs -f [container_id]       # Logs en tiempo real
docker exec -it [container_id] bash # Acceso interactivo
```

#### Gestionar imágenes
```bash
docker images               # Listar imágenes
docker pull [image]         # Descargar imagen
docker rmi [image_id]       # Eliminar imagen
docker image prune          # Limpiar imágenes no usadas
```

#### Ver recursos
```bash
docker stats                # Uso de CPU/memoria en tiempo real
docker system df            # Uso de disco
```

### 2.2 Logs y Diagnóstico

#### Logs de PostgreSQL
```bash
# Si PostgreSQL está en Docker
docker logs [postgres_container_id] | tail -100

# Si PostgreSQL está en el host
sudo tail -100 /var/log/postgresql/postgresql.log
```

#### Logs de Gitea
```bash
docker logs [gitea_container_id] | tail -100
```

#### Logs del sistema
```bash
sudo journalctl -xe          # Últimos errores del sistema
sudo journalctl -u docker    # Logs específicos de Docker
dmesg | tail -50             # Logs del kernel
```

#### Diagnóstico de red
```bash
netstat -tlnp               # Puertos escuchando
ss -tlnp                    # Alternativa moderna de netstat
ping 69.62.126.110          # Conectividad con servidor central
```

#### Verificar espacio en disco
```bash
df -h                       # Espacio en particiones
du -sh /*                   # Uso por directorio
du -sh /var/lib/docker/*    # Uso de Docker
```

### 2.3 Backups

#### Backup manual de PostgreSQL
```bash
# Backup completo de la base de datos tzzr
sudo -u postgres pg_dump tzzr > /tmp/tzzr_backup_$(date +%Y%m%d_%H%M%S).sql

# Backup de una tabla específica
sudo -u postgres pg_dump tzzr -t immutable_log > /tmp/immutable_log_backup.sql
```

#### Restaurar desde backup
```bash
# Restaurar base de datos completa
sudo -u postgres psql tzzr < /tmp/tzzr_backup.sql

# Restaurar tabla específica (cuidado: borra la tabla actual)
sudo -u postgres psql tzzr < /tmp/immutable_log_backup.sql
```

#### Backup de Gitea
```bash
# Ver documentación de Gitea para backup
docker exec [gitea_container] /app/gitea dump -c /etc/gitea/app.ini
```

#### Automático: Script de backup diario
```bash
#!/bin/bash
# Guardar como /opt/scripts/backup_daily.sh

BACKUP_DIR="/backups/postgresql"
DB_NAME="tzzr"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

sudo -u postgres pg_dump $DB_NAME > $BACKUP_DIR/tzzr_$DATE.sql
gzip $BACKUP_DIR/tzzr_$DATE.sql

# Eliminar backups más antiguos de 30 días
find $BACKUP_DIR -name "tzzr_*.sql.gz" -mtime +30 -delete

echo "Backup completado: $BACKUP_DIR/tzzr_$DATE.sql.gz"
```

Configurar en cron:
```bash
# Editar crontab
sudo crontab -e

# Agregar línea (backup diario a las 2:00 AM)
0 2 * * * /opt/scripts/backup_daily.sh >> /var/log/backup.log 2>&1
```

---

## 3. Troubleshooting

### 3.1 Problemas Comunes y Soluciones

#### Problema: No se puede conectar a PostgreSQL
```bash
# Verificar que PostgreSQL está corriendo
sudo systemctl status postgresql
# o si está en Docker:
docker ps | grep postgres

# Verificar puerto 5432
sudo netstat -tlnp | grep 5432

# Ver logs de PostgreSQL
sudo tail -50 /var/log/postgresql/postgresql.log

# Reiniciar PostgreSQL
sudo systemctl restart postgresql
# o si está en Docker:
docker restart [postgres_container_id]
```

#### Problema: Espacio en disco bajo
```bash
# Ver distribución de espacio
du -sh /* | sort -rh

# Limpiar logs antiguos
sudo journalctl --vacuum=30d

# Limpiar Docker
docker system prune -a --volumes

# Limpiar cache de PostgreSQL
sudo -u postgres psql -d tzzr -c "VACUUM ANALYZE;"
```

#### Problema: Conexiones agotadas a PostgreSQL
```bash
# Ver conexiones activas
sudo -u postgres psql -d tzzr -c "SELECT * FROM pg_stat_activity;"

# Terminar conexión específica
sudo -u postgres psql -d tzzr -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE pid <> pg_backend_pid();"

# Ver configuración de conexiones máximas
sudo -u postgres psql -d tzzr -c "SHOW max_connections;"
```

#### Problema: Base de datos bloqueada
```bash
# Ver transacciones abiertas
sudo -u postgres psql -d tzzr -c "SELECT * FROM pg_stat_activity WHERE state != 'idle';"

# Ver locks
sudo -u postgres psql -d tzzr -c "SELECT * FROM pg_locks;"

# Terminar transacción bloqueada
sudo -u postgres psql -d tzzr -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE pid = [PID];"
```

#### Problema: Docker fuera de espacio
```bash
# Ver uso de Docker
docker system df

# Limpiar imágenes sin usar
docker image prune -a

# Limpiar volúmenes sin usar
docker volume prune

# Limpiar redes sin usar
docker network prune

# Limpieza total (cuidado!)
docker system prune -a --volumes
```

#### Problema: Gitea no responde
```bash
# Ver estado del contenedor
docker ps | grep gitea

# Reiniciar Gitea
docker restart [gitea_container_id]

# Ver logs
docker logs [gitea_container_id] | tail -100

# Acceso a terminal de Gitea
docker exec -it [gitea_container_id] bash
```

#### Problema: Alto uso de CPU/memoria
```bash
# Ver uso en tiempo real
docker stats

# Identificar proceso problemático
ps aux | sort -k3 -rn | head -5    # Por CPU
ps aux | sort -k4 -rn | head -5    # Por memoria

# Ver procesos de PostgreSQL
ps aux | grep postgres

# Limitar recursos de contenedor (si es necesario)
docker update --memory 4g [container_id]
```

### 3.2 Contactos de Soporte

#### Contactos Técnicos

| Rol | Contacto | Disponibilidad |
|-----|----------|-----------------|
| **ARCHITECT** | architect@tzzr.local | Tiempo completo |
| **CAPTAIN CLAUDE** | captain@tzzr.local | Tiempo completo |
| **Soporte DB** | dba@tzzr.local | L-V 8AM-6PM |
| **Soporte Infraestructura** | infra@tzzr.local | 24/7 |

#### Escalation Path
1. Contactar equipo de soporte directo
2. Crear ticket en Gitea: https://69.62.126.110/gitea
3. SSH a servidor central: `ssh architect@69.62.126.110`
4. Activar modo debug si es necesario

#### Información para reportar problemas
Cuando reportes un problema, incluye:
- Fecha y hora exacta del incidente
- Mensajes de error completos
- Output de diagnósticos relevantes:
  ```bash
  docker ps -a
  docker logs [container_id]
  df -h
  free -h
  sudo -u postgres psql -d tzzr -c "SELECT * FROM pg_stat_activity;"
  ```
- Pasos para reproducir el problema

### 3.3 Verificación de Salud del Sistema

Script de diagnóstico completo:
```bash
#!/bin/bash
# Guardar como /opt/scripts/health_check.sh

echo "=== SALUD DEL SISTEMA DECK ==="
echo ""
echo "1. Estado de Docker:"
docker ps -a
echo ""
echo "2. Uso de Recursos:"
free -h
df -h
echo ""
echo "3. Conectividad PostgreSQL:"
sudo -u postgres psql -d tzzr -c "SELECT version();"
echo ""
echo "4. Conexiones Activas:"
sudo -u postgres psql -d tzzr -c "SELECT COUNT(*) FROM pg_stat_activity;"
echo ""
echo "5. Conectividad con servidor central:"
ping -c 1 69.62.126.110
echo ""
echo "=== FIN DIAGNÓSTICO ==="
```

Ejecutar:
```bash
chmod +x /opt/scripts/health_check.sh
/opt/scripts/health_check.sh
```

---

## Apéndice: Atajos Útiles

### Alias recomendados para .bashrc
```bash
alias pgconnect='sudo -u postgres psql -d tzzr'
alias dockerps='docker ps -a --format "table {{.ID}}\t{{.Names}}\t{{.Status}}\t{{.Ports}}"'
alias dstats='docker stats --no-stream'
alias dblog='sudo tail -f /var/log/postgresql/postgresql.log'
alias sysdump='cd /tmp && docker ps -a > docker_status.txt && df -h > disk_status.txt && free -h > memory_status.txt && ps aux > process_status.txt'
```

Cargar alias:
```bash
source ~/.bashrc
```

---

**Fin del Manual - PARTE 2**

Para más información sobre PARTE 1 (Primeros Pasos y Servicios), consulta el manual anterior.

Fecha de última actualización: 2025-12-30
# DECK - Manual de Usuario PARTE 3: Guías Rápidas

## 1. Guía Rápida de Inicio

### Primeros Pasos

Cuando accedas a DECK por primera vez:

```bash
# 1. Conéctate al servidor
ssh root@72.62.1.113

# 2. Verifica que estés en el directorio correcto
pwd
# Deberías estar en /root

# 3. Visualiza la estructura general
ls -la
```

### Verificar Servicios con Docker

Para asegurar que todos los servicios están funcionando:

```bash
# Ver todos los contenedores activos
docker ps

# Ver todos los contenedores (incluyendo detenidos)
docker ps -a

# Ver logs de un servicio específico
docker logs -f nombre_contenedor

# Ejemplo: Ver logs de Mailcow
docker logs -f mailcow-mailserver-1
```

**Servicios esperados:**
- `mailcow-mailserver-1` - Servidor de correo
- `nextcloud-app-1` - Gestor de archivos
- `vaultwarden-app-1` - Gestor de contraseñas
- `postgres-db-1` - Base de datos
- Base de datos local de context-manager

### Verificar PostgreSQL

PostgreSQL es crítico para context-manager y otros servicios:

```bash
# Acceder a PostgreSQL
docker exec -it postgres-db-1 psql -U postgres

# Dentro de psql, ver bases de datos
\l

# Ver usuarios
\du

# Conectar a una base de datos específica
\c nombre_base_datos

# Ver tablas
\dt

# Salir
\q

# Alternativa: Verificar desde el host
sudo systemctl status postgresql
```

**Status esperado:**
- PostgreSQL debe estar `active (running)`
- Puerto 5432 debe estar escuchando

---

## 2. Casos de Uso Comunes

### Caso 1: Enviar Correo con Mailcow

#### Acceder a la interfaz web
```
URL: https://deck.local/mailcow
o
URL: https://72.62.1.113/mailcow
```

#### Crear usuario de correo
1. Accede a **Mail → Mailboxes**
2. Haz clic en **+ Add Mailbox**
3. Completa:
   - **Local part**: (el nombre antes del @)
   - **Domain**: (selecciona dominio)
   - **Password**: (contraseña segura)
4. Haz clic en **Add**

#### Usar desde cliente de correo (Outlook, Thunderbird, Apple Mail)
```
Servidor IMAP: mail.deck.local (o IP del servidor)
Puerto IMAP: 993 (SSL/TLS)
Servidor SMTP: mail.deck.local
Puerto SMTP: 465 (SSL/TLS)
Usuario: correo@dominio.com
Contraseña: (la que configuraste)
```

#### Verificar correos desde terminal
```bash
# Acceder al contenedor de Mailcow
docker exec -it mailcow-mailserver-1 bash

# Verificar logs de correos
tail -f /var/log/mail.log

# Salir
exit
```

### Caso 2: Usar Nextcloud (Gestor de Archivos)

#### Acceder a la interfaz web
```
URL: https://deck.local/nextcloud
o
URL: https://72.62.1.113/nextcloud
```

#### Crear usuario en Nextcloud
1. Accede como administrador
2. Haz clic en el icono de usuario (arriba a la derecha)
3. Selecciona **Usuarios**
4. Haz clic en **+ Nuevo usuario**
5. Completa:
   - **Nombre de usuario**
   - **Contraseña**
6. Asigna grupos si es necesario
7. Haz clic en **Crear**

#### Subir archivos
1. Accede a Nextcloud
2. Haz clic en **+ (botón azul)** → **Subir archivo**
3. Selecciona archivo desde tu computadora
4. El archivo se sincronizará automáticamente

#### Sincronizar con tu computadora
1. Descarga el cliente Nextcloud: https://nextcloud.com/install/
2. Instala y abre el cliente
3. Completa:
   - **Servidor**: https://72.62.1.113/nextcloud
   - **Usuario y contraseña**: Usa las credenciales de Nextcloud
4. Selecciona carpeta local para sincronizar
5. ¡Listo! Los archivos se sincronizarán automáticamente

### Caso 3: Gestionar Contraseñas con Vaultwarden

#### Acceder a Vaultwarden
```
URL: https://deck.local/vaultwarden
o
URL: https://72.62.1.113/vaultwarden
```

#### Crear cuenta
1. Haz clic en **Create account**
2. Completa:
   - **Email**: Tu correo
   - **Master password**: Contraseña maestra (muy importante, no la olvides)
3. Haz clic en **Create account**

#### Agregar contraseña
1. Accede a Vaultwarden
2. Haz clic en **+ New item** (botón azul)
3. Selecciona **Login**
4. Completa:
   - **Name**: Nombre del servicio (ej: Gmail, GitHub)
   - **Username**: Tu usuario
   - **Password**: Tu contraseña (o genera una)
5. Haz clic en **Save**

#### Generar contraseña segura
1. Al crear/editar un login
2. Haz clic en el icono **🔄 Generate** junto al campo de contraseña
3. Ajusta las opciones:
   - **Length**: Longitud (16+ recomendado)
   - **Uppercase**: Incluir mayúsculas
   - **Lowercase**: Incluir minúsculas
   - **Numbers**: Incluir números
   - **Special**: Incluir caracteres especiales
4. Haz clic en **Regenerate** hasta estar satisfecho
5. Haz clic en **Select**

#### Usar en otros dispositivos
- **Extensión navegador**: Bitwarden/Vaultwarden para Chrome, Firefox, Edge
- **Aplicación móvil**: Descargar "Bitwarden" desde App Store o Google Play
- **Sincronización**: Se sincroniza automáticamente entre dispositivos

### Caso 4: Usar context-manager para Chat IA

#### Acceder a context-manager
```bash
# Desde la terminal de DECK
ssh root@72.62.1.113

# Ir a la carpeta de context-manager
cd /root/captain-claude/context-manager

# Ver estado
docker ps | grep context
# O si se ejecuta como servicio
systemctl status context-manager
```

#### Configurar context-manager
```bash
# 1. Verificar archivo de configuración
cat /root/captain-claude/context-manager/.env

# Debe contener:
# - API_KEY de Anthropic o OpenAI
# - URL de PostgreSQL
# - Configuración de base de datos

# 2. Si necesitas cambiar configuración
nano /root/captain-claude/context-manager/.env

# 3. Reiniciar servicio
docker restart context-manager-app-1
# O si es servicio del sistema
systemctl restart context-manager
```

#### Usar context-manager desde API
```bash
# Ejemplo: Enviar consulta y obtener respuesta con contexto

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "¿Cuál es la temperatura actual?",
    "context_type": "sensor_data",
    "session_id": "session-123"
  }'

# Respuesta esperada:
# {
#   "response": "La temperatura es de 22°C",
#   "context_used": ["sensor_data"],
#   "timestamp": "2025-01-15T10:30:00Z"
# }
```

#### Ver logs de context-manager
```bash
# Ver logs en tiempo real
docker logs -f context-manager-app-1

# O si es servicio del sistema
journalctl -u context-manager -f
```

---

## 3. Comandos Frecuentes

### Servicios y Estado

| Comando | Descripción |
|---------|-------------|
| `docker ps` | Ver contenedores activos |
| `docker ps -a` | Ver todos los contenedores |
| `docker logs -f nombre` | Ver logs en tiempo real |
| `docker restart nombre` | Reiniciar contenedor |
| `docker stop nombre` | Detener contenedor |
| `docker start nombre` | Iniciar contenedor |
| `systemctl status` | Ver estado de servicios del sistema |
| `systemctl restart nombre` | Reiniciar servicio |

### Base de Datos (PostgreSQL)

| Comando | Descripción |
|---------|-------------|
| `docker exec -it postgres psql -U postgres` | Acceder a psql |
| `\l` | Listar bases de datos (dentro de psql) |
| `\dt` | Listar tablas (dentro de psql) |
| `\du` | Listar usuarios (dentro de psql) |
| `\q` | Salir de psql |

### Sistema de Archivos

| Comando | Descripción |
|---------|-------------|
| `ls -la` | Listar archivos con detalles |
| `cd /ruta` | Cambiar de directorio |
| `pwd` | Mostrar directorio actual |
| `mkdir nombre` | Crear directorio |
| `cp archivo destino` | Copiar archivo |
| `mv archivo destino` | Mover archivo |
| `rm archivo` | Eliminar archivo |
| `rm -rf carpeta` | Eliminar carpeta completa |

### Red y Conectividad

| Comando | Descripción |
|---------|-------------|
| `ping host` | Verificar conexión |
| `netstat -tulpn` | Ver puertos en escucha |
| `curl http://url` | Hacer solicitud HTTP |
| `ss -tulpn` | Alternativa moderna a netstat |
| `dig dominio.com` | Resolver DNS |
| `nslookup dominio.com` | Alternativa a dig |

### SSH y Acceso Remoto

| Comando | Descripción |
|---------|-------------|
| `ssh root@72.62.1.113` | Conectar a DECK |
| `ssh-copy-id -i ~/.ssh/tzzr root@72.62.1.113` | Copiar clave SSH |
| `ssh -i ~/.ssh/tzzr root@72.62.1.113` | Conectar con clave específica |
| `scp archivo root@72.62.1.113:/destino` | Copiar archivo a servidor |

### Monitoreo y Rendimiento

| Comando | Descripción |
|---------|-------------|
| `top` | Monitor de procesos |
| `htop` | Monitor mejorado (si está instalado) |
| `df -h` | Espacio en disco |
| `du -sh carpeta` | Tamaño de carpeta |
| `free -h` | Uso de RAM |
| `uptime` | Tiempo de actividad del servidor |

---

## 4. Atajos y Tips Productivos

### Tips Generales

**1. Usa alias para comandos frecuentes**
```bash
# Editar ~/.bashrc
nano ~/.bashrc

# Agregar alias
alias ll='ls -la'
alias dc='docker ps'
alias psql-con='docker exec -it postgres-db-1 psql -U postgres'

# Guardar y aplicar cambios
source ~/.bashrc
```

**2. Historial de comandos**
```bash
# Ver últimos comandos
history

# Ejecutar comando anterior
!!

# Ejecutar comando que contiene "palabra"
!palabra

# Buscar en historial
Ctrl + R (luego escribe para buscar)
```

**3. Copiar/Pegar eficientemente**
```bash
# Copiar salida de comando
comando | xclip -selection clipboard

# O más simple, seleccionar con ratón en terminal
```

### Tips para Docker

**1. Ver logs en tiempo real con seguimiento de errores**
```bash
# Ver últimas 100 líneas
docker logs --tail 100 nombre_contenedor

# Ver con timestamp
docker logs -t nombre_contenedor

# Seguir logs en tiempo real
docker logs -f --tail 20 nombre_contenedor
```

**2. Ejecutar comandos dentro de contenedores**
```bash
# Acceso interactivo (bash)
docker exec -it nombre_contenedor bash

# Ejecutar comando específico
docker exec nombre_contenedor ls -la

# Con variable de entorno
docker exec -e VAR=valor nombre_contenedor comando
```

**3. Gestionar múltiples contenedores**
```bash
# Detener todos los contenedores
docker stop $(docker ps -q)

# Eliminar contenedores parados
docker container prune

# Ver uso de recursos
docker stats
```

### Tips para PostgreSQL

**1. Backups rápidos**
```bash
# Crear backup
docker exec postgres-db-1 pg_dump -U postgres nombre_base > backup.sql

# Restaurar backup
docker exec -i postgres-db-1 psql -U postgres < backup.sql
```

**2. Consultas útiles**
```bash
# Dentro de psql:

-- Ver tamaño de tablas
SELECT schemaname, tablename, pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename))
FROM pg_tables ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;

-- Ver conexiones activas
SELECT * FROM pg_stat_activity;

-- Matar conexión
SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname='base_datos';
```

### Tips para Nextcloud

**1. Sincronización manual**
```bash
# Forzar verificación de cambios
# (Espera 30 segundos en el cliente de Nextcloud)

# O rescanea el servidor
docker exec -it nextcloud-app-1 php occ files:scan --all
```

**2. Gestionar espacio**
```bash
# Ver uso de espacio en Nextcloud
docker exec -it nextcloud-app-1 php occ statistics:get

# Eliminar versiones antiguas (liberar espacio)
docker exec -it nextcloud-app-1 php occ versions:cleanup
```

### Tips para Vaultwarden

**1. Exportar contraseñas (Backup)**
```
En la interfaz de Vaultwarden:
1. Haz clic en icono de usuario → Settings
2. Selecciona "Import/Export"
3. Haz clic en "Export vault"
4. Guarda el archivo CSV en lugar seguro
```

**2. Importar desde otro gestor de contraseñas**
```
1. En el otro gestor (LastPass, 1Password, etc):
   - Exporta en formato CSV
2. En Vaultwarden:
   - Haz clic en usuario → Settings
   - Selecciona "Import/Export"
   - Haz clic en "Import"
   - Selecciona archivo CSV
```

---

## Próximos Pasos

Si necesitas ayuda adicional:
- **Problemas técnicos**: Revisa logs con `docker logs -f nombre`
- **Configuración avanzada**: Ver DECK - Manual de Usuario PARTE 2
- **Solución de problemas**: Ver sección de Troubleshooting en el manual
- **Contacto**: Consulta con el administrador del sistema