feat: add email documentation

jorgeteixe · jorgeteixe · commit 12dad9c56231 · 2025-08-27T12:58:16.000+02:00
diff --git a/docs/running/infrastructure.md b/docs/running/infrastructure.md
@@ -0,0 +1,25 @@
+# Infraestrutura
+
+Esta sección cobre a infraestrutura técnica que soporta as operacións de GPUL.
+
+## Servidor principal
+
+Toda a infraestrutura está aloxada nun servidor dedicado chamado **gpulux** en Hetzner, co proxy Caddy xestionando o acceso aos diferentes servizos.
+
+## Servizos
+
+### Autenticación e identidade
+- **[Keycloak](./infrastructure/keycloak)** - Sistema de Single Sign-On (SSO)
+
+### Comunicación
+- **[Correo electrónico](./infrastructure/email)** - Sistema de correo con Mailcow e AWS SES para correos transaccionais
+- **[Nextcloud](./infrastructure/nextcloud)** - Ficheiros e reunións
+
+### Xestión
+- **[Vaultwarden](./infrastructure/vaultwarden)** - Xestor de contrasinais da asociación
+- **[FacturaScripts](./infrastructure/facturascripts)** - Sistema de facturación para Verifactu 2026
+
+### Operacións
+- **[ActivePieces](./infrastructure/activepieces)** - Automatización de procesos
+- **[NocoDB](./infrastructure/nocodb)** - Base de datos e operacións
+- **[Listmonk](./infrastructure/listmonk)** - Xestión de listas de correo
diff --git a/docs/running/infrastructure/activepieces/admin.md b/docs/running/infrastructure/activepieces/admin.md
@@ -0,0 +1,11 @@
+# Administración
+
+Esta guía cobre as tarefas de administración de ActivePieces.
+
+## Configuración do sistema
+
+TODO: Engadir información sobre configuración
+
+## Monitorización
+
+TODO: Engadir información sobre monitorización de procesos
diff --git a/docs/running/infrastructure/activepieces/index.md b/docs/running/infrastructure/activepieces/index.md
@@ -0,0 +1,12 @@
+# ActivePieces
+
+Plataforma de automatización de procesos para optimizar as operacións de GPUL.
+
+## Visión xeral
+
+ActivePieces permite crear fluxos de traballo automatizados para reducir tarefas manuais e mellorar a eficiencia operacional.
+
+## Documentación
+
+- **[Guía de usuario](./user-guide)** - Como crear e xestionar automatizacións
+- **[Administración](./admin)** - Configuración e mantemento do sistema
diff --git a/docs/running/infrastructure/activepieces/user-guide.md b/docs/running/infrastructure/activepieces/user-guide.md
@@ -0,0 +1,11 @@
+# Guía de usuario
+
+Esta guía explica como crear e xestionar automatizacións con ActivePieces.
+
+## Crear fluxos de traballo
+
+TODO: Engadir información sobre creación de automatizacións
+
+## Xestión de procesos
+
+TODO: Engadir información sobre monitorización e xestión
diff --git a/docs/running/infrastructure/email/admin.md b/docs/running/infrastructure/email/admin.md
@@ -0,0 +1,11 @@
+# Administración
+
+Esta páxina cobre as tarefas de administración do sistema de correo electrónico de GPUL.
+
+## Xestión de usuarios
+
+TODO: Engadir información sobre xestión de usuarios
+
+## Mantemento
+
+TODO: Engadir información sobre mantemento
diff --git a/docs/running/infrastructure/email/assets/aliases.png b/docs/running/infrastructure/email/assets/aliases.png
diff --git a/docs/running/infrastructure/email/assets/app-passwords.png b/docs/running/infrastructure/email/assets/app-passwords.png
diff --git a/docs/running/infrastructure/email/assets/client-config.png b/docs/running/infrastructure/email/assets/client-config.png
diff --git a/docs/running/infrastructure/email/assets/forward.png b/docs/running/infrastructure/email/assets/forward.png
diff --git a/docs/running/infrastructure/email/assets/sender-identities.png b/docs/running/infrastructure/email/assets/sender-identities.png
diff --git a/docs/running/infrastructure/email/index.md b/docs/running/infrastructure/email/index.md
@@ -0,0 +1,13 @@
+# Correo electrónico
+
+Esta sección explica como está configurado e xestionado o sistema de correo electrónico para GPUL.
+
+## Visión xeral
+
+O sistema de correo electrónico de GPUL proporciona servizos de correo institucional para todos os membros da organización. Temos desplegado Mailcow no servidor gpulux como servidor de correo principal. Para correos transaccionais, temos configurado AWS SES con acceso de produción para o dominio gpul.org.
+
+## Documentación
+
+- **[Guía de usuario](./setup)** - Como configurar e utilizar o correo como usuario
+- **[Caixas de correo compartidas](./shared-mailboxes)** - Como funcionan os alias organizacionais
+- **[Administración](./admin)** - Xestión e mantemento do sistema
diff --git a/docs/running/infrastructure/email/setup.md b/docs/running/infrastructure/email/setup.md
@@ -0,0 +1,49 @@
+# Guía de usuario
+
+Guía para configurar e utilizar o correo electrónico de GPUL.
+
+## Prerrequisitos
+
+Para utilizar o correo electrónico de GPUL necesitas:
+
+- Ter unha conta de usuario en Keycloak (<a href="https://identity.gpul.org" target="_blank">identity.gpul.org</a>) co atributo personalizado "GPUL Email" configurado co enderezo correcto
+- Ten en conta que o correo principal de Keycloak debe ser o teu correo persoal e non o @gpul.org, xa que doutra forma non poderías verificar o correo nin cambiar a contrasinal se perdes o acceso
+- Se non tes unha conta, consulta a [documentación de Keycloak](../keycloak/user-guide) para ver como obter unha
+
+## Uso do webmail
+
+Para acceder ao teu correo a través do navegador:
+
+1. Vai a <a href="https://mail.gpul.org" target="_blank">mail.gpul.org</a>
+2. Na páxina de inicio de sesión de Mailcow, selecciona a opción **SSO** (Single Sign-On)
+3. Inicia sesión coa túa [identidade de Keycloak](../keycloak/user-guide)
+4. Terás acceso á caixa de correo configurada como "GPUL Email" no teu atributo de usuario de Keycloak
+5. Se hai un erro ao iniciar sesión, probablemente o campo "GPUL Email" estea baleiro
+
+## Xestión de redirección
+
+Como a nosa configuración anterior só incluía redirección de correo, así está configurado por defecto. Os usuarios poden querer manter a redirección pero perderán a capacidade de enviar correos desde outros servidores de correo (xa que agora os campos SPF só permiten enviar desde servidores de correo autorizados).
+
+Para isto deberán usar un cliente de correo correctamente configurado ou o webmail. Para cambiar a redirección:
+
+1. Na interface do webmail, fai clic na icona de engranaxe (⚙️) xunto ao nome do perfil na caixa de correo
+2. Selecciona "Mail" na barra lateral esquerda
+3. Vai á pestana "Forwards"
+
+![Forwards in Webmail Interface](./assets/forward.png)
+
+## Configuración de clientes
+
+Para a maioría dos clientes de correo, por exemplo Thunderbird, a configuración será recollida automaticamente polo cliente ao especificar o enderezo de correo correcto. Ten en conta que **POP3 está deshabilitado**, polo que só podes usar IMAP.
+
+![Automatic Config Discovery in Thunderbird](./assets/client-config.png)
+
+Para iniciar sesión, necesitarán crear unha contrasinal de aplicación para o cliente e é o que usarán desde o cliente. Para acceder á configuración de Mailcow, fai clic na chave inglesa (🔧) na parte superior dereita do webmail.
+
+![App Passwords Mailcow Interface](./assets/app-passwords.png)
+
+Para clientes de Apple, hai unha ligazón na interface de Mailcow que xera automaticamente unha contrasinal de aplicación e descarga o perfil que podes usar nos teus clientes iOS.
+
+## Caixas de correo compartidas
+
+Para información sobre como funcionan os alias organizacionais como presidencia@gpul.org ou info@gpul.org, consulta a [documentación de caixas de correo compartidas](./shared-mailboxes).
diff --git a/docs/running/infrastructure/email/shared-mailboxes.md b/docs/running/infrastructure/email/shared-mailboxes.md
@@ -0,0 +1,43 @@
+# Contas compartidas
+
+Esta sección explica como funcionan as caixas de correo compartidas ou "personas" como presidencia@gpul.org, info@gpul.org, etc.
+
+## Funcionamento dos alias compartidos
+
+Os alias compartidos están pensados principalmente para **recibir** correo electrónico. 
+
+### Exemplo: presidencia@gpul.org
+
+Actualmente, o alias presidencia@gpul.org está configurado como:
+- Un alias que reenvía a `presidencia-archive@gpul.org` (para arquivo)
+- Un alias que reenvía ao enderezo persoal do presidente actual: `nome.apelido@gpul.org`
+
+Desta forma, mantemos unha copia de todos os correos recibidos neste enderezo.
+
+#### Nomes neutros de xénero
+
+En lugar de usar presidente@ ou presidenta@, intentamos manter nomes neutros de xénero como presidencia@. Para evitar erros, tamén se configuran redireccións desde presidente@ e presidenta@ cara presidencia@.
+
+![Email Alias Configuration](./assets/aliases.png)
+
+## Protocolo para correos enviados
+
+A posibilidade de enviar correo desde os alias que estamos configurados para recibir está configurada, aparecendo automaticamente no webmail. Pode requirir algúns axustes específicos dependendo do teu cliente de correo. **Non obstante, esta é unha posibilidade desaconsellada**.
+
+![Sending Identities](./assets/sender-identities.png)
+
+Para correos **enviados**, esperase que respondas co teu enderezo de correo persoal mentres mantés en **CC** o alias correspondente (presidencia@ ou calquera outro alias), de forma que:
+
+- Outros usuarios estean ao tanto da conversación
+- As mensaxes tamén queden arquivadas
+- Se manteña a trazabilidade das comunicacións
+
+## Outros alias compartidos
+
+Este mesmo funcionamento aplícase a outros alias como:
+- info@gpul.org
+- secretaria@gpul.org
+- tesouraria@gpul.org
+- E outros alias organizacionais
+
+Cada un ten o seu correspondente enderezo de arquivo e reenvía ao responsable actual do rol.
diff --git a/docs/running/infrastructure/facturascripts/admin.md b/docs/running/infrastructure/facturascripts/admin.md
@@ -0,0 +1,11 @@
+# Administración
+
+Esta guía cobre as tarefas de administración de FacturaScripts.
+
+## Configuración inicial
+
+TODO: Engadir información sobre configuración inicial
+
+## Mantemento do sistema
+
+TODO: Engadir información sobre mantemento e actualizacións
diff --git a/docs/running/infrastructure/facturascripts/index.md b/docs/running/infrastructure/facturascripts/index.md
@@ -0,0 +1,13 @@
+# FacturaScripts
+
+Sistema de facturación preparado para a lexislación Verifactu que entrará en vigor en 2026.
+
+## Visión xeral
+
+FacturaScripts está dispoñible en <a href="https://facturas.gpul.org" target="_blank">facturas.gpul.org</a> e está configurado para cumprir cos requisitos da futura lexislación Verifactu.
+
+## Documentación
+
+- **[Guía de usuario](./user-guide)** - Como crear e xestionar facturas
+- **[Configuración Verifactu](./verifactu)** - Preparación para a lexislación 2026
+- **[Administración](./admin)** - Configuración e mantemento
diff --git a/docs/running/infrastructure/facturascripts/user-guide.md b/docs/running/infrastructure/facturascripts/user-guide.md
@@ -0,0 +1,11 @@
+# Guía de usuario
+
+Esta guía explica como utilizar FacturaScripts para crear e xestionar facturas.
+
+## Crear facturas
+
+TODO: Engadir información sobre creación de facturas
+
+## Xestión de clientes
+
+TODO: Engadir información sobre xestión de clientes
diff --git a/docs/running/infrastructure/facturascripts/verifactu.md b/docs/running/infrastructure/facturascripts/verifactu.md
@@ -0,0 +1,11 @@
+# Configuración Verifactu
+
+Esta guía explica a preparación para cumprir coa lexislación Verifactu que entrará en vigor en 2026.
+
+## Que é Verifactu
+
+TODO: Engadir información sobre a lexislación
+
+## Configuración necesaria
+
+TODO: Engadir pasos de configuración para cumprir cos requisitos
diff --git a/docs/running/infrastructure/keycloak/admin.md b/docs/running/infrastructure/keycloak/admin.md
@@ -0,0 +1,11 @@
+# Administración
+
+Esta guía cobre as tarefas de administración do sistema Keycloak.
+
+## Xestión de usuarios
+
+TODO: Engadir información sobre xestión de usuarios
+
+## Configuración de servizos
+
+TODO: Engadir información sobre configuración de SSO para servizos
diff --git a/docs/running/infrastructure/keycloak/index.md b/docs/running/infrastructure/keycloak/index.md
@@ -0,0 +1,12 @@
+# Keycloak
+
+Sistema de Single Sign-On (SSO) que permite aos usuarios autenticarse nunha soa vez para acceder a todos os servizos compatibles de GPUL.
+
+## Visión xeral
+
+Keycloak está dispoñible en <a href="https://identity.gpul.org" target="_blank">identity.gpul.org</a> e proporciona autenticación centralizada para todos os servizos que o soporten.
+
+## Documentación
+
+- **[Guía de usuario](./user-guide)** - Como utilizar o sistema de autenticación
+- **[Administración](./admin)** - Xestión e configuración do sistema
diff --git a/docs/running/infrastructure/keycloak/user-guide.md b/docs/running/infrastructure/keycloak/user-guide.md
@@ -0,0 +1,21 @@
+# Guía de usuario
+
+Esta guía explica como utilizar o sistema de autenticación Keycloak como usuario.
+
+## Configuración inicial
+
+Antes de comezar con Keycloak, ten en conta os seguintes puntos:
+
+- **Enderezo de correo**: Recomendamos iniciar sesión usando o teu enderezo de correo externo e non o de @gpul.org
+- **Autenticación**: Existe a posibilidade de configurar o inicio de sesión con GitHub e estamos traballando para soportar passkeys nun futuro próximo
+- **Acceso a servizos**: Keycloak dá acceso á maioría dos servizos de GPUL, como Nextcloud ou correo electrónico. Algúns servizos non permiten SSO, pero a maioría si
+- **Rexistro**: O rexistro pode estar deshabilitado. Se é o caso, para solicitar a creación da conta contacta con calquera membro de GPUL para que a configure
+- **Permisos**: O acceso aos diferentes servizos realízase despois da configuración de grupos. Por defecto non hai acceso a nada, polo que se non tes acceso, solicita que se cambie
+
+## Acceso ao sistema
+
+TODO: Engadir información sobre como acceder
+
+## Xestión do perfil
+
+TODO: Engadir información sobre xestión do perfil de usuario
diff --git a/docs/running/infrastructure/listmonk/admin.md b/docs/running/infrastructure/listmonk/admin.md
@@ -0,0 +1,11 @@
+# Administración
+
+Esta guía cobre as tarefas de administración de Listmonk.
+
+## Configuración do sistema
+
+TODO: Engadir información sobre configuración
+
+## Xestión de plantillas
+
+TODO: Engadir información sobre plantillas de correo
diff --git a/docs/running/infrastructure/listmonk/index.md b/docs/running/infrastructure/listmonk/index.md
@@ -0,0 +1,12 @@
+# Listmonk
+
+Sistema de xestión de listas de correo para comunicacións masivas.
+
+## Visión xeral
+
+Listmonk permite xestionar listas de subscritores e enviar boletíns e comunicacións masivas de forma eficiente.
+
+## Documentación
+
+- **[Guía de usuario](./user-guide)** - Como xestionar listas e enviar campañas
+- **[Administración](./admin)** - Configuración e mantemento do sistema
diff --git a/docs/running/infrastructure/listmonk/user-guide.md b/docs/running/infrastructure/listmonk/user-guide.md
@@ -0,0 +1,11 @@
+# Guía de usuario
+
+Esta guía explica como xestionar listas de correo e enviar campañas con Listmonk.
+
+## Xestión de listas
+
+TODO: Engadir información sobre xestión de subscritores
+
+## Envío de campañas
+
+TODO: Engadir información sobre creación e envío de boletíns
diff --git a/docs/running/infrastructure/nextcloud/admin.md b/docs/running/infrastructure/nextcloud/admin.md
@@ -0,0 +1,11 @@
+# Administración
+
+Esta guía cobre as tarefas de administración de Nextcloud.
+
+## Xestión de usuarios
+
+TODO: Engadir información sobre xestión de usuarios
+
+## Configuración do sistema
+
+TODO: Engadir información sobre configuración e mantemento
diff --git a/docs/running/infrastructure/nextcloud/index.md b/docs/running/infrastructure/nextcloud/index.md
@@ -0,0 +1,12 @@
+# Nextcloud
+
+Plataforma de colaboración que proporciona almacenamento de ficheiros e servizos de reunións mediante Nextcloud Talk.
+
+## Visión xeral
+
+Nextcloud está dispoñible en <a href="https://cloud.gpul.org" target="_blank">cloud.gpul.org</a> e permite aos membros de GPUL compartir ficheiros e realizar videoconferencias.
+
+## Documentación
+
+- **[Guía de usuario](./user-guide)** - Como utilizar ficheiros e reunións
+- **[Administración](./admin)** - Xestión e configuración do sistema
diff --git a/docs/running/infrastructure/nextcloud/user-guide.md b/docs/running/infrastructure/nextcloud/user-guide.md
@@ -0,0 +1,11 @@
+# Guía de usuario
+
+Esta guía explica como utilizar Nextcloud para ficheiros e reunións.
+
+## Xestión de ficheiros
+
+TODO: Engadir información sobre como usar o almacenamento de ficheiros
+
+## Nextcloud Talk
+
+TODO: Engadir información sobre como utilizar as reunións
diff --git a/docs/running/infrastructure/nocodb/admin.md b/docs/running/infrastructure/nocodb/admin.md
@@ -0,0 +1,11 @@
+# Administración
+
+Esta guía cobre as tarefas de administración de NocoDB.
+
+## Configuración de bases de datos
+
+TODO: Engadir información sobre configuración
+
+## Xestión de usuarios
+
+TODO: Engadir información sobre permisos e usuarios
diff --git a/docs/running/infrastructure/nocodb/index.md b/docs/running/infrastructure/nocodb/index.md
@@ -0,0 +1,12 @@
+# NocoDB
+
+Sistema de base de datos para xestionar operacións e datos de GPUL.
+
+## Visión xeral
+
+NocoDB proporciona unha interface visual para xestionar dados operacionais da asociación.
+
+## Documentación
+
+- **[Guía de usuario](./user-guide)** - Como traballar con bases de datos e formularios
+- **[Administración](./admin)** - Configuración e mantemento
diff --git a/docs/running/infrastructure/nocodb/user-guide.md b/docs/running/infrastructure/nocodb/user-guide.md
diff --git a/docs/running/infrastructure/vaultwarden/admin.md b/docs/running/infrastructure/vaultwarden/admin.md
diff --git a/docs/running/infrastructure/vaultwarden/index.md b/docs/running/infrastructure/vaultwarden/index.md
diff --git a/docs/running/infrastructure/vaultwarden/user-guide.md b/docs/running/infrastructure/vaultwarden/user-guide.md
diff --git a/sidebars.ts b/sidebars.ts
