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:

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:

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:

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

Comandos Principales

context-manager --help

Muestra ayuda sobre todos los comandos disponibles.

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.

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.

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.

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.

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

Ejemplo:

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

context-manager chat

Ejemplos de Uso Práctico

Ejemplo 1: Verificar estado del sistema

# 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

# 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

#!/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

ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker ps -a"

Muestra todos los contenedores (activos e inactivos).

Ver estadísticas del sistema

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

ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker ps --filter name=clara"

Ver logs de un servicio

ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker logs clara-service --tail 50"

Reiniciar un servicio

ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker restart clara-service"

Detener un servicio

ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker stop nextcloud"

Iniciar un servicio

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:

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

# 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

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

\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

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.

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

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

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

Tabla: agents

Registro de agentes activos en el sistema.

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

# 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

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

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

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

docker ps                   # Contenedores activos
docker ps -a                # Todos los contenedores
docker status               # Estado general de Docker

Gestionar contenedores

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

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

docker stats                # Uso de CPU/memoria en tiempo real
docker system df            # Uso de disco

2.2 Logs y Diagnóstico

Logs de PostgreSQL

# 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

docker logs [gitea_container_id] | tail -100

Logs del sistema

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

netstat -tlnp               # Puertos escuchando
ss -tlnp                    # Alternativa moderna de netstat
ping 69.62.126.110          # Conectividad con servidor central

Verificar espacio en disco

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

# 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

# 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

# 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

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

  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:

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

chmod +x /opt/scripts/health_check.sh
/opt/scripts/health_check.sh

---

Apéndice: Atajos Útiles

Alias recomendados para .bashrc

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:

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:

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

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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