Custom Domains

Custom domains let you serve your applications from your own domain names instead of Reoclo-provided subdomains. Reoclo handles DNS verification, SSL certificate provisioning, and continuous monitoring to keep your domains healthy.

Prerequisites

Before adding a custom domain:

• DNS access: You need the ability to add TXT records to your domain’s DNS settings.
• Admin role: Only admins can add, verify, or delete domains.
• Application deployed (optional): You can add domains before or after deploying an application. If you add a domain before deployment, you can link it to an application later.

Adding a Domain

1. Navigate to Domains

   From the dashboard, go to Servers → Domains.

2. Add a new domain

   Click Add Domain and enter your fully qualified domain name (FQDN):

   app.example.com

   Or use an apex domain:

   example.com

3. Link to an application (optional)

   If you want this domain to route to a specific application, select it from the dropdown. You can skip this step and link the domain later.

4. Save the domain

   Click Add Domain. Reoclo generates a verification token and displays DNS instructions.

Redirect www and other domains

A linked domain either serves its application or redirects to another address. Use a redirect to send traffic to one canonical domain. For example, send www.example.com to example.com, or send an old domain to your current domain.

Redirect www when you link a domain

1. Go to Domains and click Link Domain.
2. Select the root domain and the application. To link the root domain, leave the subdomain empty.
3. Select Also redirect www.example.com here.
4. Click Link Domain.

Reoclo links example.com to the application and links www.example.com as a 301 redirect to example.com. If you link www.example.com first, the checkbox offers the opposite direction.

Change an existing domain into a redirect

1. Open the domain and go to the Settings tab.
2. Set Behavior to Redirect.
3. In Redirect to, select a domain that serves the same application, or select A URL.
4. Click Save Changes.

Redirect options

Option	What it does
Redirect to a domain	Sends visitors to another domain of the same application. You can add a path, for example /blog.
Redirect to a URL	Sends visitors to any http or https address. The URL cannot have a query or a fragment.
Status	301 and 308 are permanent. 302 and 307 are temporary. 307 and 308 keep the request method.
Keep the request path	On: https://www.example.com/pricing?plan=pro goes to https://example.com/pricing?plan=pro. Off: every request goes to the target exactly.

A redirect domain runs on the server of its target. A URL redirect runs on the server of its application. Redirects work on servers that use the managed proxy or an external proxy.

Rules for redirects

• A redirect cannot point to another redirect. This prevents chains and loops.
• You cannot delete, unlink, or disable a domain when other domains redirect to it. Reoclo shows the redirect domains. Remove or change those redirects first.
• If you move a domain to a different server, the domains that redirect to it move with it.

Wildcard domains

A wildcard domain, for example *.example.com, matches domains with exactly one extra label, such as a.example.com or shop.example.com. It does not match example.com or a.b.example.com. Reoclo sends every match to one application.

• Verify the root domain first. A wildcard domain does not have its own TXT verification.
• On the managed proxy, a wildcard certificate needs the DNS-01 challenge. Add a Cloudflare DNS token that covers the zone and assign the token to the server. See Cloudflare DNS.
• A domain that you link separately, for example api.example.com, has priority over the wildcard. It can serve a different application.
• A wildcard domain can serve an application or redirect. It cannot be the target of a redirect.

Restrict inbound access by IP

On servers that use the managed proxy, you can limit who reaches your domains by source address. The proxy answers 403 Forbidden to every other address. Use this to lock an origin behind Cloudflare, or to keep an internal tool reachable only from your office or VPN egress.

Access is set in two places:

• The server default applies to every domain and preview on the server.
• A domain’s own setting replaces the server default for that domain.

Set the server default

1. Open the server and go to the Proxy tab.
2. Under Inbound access, turn on Cloudflare only, add addresses or CIDR ranges to Allowed IP ranges (one per line), or both.
3. Click Save inbound access.

To remove the default, turn off Cloudflare only, clear the ranges, and save.

Set access for one domain

1. Open the domain and go to the Settings tab.
2. Under Inbound access, select Set for this domain.
3. Turn on Cloudflare only, add ranges, or both. Leave both empty to accept every visitor, even when the server default restricts access.
4. Click Save Changes.

To follow the server default again, select Use the server default. Reoclo applies every change to the proxy on its next reconcile.

Option	What it does
Cloudflare only	Accepts Cloudflare’s published edge ranges, IPv4 and IPv6. Reoclo checks Cloudflare’s list daily and updates the proxy when it changes.
Allowed IP ranges	Accepts single addresses (203.0.113.7) and CIDR ranges (203.0.113.0/24, 2001:db8::/32). Up to 100 entries.

