# Servidor Personal tzzr.net — Actualización Repositorio GitHub

## Contexto

Servidor personal autoalojado en Hostinger VPS (Ubuntu 22.04, 8GB RAM, 100GB SSD).
Función: máquina personal del usuario, punto de entrada privado al ecosistema.

**IP**: 72.62.1.113  
**Dominio**: tzzr.net  
**Hostname**: box.tzzr.net

---

## Arquitectura Actual

```
                    [Cloudflare DNS]
                          │
                    [72.62.1.113]
                          │
        ┌─────────────────┴─────────────────┐
        │                                   │
  [Mail-in-a-Box]                    [Docker Stack]
   Puertos 25,443,993                 Puertos internos
        │                                   │
   ┌────┴────┐              ┌───────────────┼───────────────┐
   │         │              │       │       │       │       │
 Email   Nextcloud     PostgreSQL NocoDB  Shlink  Addy  Vaultwarden
 (box)   (/cloud)        5432    8081    8083   8084    8085
                                   │
                              FileBrowser
                                 8082
```

---

## Servicios Docker

| Servicio | Puerto | Subdominio | Imagen |
|----------|--------|------------|--------|
| PostgreSQL 15 | 5432 | (interno) | postgres:15-alpine |
| NocoDB | 8081 | db.tzzr.net | nocodb/nocodb:latest |
| FileBrowser | 8082 | files.tzzr.net | filebrowser/filebrowser:latest |
| Shlink | 8083 | s.tzzr.net | shlinkio/shlink:stable |
| Addy.io | 8084 | alias.tzzr.net | anonaddy/anonaddy:latest |
| Redis | 6379 | (interno) | redis:alpine |
| Vaultwarden | 8085 | pass.tzzr.net | vaultwarden/server:latest |

---

## Tarea: Actualizar Repositorio GitHub

### Estructura de Archivos del Repositorio

```
tzzr-server/
├── README.md                    # Documentación principal
├── docker-compose.yml           # Stack de servicios
├── init.sql                     # Schema PostgreSQL completo
├── nginx/
│   └── services.conf            # Configuración reverse proxy
├── scripts/
│   ├── backup.sh                # Script de backup diario
│   ├── mail-processor.py        # Procesar correos → mail_registry
│   └── hst-sync.py              # Sincronización etiquetas HST
├── dns/
│   └── tzzr_net.zone            # Registros DNS para Cloudflare
└── docs/
    ├── INSTALACION.md           # Guía de instalación desde cero
    ├── CLONACION.md             # Guía para clonar a nuevo usuario
    └── CREDENCIALES.template    # Plantilla de credenciales (sin valores reales)
```

---

## Schema PostgreSQL (init.sql)

### Tablas de Etiquetas HST

Crear 4 tablas con estructura idéntica:

```sql
-- hst_tags_sistema: Sync desde tzrtech.org (grupo: hst)
-- hst_tags_empresa: Sync desde servidor empresa (grupo: emp)
-- hst_tags_usuario: Etiquetas personales (grupo: hsu)
-- hst_tags_proyecto: Etiquetas de proyecto (grupo: pjt)

CREATE TABLE IF NOT EXISTS hst_tags_sistema (
    id SERIAL PRIMARY KEY,
    h_maestro VARCHAR(64) UNIQUE,           -- SHA-256, identificador único
    codigo VARCHAR(50) NOT NULL,            -- Código corto memorable
    nombre VARCHAR(100) NOT NULL,           -- Nombre legible
    nombre_en VARCHAR(100),                 -- Nombre en inglés (opcional)
    descripcion TEXT,
    imagen_url TEXT,                        -- URL externa a la imagen (no blob)
    color VARCHAR(7),                       -- Color hex (#RRGGBB)
    grupo VARCHAR(10) DEFAULT 'hst',        -- hst, emp, hsu, pjt
    padre_h_maestro VARCHAR(64),            -- Jerarquía: referencia al padre
    activo BOOLEAN DEFAULT true,
    metadata JSONB,                         -- Datos adicionales flexibles
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    synced_at TIMESTAMP                     -- Última sincronización (para hst/emp)
);

-- Repetir estructura para: hst_tags_empresa, hst_tags_usuario, hst_tags_proyecto
-- Cambiar DEFAULT de 'grupo' según corresponda: 'emp', 'hsu', 'pjt'
```

**Índices requeridos:**
```sql
CREATE INDEX idx_hst_sistema_h_maestro ON hst_tags_sistema(h_maestro);
CREATE INDEX idx_hst_sistema_codigo ON hst_tags_sistema(codigo);
CREATE INDEX idx_hst_sistema_grupo ON hst_tags_sistema(grupo);
CREATE INDEX idx_hst_sistema_padre ON hst_tags_sistema(padre_h_maestro);
```

### Tabla mail_registry

