# Certificados SSL

HTTPS para cada dominio del VPS: comodín de la zona de ArduMaker o Let's Encrypt emitido al activar el dominio.

Fuente: https://ardumaker.com/docs/ssl/

- Categoría: Servidores e infraestructura
- Estado: Disponible
- Requisitos: Un dominio que ya llegue al host del VPS (se comprueba con `verificar_dominio_vps`); Ser miembro de la empresa con acceso al VPS; Para un dominio propio: que el puerto 80 del dominio llegue al host durante la validación
- Herramientas MCP (Solo leen): `verificar_dominio_vps`, `ver_operacion`
- Herramientas MCP (Escriben o modifican): `activar_dominio_vps`

## ¿Qué permite hacer?

- Servir cada dominio publicado en HTTPS (TLS 1.2 y 1.3, HTTP/2), con redirección automática de HTTP a HTTPS.
- Usar sin trámite el certificado comodín de la zona de ArduMaker para subdominios de un solo nivel.
- Emitir un certificado de Let's Encrypt para un dominio propio o para un subdominio de dos niveles de la zona, al activar el dominio.
- Publicar un dominio solo en HTTP cuando no se quiere TLS (`use_ssl=false`).

## ¿Cuándo conviene usarlo?

- Al publicar cualquier dominio en un VPS: el certificado se resuelve en el mismo paso de activación.
- Cuando se conecta un dominio propio de la empresa a una app del VPS.
- Cuando un dominio muestra un error de certificado y hay que volver a pedirlo.

## ¿Cómo funciona en ArduMaker?

El TLS **termina en el host compartido**, nunca dentro del VPS. Qué certificado usa un dominio depende de su nombre:

| Dominio | Certificado | Qué hace la activación |
| --- | --- | --- |
| Subdominio de un nivel de la zona de ArduMaker (`app.<zona>`) | Comodín de la zona, que emite y renueva la plataforma | No emite nada: `certificate.skipped: true` |
| Subdominio de dos niveles de la zona (`api.app.<zona>`) | Let's Encrypt, propio de ese nombre | Comprueba el DNS y emite con `create_cert=true` |
| Dominio propio | Let's Encrypt, propio de ese nombre | Comprueba el DNS y emite con `create_cert=true` |

### Emisión con Let's Encrypt

1. `activar_dominio_vps` valida el nombre y comprueba que el DNS llegue al host (registro A al host, CNAME al `dnsip` del VPS, o un proxy delante que se acepta).
2. Con `create_cert=true` (por defecto), el host pide el certificado a Let's Encrypt con `certbot` en modo standalone (validación por HTTP en el puerto 80). Con `email` se registra ese correo; sin él, se registra sin correo.
3. Recién con el certificado emitido se escribe el server block HTTPS del host que lo usa.
4. Si la validación falla, no se publica nada y la respuesta trae solo las líneas de la autoridad sobre ESE dominio (`Domain:`, `Type:`, `Detail:`).

> **INFO:** Las claves privadas quedan en el host: nunca se copian al VPS ni se devuelven en una respuesta. El nginx del VPS escucha en HTTP plano y no necesita certificados.

Volver a activar un dominio con `create_cert=true` es seguro: si el certificado sigue vigente, Let's Encrypt no emite otro; si venció, lo renueva. No hay una herramienta aparte para renovar a mano.

## ¿Qué cambia realmente?

- En el host: el certificado y la clave del dominio, y un server block con `listen 443 ssl http2` que los usa, más un bloque en el 80 que responde 301 a HTTPS.
- En el VPS: nada relacionado con TLS.
- En la cuenta de Let's Encrypt: una emisión por dominio propio (cuenta para sus límites de emisión).

## Copias y bases de datos

Las copias de seguridad semanales del VPS incluyen los certificados de los dominios propios (carpetas `live/`, `archive/` y `renewal/`), para poder restaurarlos. Los certificados de la plataforma **no** viajan en la copia: el manifiesto los lista en `ssl_domains_excluidos` para distinguir «nunca tuvo certificado» de «lo tenía y no viaja». Ver [Copias de seguridad](https://ardumaker.com/docs/backups).

### TLS de las bases de datos con acceso externo

Cuando una base (PostgreSQL, MySQL o Redis) instalada con Apps se abre al exterior, el motor recibe un certificado propio para su hostname, emitido por validación DNS. Se renueva solo cuando faltan menos de 30 días para el vencimiento; si una renovación falla, el certificado anterior sigue cargado.

## Esquema

**Dónde se cifra y dónde no**

```text
Navegador (HTTPS)
  ↓
Cloudflare (solo zona de ArduMaker: certificado del borde)
  ↓
nginx del host :443 (termina TLS con el comodín o con Let's Encrypt)
  ↓
Redirección de puerto (tráfico interno, sin TLS)
  ↓
nginx del VPS :443 (HTTP plano)
```

## Resultado esperado

- `certificate` en la respuesta de `activar_dominio_vps`: `{success, domain, exit_code}` si se emitió, o `{success, skipped, reason, domain}` si se usó el comodín.
- Con `use_ssl=true` el dominio responde por HTTPS y el puerto 80 redirige con un 301.
- Se comprueba con `curl -sI https://<dominio>/` o mirando el certificado en el navegador.

## Errores y resolución

| Error | Causa | Qué hacer |
| --- | --- | --- |
| `desafio_fallido` | Let's Encrypt no pudo validar el dominio por HTTP (DNS que no llega al host, puerto 80 bloqueado por un proxy o firewall externo) | Leer `problems`, corregir el DNS y volver a activar |
| `limite_emision` | Se alcanzó un límite de emisión de Let's Encrypt para ese dominio | Esperar antes de reintentar; repetir enseguida no ayuda |
| `certificado_del_host_ausente` | Se pidió HTTPS sin certificado emitido para ese nombre | Activar con `create_cert=true`, o con `use_ssl=false` |
| `Domain could not be resolved` | El dominio todavía no resuelve | Revisar el DNS y esperar la propagación |

La salida completa de `certbot` no se devuelve (el host es compartido): queda en el log del servidor. Activar de nuevo un dominio es seguro; cuidado con repetir muchas veces una emisión que falla, porque Let's Encrypt limita los intentos.

## Relación con MCP

El certificado se pide con `activar_dominio_vps` (parámetros `use_ssl`, `create_cert` y `email`). Con un dominio propio puede tardar, porque la validación es real; la herramienta devuelve un `operacion_id` que se sigue con `ver_operacion`. Antes conviene llamar a `verificar_dominio_vps`, que es de solo lectura.

Es una operación de escritura: un agente autorizado como solo lectura no puede ejecutarla. No hay herramientas para leer ni exportar certificados o claves. Referencia en [/mcp/docs](https://ardumaker.com/mcp/docs) y ejemplos en [/mcp/dominios](https://ardumaker.com/mcp/dominios).

## Funciones relacionadas

- [Nginx](https://ardumaker.com/docs/nginx/)
- [Dominios y DNS](https://ardumaker.com/docs/dominios-y-dns/)
- [Copias de seguridad](https://ardumaker.com/docs/backups/)
- [Servidores VPS](https://ardumaker.com/docs/vps/)