ligbox/ligbox-ops-platform
3
0
Fork 0
Code Issues 421 Pull requests Projects Releases Packages Wiki Activity Actions
ligbox-ops-platform/specs/034-nextcloud-carbonio-vm112-integration/spec.md
Ligbox Spec Hub f6cf9f8e1c Add Spec 034 Nextcloud integration with VM112 Carbonio mail. 
Defines hybrid hot/warm storage to expand tenant mail capacity via Nextcloud Hub on proposed VM116.
2026-06-20 22:07:00 +00:00

11 KiB
Raw Blame History

Spec 034 — Nextcloud + E-mail VM112 (ampliar capacidade Carbonio)

Criado: 2026-06-20
Solicitado por: Roger
Status: 📋 Draft — aguarda validação arquitectura
Prioridade: P1 (capacidade mail tenants + produto Ligbox Mail)
Sistema: VM112 (Carbonio) + VM116 (Nextcloud — proposto) + CT114 (Traefik) + Desk VM122
Relacionado: Spec 017 (purge domínio) · 022 (Carbonio release) · 013/019 (migração mail) · 027 (RBAC) · 033 (Infra stack health)

Resumo

Integrar Nextcloud Hub ao ecossistema Ligbox Mail (VM112) para ampliar a capacidade efectiva de e-mail e ficheiros dos tenants Carbonio, sem substituir o motor de mail.

Problema: a VM112 tem disco limitado (~96 GB) e o Carbonio CE guarda mail + blobs localmente. Quotas altas por domínio esgotam o volume rapidamente.

Solução proposta: modelo híbrido em camadas:

Camada Produto Função Quota típica
Hot Carbonio VM112 SMTP/IMAP, webmail, calendário, contactos 5–10 GB / caixa
Warm Nextcloud Files VM116 Anexos grandes, documentos, partilha 50–500 GB / utilizador
Cold (fase 2) Carbonio → S3 secundário Arquivo IMAP antigo, blobs offload Configurável

O Carbonio permanece autoridade para @dominio (MX, DKIM, LMTP). Nextcloud complementa capacidade de armazenamento e UX unificada (Mail app + Files).

Problema

Limitações actuais (VM112)

Item Estado
Disco VM112 /dev/sda1 ~96 GB (~20 GB usados hoje — cresce com tenants)
Storage Carbonio Volumes locais (Primary + Index)
Quota domínio/conta zmprov / Domain Admin — sem offload automático
Integração nativa Nextcloud Inexistente no Carbonio CE (Zextras: sem roadmap oficial)
ManageSieve (4190) Não disponível — filtros Nextcloud Mail não funcionam nativamente

Impacto operacional

  1. Onboarding cria contas com quota default alta → risco de encher disco.
  2. Anexos grandes (PST import, ficheiros 25 MB+) pressionam o mesmo volume do mailstore.
  3. Clientes pedem «mais espaço de e-mail» — hoje só há aumento de quota Carbonio (mesmo disco).
  4. Purge domínio (Spec 017) remove Carbonio mas não limpa workspace Nextcloud (futuro).

Decisões de arquitectura (propostas — Roger valida)

# Tema Decisão proposta
1 Motor de mail Carbonio VM112 — inalterado como MTA/MUA principal
2 Armazenamento expandido Nextcloud Hub em VM dedicada com disco ampliado
3 VM alvo Nextcloud VM116 10.10.10.116 (nova) — 4 vCPU, 8 GB RAM, 500 GB+ disco
4 Identidade Conta Nextcloud = mesmo e-mail @dominio (provisionamento paralelo ao Carbonio)
5 Autenticação Fase 1: senha sincronizada no wizard · Fase 2: OIDC/SAML ou LDAP Carbonio
6 URL tenant files.{dominio} (SNI CT114) · hub Ligbox: cloud.ligbox.com.br
7 Mail Nextcloud App Mail → IMAP/SMTP Carbonio (mail.{dominio}) — opcional na UI
8 Offload Carbonio Fase 2: volume S3 secundário (MinIO na VM116) via Carbonio Storage
9 Orquestração Wizard VM112 API + Desk VM122 (monitorização, purge, RBAC)
10 Produto comercial Pacote Ligbox Mail Plus = Carbonio base + Nextcloud Files quota