```sql
CREATE TABLE IF NOT EXISTS mail_registry (
    id SERIAL PRIMARY KEY,
    message_id VARCHAR(255) UNIQUE,         -- Message-ID del correo
    
    -- Direcciones
    from_address VARCHAR(255) NOT NULL,
    to_address VARCHAR(255) NOT NULL,
    cc_address TEXT,                        -- Puede ser múltiple
    reply_to VARCHAR(255),
    
    -- Contenido
    subject TEXT,
    body_preview TEXT,                      -- Primeras 500 palabras
    
    -- Fechas
    date_sent TIMESTAMP,
    date_received TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    -- Adjuntos
    has_attachments BOOLEAN DEFAULT false,
    attachment_count INTEGER DEFAULT 0,
    attachment_paths JSONB,                 -- Array de rutas en FileBrowser
    
    -- Clasificación
    direction VARCHAR(10) NOT NULL,         -- 'inbound' o 'outbound'
    folder VARCHAR(100) DEFAULT 'INBOX',
    is_spam BOOLEAN DEFAULT false,
    spam_score DECIMAL(5,2),
    read_status BOOLEAN DEFAULT false,
    
    -- Etiquetado
    tags JSONB,                             -- Array de h_maestro
    
    -- Procesamiento IA
    processed_by_ia BOOLEAN DEFAULT false,
    ia_classification JSONB,                -- Resultado del clasificador
    ia_processed_at TIMESTAMP,
    
    -- Metadata
    size_bytes INTEGER,
    headers JSONB,                          -- Headers relevantes
    metadata JSONB,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Índices
CREATE INDEX idx_mail_registry_message_id ON mail_registry(message_id);
CREATE INDEX idx_mail_registry_from ON mail_registry(from_address);
CREATE INDEX idx_mail_registry_to ON mail_registry(to_address);
CREATE INDEX idx_mail_registry_date ON mail_registry(date_received);
CREATE INDEX idx_mail_registry_direction ON mail_registry(direction);
CREATE INDEX idx_mail_registry_tags ON mail_registry USING GIN(tags);

-- Constraint para direction
ALTER TABLE mail_registry 
ADD CONSTRAINT chk_direction CHECK (direction IN ('inbound', 'outbound'));
```

### Tabla log_personal

```sql
CREATE TABLE IF NOT EXISTS log_personal (
    id SERIAL PRIMARY KEY,
    tipo VARCHAR(50) NOT NULL,              -- nota, recordatorio, evento, etc.
    titulo VARCHAR(255),
    descripcion TEXT,
    fecha_evento TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    tags JSONB,                             -- Array de h_maestro
    metadata JSONB,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_log_personal_tipo ON log_personal(tipo);
CREATE INDEX idx_log_personal_fecha ON log_personal(fecha_evento);
CREATE INDEX idx_log_personal_tags ON log_personal USING GIN(tags);
```

### Tabla log_sistema

```sql
CREATE TABLE IF NOT EXISTS log_sistema (
    id SERIAL PRIMARY KEY,
    tipo_evento VARCHAR(50) NOT NULL,       -- Tipo de evento (ver enum abajo)
    nivel VARCHAR(20) NOT NULL DEFAULT 'INFO', -- INFO, WARNING, ERROR, DEBUG
    servicio VARCHAR(100),                  -- Servicio origen
    mensaje TEXT NOT NULL,
    detalles JSONB,                         -- Datos estructurados del evento
    
    -- Contexto
    ip_origen VARCHAR(45),
    usuario VARCHAR(100),
    trace_id VARCHAR(64),                   -- Para correlacionar eventos
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Tipos de evento permitidos
COMMENT ON COLUMN log_sistema.tipo_evento IS 
'Valores: mail_received, mail_sent, file_uploaded, file_downloaded, 
login, logout, api_call, sync_hst, sync_emp, backup_started, 
backup_completed, backup_failed, error, warning, service_start, service_stop';

CREATE INDEX idx_log_sistema_tipo ON log_sistema(tipo_evento);
CREATE INDEX idx_log_sistema_nivel ON log_sistema(nivel);
CREATE INDEX idx_log_sistema_fecha ON log_sistema(created_at);
CREATE INDEX idx_log_sistema_servicio ON log_sistema(servicio);
CREATE INDEX idx_log_sistema_trace ON log_sistema(trace_id);
```

### Tablas Auxiliares