The proxy checks the address of the connection it receives, never the X-Forwarded-For header, so a client cannot claim an allowed address.

Caution

With Cloudflare only on, the DNS record must be proxied through Cloudflare (orange cloud). A DNS-only record sends visitors straight to your server, and the proxy refuses them.

• IP allowlists need the managed proxy. Reoclo refuses an allowlist on a server with an external proxy or no proxy, and refuses to move a restricted domain to such a server.
• While a server default or any domain on the server restricts access, Reoclo refuses to disable or uninstall the managed proxy, or to switch the server to an external proxy. Remove the allowlists first. No other proxy mode enforces them.
• Preview environments on the server follow the server default.
• The proxy must see each visitor’s real address. On rootless Docker, Docker’s userland proxy hides it, so every request appears to come from the same internal address. Reoclo detects this and refuses allowlists on such a server. Servers prepared with Set Up a New Server are configured correctly from the start. On another rootless server with RootlessKit 3.0 or newer, load the br_netfilter kernel module, add "userland-proxy": false to ~/.config/docker/daemon.json, and restart rootless Docker (systemctl --user daemon-reload && systemctl --user restart docker, which restarts your containers). RootlessKit 3.2 also needs DOCKERD_ROOTLESS_ROOTLESSKIT_DETACH_NETNS=false in the rootless Docker service’s environment; the Proxy tab shows the exact command. The runner installer prepares all of this for you, and running it with --repair does the same on a server that already has the runner. Load the module before you restart: without it, Docker does not start. You can also reinstall the runner in root mode (reoclo runner reinstall --mode root).
• Certificate issuance keeps working. The proxy answers Let’s Encrypt HTTP-01 challenges before it checks the allowlist.
• The allowlist applies to redirect domains too. A refused visitor gets 403 instead of the redirect.

Visitor IPs behind Cloudflare

When Cloudflare proxies your domains, every connection to your server comes from a Cloudflare edge address, so your apps see Cloudflare instead of the visitor. Turn on Visitor IPs behind Cloudflare on the server’s Proxy tab and the managed proxy takes each visitor’s address from Cloudflare’s CF-Connecting-IP header and sends it to your apps as X-Forwarded-For, replacing any value the visitor sent.

• The proxy trusts the header only on connections from Cloudflare’s published ranges, the same list Cloudflare only uses. A visitor who reaches the server directly cannot set their own address.
• It applies to every domain and preview on the server. Domains with DNS-only records keep the connecting address.
• Inbound access rules keep matching the connecting address, so Cloudflare only still works with this on.
• Like allowlists, it needs the managed proxy and a server where the proxy can see visitors’ addresses.

Verifying Your Domain

After adding a domain, you must verify ownership by adding a TXT record to your DNS settings.

1. Copy the verification token

   Reoclo shows a verification token in the domain detail view:

   reoclo-verification=abc123def456...

2. Add a TXT record to your DNS

   In your DNS provider’s control panel (Cloudflare, Route 53, Namecheap, and so on), add a TXT record:

   Type	Name	Value
   TXT	_reoclo-verify.app.example.com	reoclo-verification=abc123def456...

   If you are verifying an apex domain (example.com), the name is _reoclo-verify.example.com.

   Tip

   DNS propagation can take 5-60 minutes depending on your provider. Use a tool like dig to check if the record is live:

   dig TXT _reoclo-verify.app.example.com +short

   You should see the verification token in the output.

3. Trigger verification

   Once the TXT record is live, return to the domain detail view in the Reoclo dashboard and click Verify Domain.

   Reoclo checks your DNS records. If the token matches, the domain status changes to Verified.

4. Point your domain to Reoclo

   After verification, add an A or CNAME record to route traffic to your Reoclo server:

   Type	Name	Value
   A	app.example.com	<your-server-ip>

   Or use a CNAME if your DNS provider supports it for subdomains:

   Type	Name	Value
   CNAME	app.example.com	<your-reoclo-hostname>

   Caution

   Most DNS providers do NOT allow CNAME records on apex domains (example.com). Use an A record instead, or check if your provider supports CNAME flattening (Cloudflare does).

   If a Cloudflare token covers the zone, Reoclo can create this record for you. See Let Reoclo write the records.

Monitoring

After verification, Reoclo continuously monitors your domain’s health across three dimensions.