Arquitectura

flowchart TB
  subgraph Internet
    Users[Utilizadores / Browser]
    CF[Cloudflare DNS]
  end

  subgraph CT114["CT114 Traefik + SNI"]
    TR[Traefik :443]
  end

  subgraph VM112["VM112 — Carbonio + Wizard"]
    WZ[Wizard API :8090]
    CB[Carbonio CE<br/>SMTP :25 · IMAP :993 · LMTP :7025]
    DA[Domain Admin]
  end

  subgraph VM116["VM116 — Nextcloud Hub (proposto)"]
    NC[Nextcloud :443]
    NCMAIL[App Mail → IMAP Carbonio]
    NCFiles[App Files — quota ampliada]
    S3[MinIO S3 :9000<br/>fase 2]
  end

  subgraph VM122["VM122 — Desk"]
    DS[Ops Desk API]
  end

  Users --> CF
  CF --> TR
  TR -->|mail.{dom}| CB
  TR -->|onboard.ligbox| WZ
  TR -->|files.{dom}| NC
  NCMAIL -->|IMAP/SMTP| CB
  CB -.->|volume secundário fase 2| S3
  WZ -->|provision user| NC
  WZ -->|webhooks| DS
  DS -->|stack health / purge| NC
  DS -->|proxy status| WZ

Modelo de capacidade (quotas)

Política Ligbox Mail (default proposto)

Plano Quota Carbonio (hot) Quota Nextcloud Files Notas
Starter 5 GB 25 GB Wizard default
Business 10 GB 100 GB FOSSBilling add-on
Enterprise 20 GB 500 GB Negociado

Regra: quota Carbonio sempre ≤ hot tier; crescimento comercial → Nextcloud Files, não aumento cego no mailstore local.

Fluxos de offload (UX)

  1. Anexo grande no webmail Carbonio — aviso «Guarde em Files» + link files.{dominio}.
  2. Nextcloud Mail — utilizador lê mail via IMAP; anexos > N MB → «Guardar no Files» (manual fase 1).
  3. Fase 2 — Archive — job carbonio powerstore move mensagens > 90 dias para volume S3; stub no IMAP.

Integração VM112 (Wizard + Domain Admin)

Provisionamento no onboarding

Após POST /api/onboarding/account/create (Carbonio OK):

Passo Acção
NC-1 Criar utilizador Nextcloud via OCS Provisioning API
NC-2 Definir quota Files conforme plano
NC-3 Pré-configurar conta Mail app (IMAP host, SSL, e-mail) — opcional
NC-4 Registar nextcloud_user_id + files_url no estado do domínio
NC-5 Webhook Desk onboarding.nextcloud.provisioned

Feature flag wizard: NEXTCLOUD_INTEGRATION=0|1 (default 0 até piloto).

Domain Admin (/admin)

Funcionalidade Descrição
Ver quota Carbonio + Files Painel unificado
Link «Abrir Files» Redirect files.{dominio}
Reset senha Sincroniza Carbonio + Nextcloud (fase 1)

Integração Desk VM122

Módulo Desk (Spec 015)

Campo Valor
id nextcloud-storage
label Nextcloud Storage
default_enabled false (piloto)
nav_views (vazio — tile em Serviços / Infra)

API Desk (novos endpoints)

Método Path Descrição
GET /api/v1/nextcloud/domains/{domain}/status Quota, users, health
GET /api/v1/nextcloud/domains/{domain}/users Lista utilizadores tenant
POST /api/v1/nextcloud/domains/{domain}/users Provision manual (ops)
DELETE /api/v1/nextcloud/domains/{domain}/users/{email} Remover user
GET /api/v1/nextcloud/health Probe VM116

Ver contrato: contracts/nextcloud-provisioning-api.md.

Stack health (Spec 033)

Adicionar probe VM116 em stack_health.py:

