ligbox-ops-platform/specs/034-nextcloud-carbonio-vm112-integration/spec.md

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) + VM124 (Nextcloud) + 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 VM124	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	VM124 10.10.10.124 — 2 vCPU, 4 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 VM124) via Carbonio Storage
9	Orquestração	Wizard VM112 API + Desk VM122 (monitorização, purge, RBAC)
10	Produto comercial	Pacote Ligbox Mail Plus = Carbonio + Nextcloud — Spec 035 (bundles FOSS/OpenPanel, preços, gerente domínio)

---

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 VM124["VM124 — Nextcloud Hub"]
    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) — só se nextcloud_mail_enabled=1 no domínio
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)

UI detalhada: 034-console-process-ui.md · Shell: 035-UX

Funcionalidade	Descrição
Ver quota Carbonio + Files	Painel unificado
Toggle Mail Nextcloud	Activar/desactivar Mail app por domínio (default OFF — Spec 035 §2.2.1)
Link «Abrir Files»	Redirect files.{dominio}
Link «Abrir webmail»	Redirect mail.{dominio} (sempre)
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 VM124

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

Stack health (Spec 033)

Adicionar probe VM124 em stack_health.py:

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

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 VM124

Detalhe: infrastructure.md

Item	Valor
VMID	124
IP LAN	10.10.10.124/24
SSH WAN	95.216.14.146:2524 (reservar no pfSense)
vCPU / RAM / disco	2 / 4 GB / 500 GB
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: VM124
roles:
  nextcloud_admin: [super_admin, ops_lead]
  nextcloud_read: [technician, noc]

---

Fases de implementação

Fase 0 — Piloto infra (sem wizard)

• Provisionar VM124 + 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» → ver Spec 035 (bundles completos)
• Domain Admin painel unificado quota

Fase 3 — Offload S3 Carbonio

• MinIO VM124
• 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. VM124 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
034-console-process-ui.md	Visão processo Console (UI Spec 030 + componentes 034)
contracts/nextcloud-provisioning-api.md	OCS + Desk API
docs/EMAIL_LIGBOX_VM112.md	Arquitectura mail actual
docs/vms/VM112.md	Ficha VM112
Spec 035 — Bundles FOSS/OpenPanel	Preços, FOSS, login gerente domínio

---

Referências externas

• Carbonio CE Storage
• Carbonio S3 volumes
• Nextcloud OCS Provisioning API
• Zextras Forum — Nextcloud integration — sem integração nativa CE