DNS Status

Checks if your domain resolves correctly to the expected IP address.

• Resolving: DNS lookup in progress.
• Resolved: Domain points to the correct server.
• Misconfigured: Domain points to the wrong IP or does not resolve.

If DNS status shows Misconfigured, check your A or CNAME record in your DNS provider.

SSL Status

Tracks SSL certificate provisioning and validity.

• Provisioning: Certificate is being requested.
• Active: Certificate is valid and not close to expiry.
• Expired: Certificate has expired. Reoclo will attempt to renew automatically.
• Error: Certificate provisioning failed (usually due to DNS misconfiguration).

Note

SSL certificates are provisioned automatically after DNS verification. This can take 1-5 minutes. If provisioning fails, check that your domain resolves correctly and that port 80 is accessible on your server for the certificate challenge.

Uptime Status

Monitors HTTP availability of your domain.

• Up: Domain responds to HTTP requests.
• Down: Domain is unreachable.
• Degraded: Intermittent failures or slow response times.

Updating a Domain

You can update a domain’s linked application or disable it temporarily.

1. Go to Servers → Domains and select the domain.
2. Click Edit.
3. Change the linked application or toggle the domain status to Disabled.
4. Click Save.

Disabling a domain stops traffic routing but keeps the domain record and monitoring data. Re-enable it anytime by setting the status back to Active.

Deleting a Domain

Deleting a domain soft-deletes it. The domain record is retained for audit purposes but no longer routes traffic or appears in the domain list.

1. Go to Servers → Domains and select the domain.
2. Click Delete Domain.
3. Confirm the deletion.

Caution

After deletion, you can re-add the domain, but you will need to verify it again with a new TXT record.

Troubleshooting

Verification Fails with “TXT Record Not Found”

Cause: The TXT record has not propagated yet, or the record name is incorrect.

Fix:

1. Wait 5-10 minutes and try again
2. Check the record name: it must be _reoclo-verify.<your-domain>, not just <your-domain>
3. Use dig to verify the record is live:

   dig TXT _reoclo-verify.app.example.com +short

Verification Token Expired

Cause: Verification tokens expire after 30 days.

Fix:

1. Delete the domain and re-add it to generate a new token
2. Update the TXT record with the new token and verify again

SSL Status Stuck on “Provisioning”

Cause: The certificate challenge cannot reach your domain. Common reasons: DNS does not resolve to the correct server, port 80 is blocked, or the application is not deployed.

Fix:

1. Check DNS status first. If it is Misconfigured, fix your A/CNAME record
2. Ensure port 80 is open on your server:

   sudo ufw status

   If port 80 is blocked:

   sudo ufw allow 80/tcp

3. Verify the application is deployed and running in Applications → Deployments

If the domain is behind Cloudflare’s proxy (orange cloud), HTTP-01 cannot reach your server. Add a Cloudflare API token under DNS providers so Reoclo issues the certificate with DNS-01. See Cloudflare Proxied Domains.

Domain Shows “Down” in Uptime Monitoring

Cause: The application is not responding to HTTP requests, or the server is unreachable.

Fix:

1. Check the application deployment status. If the deployment failed, redeploy
2. Check if the container is running on the server (use the terminal in the dashboard or the reoclo/run action):

   docker ps

3. Check server health in Servers. If the server is Unreachable, investigate network connectivity

DNS Status Shows “Misconfigured”

Cause: The A record points to the wrong IP, or DNS has not propagated yet.

Fix:

1. Verify the A record value matches your server’s IP address (check the server detail page in the dashboard)
2. Wait 5-10 minutes for DNS propagation
3. Use dig to check current resolution:

   dig app.example.com +short

   The output should match your server’s IP

The Domain Shows the “Powered by Reoclo” Page

Cause: The domain points at a server that runs the managed proxy, but no application on that server is linked to the domain. The proxy serves this page for every hostname it has no route for, over HTTP and over HTTPS.

Fix:

1. Open the domain in Domains and select the Settings tab
2. Select the application and the server that must serve the domain, then save
3. Wait for the next reconcile. The page changes to your application within a minute

If Cloudflare proxies the domain in Full (strict) mode, Cloudflare shows error 526 instead of this page. The error clears after you link the domain and Reoclo issues the certificate. See Cloudflare shows error 525 or 526.

Next Steps

• Deploy an application to serve traffic on your custom domain
• Set up a status page to display domain uptime publicly
• Learn about encryption and how Reoclo protects your data