# Certificados SSL

HTTPS para cada domínio do VPS: curinga da zona da ArduMaker ou Let's Encrypt emitido ao ativar o domínio.

Fonte: https://ardumaker.com/pt/docs/ssl/

- Categoria: Servidores e infraestrutura
- Estado: Disponível
- Requisitos: Um domínio que já chegue ao host do VPS (verifique com `verificar_dominio_vps`); Ser membro da empresa com acesso ao VPS; Para um domínio próprio: que a porta 80 do domínio chegue ao host durante a validação
- Ferramentas MCP (Só leem): `verificar_dominio_vps`, `ver_operacion`
- Ferramentas MCP (Escrevem ou modificam): `activar_dominio_vps`

## O que permite fazer?

- Servir cada domínio publicado em HTTPS (TLS 1.2 e 1.3, HTTP/2), com redirecionamento automático de HTTP para HTTPS.
- Usar sem trâmites o certificado curinga da zona da ArduMaker para subdomínios de um só nível.
- Emitir um certificado Let's Encrypt para um domínio próprio, ou para um subdomínio de dois níveis da zona, ao ativar o domínio.
- Publicar um domínio só em HTTP quando não se quer TLS (`use_ssl=false`).

## Quando convém usar?

- Ao publicar qualquer domínio em um VPS: o certificado é resolvido no mesmo passo de ativação.
- Quando se liga um domínio próprio da empresa a uma app do VPS.
- Quando um domínio mostra um erro de certificado e é preciso pedi-lo de novo.

## Como funciona na ArduMaker?

O TLS **termina no host compartilhado**, nunca dentro do VPS. Que certificado um domínio usa depende do nome:

| Domínio | Certificado | O que a ativação faz |
| --- | --- | --- |
| Subdomínio de um nível da zona da ArduMaker (`app.<zona>`) | Curinga da zona, emitido e renovado pela plataforma | Não emite nada: `certificate.skipped: true` |
| Subdomínio de dois níveis da zona (`api.app.<zona>`) | Let's Encrypt, próprio desse nome | Verifica o DNS e emite com `create_cert=true` |
| Domínio próprio | Let's Encrypt, próprio desse nome | Verifica o DNS e emite com `create_cert=true` |

### Emissão com Let's Encrypt

1. `activar_dominio_vps` valida o nome e verifica que o DNS chega ao host (registro A para o host, CNAME para o `dnsip` do VPS, ou um proxy à frente, que é aceito).
2. Com `create_cert=true` (padrão), o host pede o certificado à Let's Encrypt com `certbot` em modo standalone (validação por HTTP na porta 80). Com `email` registra-se esse correio; sem ele, registra-se sem correio.
3. Só com o certificado emitido se escreve o server block HTTPS do host que o usa.
4. Se a validação falhar, nada é publicado e a resposta traz apenas as linhas da autoridade sobre ESSE domínio (`Domain:`, `Type:`, `Detail:`).

> **INFO:** As chaves privadas ficam no host: nunca são copiadas para o VPS nem devolvidas em uma resposta. O nginx do VPS escuta em HTTP simples e não precisa de certificados.

Voltar a ativar um domínio com `create_cert=true` é seguro: se o certificado continua válido, a Let's Encrypt não emite outro; se expirou, é renovado. Não há uma ferramenta à parte para renovar à mão.

## O que muda realmente?

- No host: o certificado e a chave do domínio, e um server block com `listen 443 ssl http2` que os usa, mais um bloco na 80 que responde 301 para HTTPS.
- No VPS: nada relacionado com TLS.
- Na Let's Encrypt: uma emissão por domínio próprio (conta para os seus limites de emissão).

## Cópias e bases de dados

As cópias de segurança semanais do VPS incluem os certificados dos domínios próprios (pastas `live/`, `archive/` e `renewal/`), para os poder restaurar. Os certificados da plataforma **não** viajam na cópia: o manifesto lista-os em `ssl_domains_excluidos` para distinguir “nunca teve certificado” de “tinha e não viaja”. Ver [Cópias de segurança](https://ardumaker.com/pt/docs/backups).

### TLS das bases de dados com acesso externo

Quando uma base (PostgreSQL, MySQL ou Redis) instalada com Apps é aberta ao exterior, o motor recebe um certificado próprio para o seu hostname, emitido por validação DNS. É renovado automaticamente quando faltam menos de 30 dias para o vencimento; se uma renovação falhar, o certificado anterior continua carregado.

## Esquema

**Onde se cifra e onde não**

```text
Navegador (HTTPS)
  ↓
Cloudflare (só zona da ArduMaker: certificado da borda)
  ↓
nginx do host :443 (termina TLS com o curinga ou com Let's Encrypt)
  ↓
Redirecionamento de porta (tráfego interno, sem TLS)
  ↓
nginx do VPS :443 (HTTP simples)
```

## Resultado esperado

- `certificate` na resposta de `activar_dominio_vps`: `{success, domain, exit_code}` se foi emitido, ou `{success, skipped, reason, domain}` se foi usado o curinga.
- Com `use_ssl=true` o domínio responde por HTTPS e a porta 80 redireciona com um 301.
- Verifica-se com `curl -sI https://<dominio>/` ou olhando o certificado no navegador.

## Erros e resolução

| Erro | Causa | O que fazer |
| --- | --- | --- |
| `desafio_fallido` | A Let's Encrypt não conseguiu validar o domínio por HTTP (DNS que não chega ao host, porta 80 bloqueada por um proxy ou firewall externo) | Ler `problems`, corrigir o DNS e voltar a ativar |
| `limite_emision` | Foi atingido um limite de emissão da Let's Encrypt para esse domínio | Esperar antes de tentar de novo; repetir logo não ajuda |
| `certificado_del_host_ausente` | Pediu-se HTTPS sem certificado emitido para esse nome | Ativar com `create_cert=true`, ou com `use_ssl=false` |
| `Domain could not be resolved` | O domínio ainda não resolve | Rever o DNS e esperar a propagação |

A saída completa do `certbot` não é devolvida (o host é compartilhado): fica no log do servidor. Ativar de novo um domínio é seguro; cuidado ao repetir muitas vezes uma emissão que falha, porque a Let's Encrypt limita as tentativas.

## Relação com MCP

O certificado é pedido com `activar_dominio_vps` (parâmetros `use_ssl`, `create_cert` e `email`). Com um domínio próprio pode demorar, porque a validação é real; a ferramenta devolve um `operacion_id` que se acompanha com `ver_operacion`. Antes convém chamar `verificar_dominio_vps`, que é só de leitura.

É uma operação de escrita: um agente autorizado como só leitura não a pode executar. Não há ferramentas para ler nem exportar certificados ou chaves. Referência em [/mcp/docs](https://ardumaker.com/pt/mcp/docs) e exemplos em [/mcp/dominios](https://ardumaker.com/pt/mcp/dominios).

## Funcionalidades relacionadas

- [Nginx](https://ardumaker.com/pt/docs/nginx/)
- [Domínios e DNS](https://ardumaker.com/pt/docs/dominios-y-dns/)
- [Cópias de segurança](https://ardumaker.com/pt/docs/backups/)
- [Servidores VPS](https://ardumaker.com/pt/docs/vps/)