DocsInfrastructure
Cloudflare DNS
Create DNS records for application domains automatically and get wildcard certificates through DNS-01, using a Cloudflare API token.
- Connect
- Integrations → DNS providers (owner/admin)
- Per domain
- Application → Domain tab: DNS record, certificate mode
- Wildcards
- Infrastructure → Reverse proxy → DNS-01 certificates (owner)
What it does
Normally you create the DNS record of a domain yourself and aoox only checks it. With a Cloudflare connection you get two optional extras:
- DNS records: when you add a domain to an application, aoox creates the A record (or AAAA, if the server's address is IPv6) in your Cloudflare zone, pointing at the same IP the DNS check expects.
- DNS-01 certificates: the proxy proves domain ownership through the Cloudflare API instead of port 80, which makes wildcard certificates possible (for example one certificate for every pull request preview).
Both are opt-in. With no connection, nothing changes: you manage DNS and certificates as before. Only Cloudflare is supported for now.
Create an API token
In Cloudflare: My Profile, API Tokens, Create Token
Choose a custom token with two permissions, limited to the zones you use:
Zone:Zone:ReadZone:DNS:Edit
Copy the token
Cloudflare shows it once. A token owned by an account (not a user) also needs the account ID, see below.
Add the connection
Integrations → DNS providers
Owners and admins see it. Click add; the dialog is called New Cloudflare connection.
Fill in the name and the token
Name it (it must be unique), paste the API token, and fill in Account ID (optional) only for an account-owned token. The token is stored encrypted and can't be viewed again.
Test it
The test button verifies the token and lists the zones it can see, for example “3 zones”. A token scoped to one sub-zone works too: aoox looks for the longest matching zone of each host.
Deleting a connection is refused while a domain or a proxy still uses it (409), because aoox could no longer clean up the records it created. Every project member can see the connection names (to choose them on a domain); only owners and admins add, test or delete.
DNS records for a domain
On the application's Domain tab, the add form has a DNS record choice: I manage DNS myself (default) or Cloudflare: <connection name>. Each existing domain has the same choice on its row, with a status badge, a sync button and the last message. Developers and up can change it; viewers see it read-only.
| Option | Meaning |
|---|---|
| Proxied (orange cloud) | Off by default. The proxy needs to see the real host and answer certificate challenges itself. Turn it on only if you want Cloudflare in front; then its SSL mode must be Full (strict) (see How HTTPS works). |
| Replace an existing record with different content | Off by default. See the rules below. |
What aoox does with existing records
| Situation | What aoox does |
|---|---|
| No record for the name | Creates it (automatic TTL, comment “Managed by aoox”). |
| A record aoox created earlier has drifted | Updates it in place. |
| A record with other content exists | Leaves it alone and reports a warning. With Replace an existing record… on, it updates it and takes it over. |
| An identical record exists that aoox did not create | Leaves it as it is and does not track it, so it is never deleted later. |
| A CNAME exists on that name | Does not create anything and warns. |
| No zone matches the host, or Cloudflare is unreachable | Warns; the domain itself is still added. |
- DNS never makes the request fail. The domain is added and the problem comes back as a warning (“Domain added, but DNS needs attention”) plus a DNS warning or DNS error badge on the row. Fix the cause and press the sync button to retry; DNS ok means the record is in place.
- aoox only deletes records it created, by their stored id, when you delete the domain, delete the application, or switch the domain back to I manage DNS myself. It never lists or deletes anything else in your zone.
- The record is written before the container is recreated, so the first certificate request already finds the name.
- Deleting a whole project removes the rows only: the records stay in Cloudflare.
- Project export keeps the connection name and the proxied flag, never the token or record ids. An import creates no record: use the sync button.
DNS-01 on the proxy
Certificates are HTTP-01 unless you enable this. It adds a second ACME resolver to Traefik that answers challenges through Cloudflare.
Set an ACME email on the proxy first
DNS-01 uses the same ACME account email, so the proxy must already have one (Provisioning the reverse proxy).
Infrastructure → Reverse proxy → the DNS-01 certificates card
Choose the proxy (aoox host or a remote server), pick the DNS connection and click Enable DNS-01. Owners change it; admins can read it.
Confirm the recreation
On a running proxy a dialog Recreate the proxy? appears: the proxy is recreated, a few seconds without service for every domain on it. Certificates and other routes stay. Continue with Recreate and continue.
The card shows the state: Active, Off, Not applied yet (saved, proxy not recreated) or Proxy not running, and what depends on it. The Disable button is refused (409) while a domain or preview still uses DNS-01; move them back to automatic first.
docker inspect on that machine can read it, like other secrets aoox passes to containers. Use a token limited to the zones you need.Certificate modes
Once the proxy has DNS-01, an HTTPS domain gets a Certificate mode choice on the Domain tab (without DNS-01 it only says DNS-01 is not enabled on this proxy yet):
| Mode | Certificate |
|---|---|
| Automatic (HTTP-01) | The default: requested when the host is first reached, needs port 80. |
| DNS-01 for this host | One certificate for that host, proved through DNS. |
DNS-01 wildcard (*.example.com) | One certificate for the parent domain of the host (app.example.com becomes *.example.com), shared by every host under it. |
- Only for HTTPS domains, and not together with an uploaded certificate (the API answers 400).
- If a domain asks for DNS-01 but its proxy no longer has the resolver, it falls back to HTTP-01 with a warning instead of failing.
- Importing a project keeps a DNS-01 mode only when the destination proxy has DNS-01; otherwise the domain uses HTTP-01 and the report says so.
Wildcard certificate for previews
Pull request previews normally get a certificate per preview host. On the application's Webhook tab, the previews card has Wildcard certificate for previews: one DNS-01 certificate for *.<preview domain> instead of one per pull request. It needs DNS-01 on the proxy and a preview domain; the switch is disabled with an explanation until both exist.
*.preview.example.com yourself, as described in the preview prerequisites.Limits
- Cloudflare only. Other DNS providers are not supported yet.
- Records are created for application domains only. Domains of compose stacks and the hosts of database admin UIs keep manual DNS.
- There is no DNS check against Cloudflare itself; the usual DNS check still compares public DNS with the expected IP.
- The actual issuance of DNS-01 certificates and proxies on remote servers have not been tried against a real Cloudflare account yet; test with a staging ACME setup first.
Common pitfalls
| Symptom | Cause & fix |
|---|---|
| Test says 403 or lists no zones | The token lacks Zone:Zone:Read or Zone:DNS:Edit, or is limited to other zones. Create a new token. |
| Warning: no zone for the host | The token cannot see the zone that holds the host. Add that zone to the token. |
| Warning: a record already exists | Another record with different content is on the name. Change it yourself, or use Replace an existing record…. |
| Browser rejects the certificate with Proxied on | Cloudflare's SSL mode must be Full (strict); or turn Proxied off. |
| Enable DNS-01 asks for an ACME email | The proxy has no ACME email yet; set it first. |
| Cannot delete the connection or disable DNS-01 (409) | A domain, preview or proxy still uses it. Detach those first. |
Next steps
Found a mistake? Edit this page on GitHub ↗