# TLS certificates

> Choose how Falak secures each domain — automatic Let's Encrypt, DNS-01 wildcards via Cloudflare, custom certificates, an internal CA or plain HTTP.

Source: https://falak.sh/docs/guides/tls-certificates/

Every domain has a **TLS mode**. The default, **Automatic**, needs nothing from you: Caddy on your server obtains and renews a Let's Encrypt certificate as soon as DNS points at it.

## TLS modes

| Mode | Value | How the certificate is obtained | Publicly trusted |
|---|---|---|---|
| Automatic (Let's Encrypt) | `auto` | ACME HTTP-01 / TLS-ALPN-01 on ports 80/443 | Yes |
| DNS-01 (wildcard) | `dns` | ACME DNS-01 through a Cloudflare API token | Yes |
| Custom certificate | `custom` | You upload certificate, private key and optional chain | Depends on your CA |
| Internal CA | `internal` | Caddy's local CA (self-signed) | No |
| Off (HTTP only) | `off` | none | — |

Change the mode per domain in the domains table under **Settings → Networking**.

## Automatic

Requirements:

- DNS for the name points at the server (or load balancer), and records are **not proxied**.
- Ports 80 and 443 are reachable from the internet (the server firewall allows them by default for app, web and lb servers; check your cloud provider's security groups).

The ACME account e-mail is `FALAK_ACME_EMAIL` (set by the installer from `--email`). `FALAK_ACME_CA` overrides the ACME directory (for example Let's Encrypt staging).

## DNS-01 with Cloudflare

Use DNS-01 for wildcard names (`*.example.com`), for servers not reachable on port 80, or behind a proxy.

1. Create a Cloudflare API token with **Zone → DNS → Edit** for the zone (at least 20 characters).
2. In **Settings → Networking**, under **DNS providers**, click **Add**, choose Cloudflare, name it and paste the token. Tokens are shared by the organization (permission `edge.dns.manage`, admins).
3. Set the domain's TLS mode to **DNS-01** and pick the credential.

DNS-01 requires the FrankenPHP or Caddy binary on your servers to include the Cloudflare DNS module. The stock binaries Falak installs may not include it. DNS-01 wildcard certificates are not covered by Falak's end-to-end tests.

## Custom certificates

Upload under **Settings → Networking → Custom certificates**: the certificate (PEM), the private key and an optional chain, up to 64 KiB each. Falak installs it on every server routing the site. Then set the domain's TLS mode to **Custom** and select it. You are responsible for renewals.

## Internal CA

Caddy issues a certificate from its own local CA. Browsers show a warning unless you trust that CA. Use it for private networks only. Health checks do not verify internal-CA certificates.

## Alerts

- `edge.certificate_failed` (critical) when installing a certificate fails.
- `edge.certificate_installed` (info) when it recovers.

## Troubleshooting

| Symptom | Fix |
|---|---|
| Certificate stays **pending** | Run the DNS check. The name must point at the server and not be proxied. Ports 80/443 must be open in your cloud firewall. |
| Let's Encrypt rate limit errors | Too many certificates for the same registered domain (common on shared `sslip.io` names). Use your own domain. |
| Browser warns about the certificate | The domain uses **Internal CA**, or a custom certificate without its chain. |

## Next steps