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

```mermaid
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](./034-console-process-ui.md) · Shell: [035-UX](../035-ligbox-mail-bundles-foss-openpanel/ligbox-console-shell.md)

| 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](./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](./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):

```yaml
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](./infrastructure.md) | VM116, rede, Traefik, disco |
| [quickstart.md](./quickstart.md) | Piloto manual ops |
| [tasks.md](./tasks.md) | Checklist implementação |
| [034-console-process-ui.md](./034-console-process-ui.md) | **Visão processo Console** (UI Spec 030 + componentes 034) |
| [contracts/nextcloud-provisioning-api.md](./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](../035-ligbox-mail-bundles-foss-openpanel/spec.md) | Preços, FOSS, login gerente domínio |

---

## Referências externas

- [Carbonio CE Storage](https://docs.zextras.com/carbonio-ce/html/adminpanel/storage.html)
- [Carbonio S3 volumes](https://docs.zextras.com/carbonio/html/admincli/storages.html)
- [Nextcloud OCS Provisioning API](https://docs.nextcloud.com/server/latest/admin_manual/configuration_user/user_provisioning_api.html)
- [Zextras Forum — Nextcloud integration](https://community.zextras.com/forum/carbonio-general-thread/nextcloud-for-carbonio-ce/) — sem integração nativa CE