Serviço URL VM
Nextcloud Hub https://cloud.ligbox.com.br/status.php 116
Nextcloud OCS https://10.10.10.116/ocs/v2.php/cloud/capabilities 116

Purge domínio (extensão Spec 017)

Ordem após purge Carbonio:

  1. Listar users Nextcloud com e-mail @dominio
  2. Apagar utilizadores via OCS API
  3. Apagar grupo tenant (se existir)
  4. Registar passo na timeline purge

Infraestrutura VM116

Detalhe: infrastructure.md

Item Valor proposto
VMID 116
IP LAN 10.10.10.116/24
SSH WAN 95.216.14.146:2516 (reservar no pfSense)
Hostname cloud.ligbox.com.br
SO Ubuntu 24.04 LTS
Stack Nextcloud 30+ (snap ou Docker), PostgreSQL, Redis
TLS Let's Encrypt via Traefik CT114
Backup Proxmox snapshot + Nextcloud occ backup diário

RBAC (Spec 027)

Acção Perfis
Ver status Nextcloud (Desk) super_admin, ops_lead, technician
Provision manual user super_admin, ops_lead
Alterar quotas tenant super_admin, ops_lead
Purge users Nextcloud super_admin, ops_lead (com purge domínio)
Cliente Domain Admin Gerente domínio — só o seu tenant

Binding software (matriz RBAC):

software_group: vm112-nextcloud
host: VM116
roles:
  nextcloud_admin: [super_admin, ops_lead]
  nextcloud_read: [technician, noc]

Fases de implementação

Fase 0 — Piloto infra (sem wizard)

  • Provisionar VM116 + Nextcloud + TLS
  • Conta manual admin@ligbox.com.br + teste Mail app → Carbonio VM112
  • Documentar quotas e limites IMAP

Fase 1 — Provisionamento wizard + Desk read-only

  • API Nextcloud provisioning no wizard (flag OFF default)
  • Endpoints Desk status/health
  • Traefik files.{dom} template (CT114)
  • Stack health card Infra

Fase 2 — Purge + quotas comerciais

  • Purge Nextcloud no fluxo Spec 017
  • FOSSBilling add-on «Mail Plus»
  • Domain Admin painel unificado quota

Fase 3 — Offload S3 Carbonio

  • MinIO VM116
  • Volume secundário Carbonio → S3
  • Política retenção / archive IMAP

Fora de escopo (v1)

  • Substituir webmail Carbonio por Nextcloud Mail como única UI
  • ManageSieve / filtros Nextcloud nativos (requer bridge custom — backlog)
  • Integração nativa Carbonio Files ↔ Nextcloud (inexistente no CE)
  • Nextcloud Talk / Office (avaliar Spec separada)
  • Multi-tenant Nextcloud federado (um hub Ligbox basta no piloto)

Riscos e mitigações

Risco Mitigação
Duplicar senhas (Carbonio + NC) Fase 2 OIDC; rotação via Domain Admin
IMAP Nextcloud Mail sobrecarrega VM112 Rate limit; quota hot baixa; monitor CPU
Purge incompleto (dados órfãos NC) Passo obrigatório Spec 017 + audit
Disco VM112 enche antes do piloto Alertas quota 80% + política quota default 5 GB
S3 MinIO single point Replicação fase 3; backup S3

Critérios de aceitação (Fase 1)

  1. VM116 Nextcloud acessível em https://cloud.ligbox.com.br com TLS válido.
  2. Utilizador admin@ligbox.com.br lê/envia mail via Nextcloud Mail → Carbonio VM112.
  3. Wizard com flag ON cria user Nextcloud após conta Carbonio.
  4. Desk exibe quota Carbonio + Nextcloud no tile domínio (read-only).
  5. Documentação quickstart validada por ops_lead.

Documentos relacionados

Documento Conteúdo
infrastructure.md VM116, rede, Traefik, disco
quickstart.md Piloto manual ops
tasks.md Checklist implementação
contracts/nextcloud-provisioning-api.md OCS + Desk API
docs/EMAIL_LIGBOX_VM112.md Arquitectura mail actual
docs/vms/VM112.md Ficha VM112

Referências externas