```sql
-- Aliases de correo (tracking de Addy.io)
CREATE TABLE IF NOT EXISTS mail_aliases (
    id SERIAL PRIMARY KEY,
    alias VARCHAR(255) UNIQUE NOT NULL,
    destino VARCHAR(255) NOT NULL,
    descripcion TEXT,
    activo BOOLEAN DEFAULT true,
    contador_uso INTEGER DEFAULT 0,
    ultimo_uso TIMESTAMP,
    tags JSONB,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- URLs acortadas (tracking adicional a Shlink)
CREATE TABLE IF NOT EXISTS short_urls (
    id SERIAL PRIMARY KEY,
    short_code VARCHAR(50) UNIQUE NOT NULL,
    url_original TEXT NOT NULL,
    titulo VARCHAR(255),
    descripcion TEXT,
    visitas INTEGER DEFAULT 0,
    activo BOOLEAN DEFAULT true,
    fecha_expiracion TIMESTAMP,
    tags JSONB,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

---

## Script mail-processor.py

Script Python que escucha nuevos correos y los registra en `mail_registry`.

**Requisitos funcionales:**
1. Conectar a Dovecot via IMAP (localhost:993)
2. Escuchar eventos IDLE para nuevos correos
3. Por cada correo nuevo:
   - Extraer headers y metadatos
   - Generar body_preview (primeras 500 palabras, texto plano)
   - Si hay adjuntos: guardar en FileBrowser, registrar rutas en attachment_paths
   - Insertar registro en mail_registry
   - Insertar evento en log_sistema (tipo: mail_received)
4. Manejar reconexión automática
5. Logging a stdout (para docker logs)

**Dependencias:**
```
imapclient
psycopg2-binary
python-dotenv
```

**Ejecutar como servicio systemd o contenedor Docker.**

---

## Script hst-sync.py

Script Python para sincronizar etiquetas HST desde servidor externo.

**Requisitos funcionales:**
1. Conectar a API de tzrtech.org (endpoint y auth por definir)
2. Obtener lista de etiquetas con h_maestro
3. Comparar con hst_tags_sistema local
4. UPDATE si h_maestro existe y hay cambios
5. INSERT si h_maestro no existe
6. Marcar synced_at en registros actualizados
7. Registrar evento en log_sistema (tipo: sync_hst)

**Ejecutar via cron cada 24h.**

---

## Script backup.sh

Actualizar el script existente para incluir:
1. Dump PostgreSQL completo
2. Volumen vaultwarden_data
3. Configuración de servicios
4. Volumen filebrowser_data
5. Rotación: 7 días
6. Log de cada backup en log_sistema (via psql o curl a API)

---

## Configuración Nginx (services.conf)

Asegurar que incluye todos los servicios:
- db.tzzr.net → localhost:8081 (NocoDB)
- files.tzzr.net → localhost:8082 (FileBrowser)
- s.tzzr.net → localhost:8083 (Shlink)
- alias.tzzr.net → localhost:8084 (Addy.io)
- pass.tzzr.net → localhost:8085 (Vaultwarden, con WebSocket)

Todos con:
- SSL usando certificados de Mail-in-a-Box
- Headers de seguridad estándar
- ACME challenge para renovación SSL

---

## README.md

Incluir:
1. Descripción del proyecto (servidor personal, no sistema completo)
2. Arquitectura (diagrama ASCII)
3. Servicios y URLs
4. Requisitos previos (VPS, dominio, Cloudflare)
5. Instalación rápida
6. Estructura de archivos
7. Comandos útiles
8. Backups y restauración
9. Seguridad (puertos, firewall, SSL)
10. Licencia

**NO incluir credenciales reales en el repositorio.**

---

## Entregables

1. [ ] `docker-compose.yml` — Actualizado con todos los servicios
2. [ ] `init.sql` — Schema completo con las 4 tablas HST + mail_registry + logs
3. [ ] `nginx/services.conf` — Configuración reverse proxy completa
4. [ ] `scripts/backup.sh` — Actualizado con vaultwarden
5. [ ] `scripts/mail-processor.py` — Nuevo: procesar correos
6. [ ] `scripts/hst-sync.py` — Nuevo: sincronizar etiquetas
7. [ ] `dns/tzzr_net.zone` — Archivo de zona DNS
8. [ ] `README.md` — Documentación principal
9. [ ] `docs/INSTALACION.md` — Guía paso a paso
10. [ ] `docs/CLONACION.md` — Guía para replicar a nuevo usuario
11. [ ] `docs/CREDENCIALES.template` — Plantilla sin valores reales
12. [ ] `.gitignore` — Excluir .env, credenciales, backups
13. [ ] `.env.example` — Variables de entorno requeridas

---

## Variables de Entorno (.env.example)

```env
# PostgreSQL
POSTGRES_USER=tzzr
POSTGRES_PASSWORD=
POSTGRES_DB=tzzr

# NocoDB
NC_AUTH_JWT_SECRET=

# Addy.io
ANONADDY_DOMAIN=tzzr.net
ANONADDY_SECRET=
APP_KEY=

# Vaultwarden
VAULTWARDEN_DOMAIN=https://pass.tzzr.net
VAULTWARDEN_ADMIN_TOKEN=

# Shlink
SHLINK_DOMAIN=s.tzzr.net

# Mail processor
IMAP_HOST=localhost
IMAP_USER=
IMAP_PASSWORD=

# HST Sync (por definir)
HST_API_URL=
HST_API_TOKEN=
```

---

## Notas para Code

1. **No crear servicios nuevos** — Solo documentar y estructurar lo existente
2. **No incluir credenciales reales** — Usar placeholders o .env.example
3. **Mantener compatibilidad** — El servidor ya está funcionando
4. **Schema SQL debe ser idempotente** — Usar IF NOT EXISTS
5. **Scripts deben tener logging** — Para debugging via docker logs
6. **Documentación en español** — Usuario hispanohablante

---

## Repositorio Destino

Por confirmar con el usuario. Puede ser:
- Nuevo repositorio
- Repositorio existente a actualizar

---

*Documento generado: Diciembre 2024*