Custom Domains¶
Pointing your own name at an App Server is the easy half: a CNAME at your DNS provider does it, and Muppy will route the name to your application. The half that decides everything is who holds the TLS certificate for that name — because a browser asks for it before it ever sends the host name.
Muppy offers three levels of naming. They differ in one line only, the last one.
| The name comes from | You create | The certificate comes from | |
|---|---|---|---|
| 1. The name you are given | Muppy | nothing | Let's Encrypt, on the operator's zone |
| 2. Your name, in front of a public URL | you, by CNAME | one CNAME | the Cloudflare edge in front of your application |
| 3. Your own domain, managed by you | you | your own records | Let's Encrypt, on your zone |
Level 1 works out of the box and needs no reading. This page is about 2 and 3.
Level 2 — your name in front of a public URL¶
This is the usual answer. Your application keeps the public URL Muppy gave it — say
erp-prod.acme.muppy.cloud — and answers to erp.acme.com as well. Both names reach the same
application; the Muppy one stays valid and is worth keeping for support.
It works because your application is served through Cloudflare, and Cloudflare holds a certificate for your name. Nothing is installed on the server.
What you do
-
Fill Custom Domain (CNAME) on the App Server's Traefik Application and save. The name is recorded in lower case, not yet served — Declare, at step 3, is what puts it in the router. It cannot be the name of the Muppy instance itself.
-
Create one CNAME at your DNS provider:
erp.acme.com. CNAME erp-prod.acme.muppy.cloud.Note the trailing dot if your provider's form expects one. A short TTL — 60 seconds — makes the first minutes easier to observe; raise it once the name answers.
-
Come back to the Traefik Application and press Declare. Muppy registers your name on the zone that serves your applications and asks for its certificate. The form then shows the state next to the field, and refreshes on its own while the certificate is being issued. Afterwards it stops: press Check whenever you want to know whether the name is still being served — that is also how you find out if your CNAME was changed or removed later.
The certificate usually arrives about two minutes after your CNAME resolves. Until then the state stays Pending, and the message underneath is what the provider reports while it retries: it is the normal wait, not a failure.
Nothing happens until you press Declare
Filling the field records your name. Declare does both of the things that make it answer: it puts the name in your application's router, and it asks the provider for the certificate. Until you press it, the name is served by nobody.
Changing or removing the name. While a declaration exists the field is locked, so that a typo cannot leave a certificate behind with nothing pointing at it. Press Remove to withdraw the declaration — the certificate goes with it — and the field becomes editable again. The router keeps accepting the name until you clear the field and reconfigure, so between the two your visitors get a certificate error rather than a 404.
A declaration that is never validated is abandoned
If your CNAME never resolves to the name Muppy gave you, the provider retries for a while and then drops the declaration. Fix the CNAME and press Declare again. The retry schedule is the provider's; see Cloudflare's backoff schedule for the detail.
A CNAME cannot be set on the root of a domain
acme.com itself cannot carry a CNAME — the DNS standard forbids it, and most providers
refuse the record. Use a sub-domain: erp.acme.com, www.acme.com. Some providers offer
ALIAS or ANAME records that work around it; if yours does not, publish a sub-domain and
redirect the root to it at your registrar.
One name per application. If you need two — erp.acme.com and www.acme.com — create a
second Traefik Application and give it the second name. Each one then has its own routing and
its own security settings.
Level 3 — your own domain, managed by you¶
If you want to name your applications freely rather than put one name in front of one application, connect your own domain to your Muppy instance. Muppy drives Cloudflare, OVH and Scaleway; a domain already registered elsewhere can be transferred or delegated to one of them, so this does not mean buying a new one.
Once the domain is connected, there is no CNAME at all: your applications are named
directly in your zone — erp.acme.com is the application's own name — and Muppy obtains the
Let's Encrypt certificate for it through the
DNS-01 challenge, because it can write in a zone
you have connected.
This is the level to choose when the naming is part of your product rather than a label on top of it.
Why the field is greyed out on some applications¶
Custom Domain is locked in two situations, for two different reasons.
While a declaration exists, so that changing the name cannot orphan its certificate. Press Remove first; see Changing or removing the name above.
On the direct route. An App Server is usually reachable by two routes: a public one through Cloudflare, and a direct one straight to the server. Custom Domain is available on the public one and locked on the direct one, with the reason shown next to the field.
The reason is the certificate. On the direct route the server obtains its own certificate from Let's Encrypt, and it can only do that for zones Muppy manages — your domain is not one of them. The name would be routed and the connection would then fail on the certificate, which is worse than not offering it. So the field is locked, and levels 2 and 3 are the ways through.
What a custom domain does not change¶
Your application chooses the name it writes in its own links. Password-reset emails, portal invitations and report footers carry whichever URL the application is configured with, not necessarily the name your visitors typed. If those links must show your name, set it in the application's own configuration.
Sessions are per host name. Someone who signs in on one name and then follows a link to the other will be asked to sign in again. Publishing one name and keeping the other for support avoids the surprise.
What your application receives¶
Measured on a live custom domain. Your application sees the name your visitor typed, and the visitor's own address — but not where a web application usually looks for it.
| Header | Value |
|---|---|
Host |
your name — erp.acme.com, not the Muppy one |
X-Forwarded-Host |
your name |
X-Forwarded-Proto |
https |
X-Forwarded-For |
the visitor first, then the proxies — 203.0.113.7, 172.69.222.205 |
CF-Connecting-IP |
the visitor |
X-Real-IP |
⚠️ the edge, not the visitor |
Do not read X-Real-IP
It carries the address of the Cloudflare edge that forwarded the request, so an application
that trusts it logs every visitor as the same handful of addresses — and any rate limit or
geo rule built on it applies to Cloudflare rather than to your users. Read
CF-Connecting-IP, or the first entry of X-Forwarded-For.
Requests through the Muppy name and through your own name are identical in shape: only Host
and X-Forwarded-Host differ. An application that works on one works on the other.
Checking that it works¶
From anywhere:
dig +short erp.acme.com
curl -sS -o /dev/null -w '%{http_code}\n' https://erp.acme.com/
| What you see | What it means |
|---|---|
| the CNAME, then addresses | your DNS record has propagated |
| a TLS error, no certificate | the name is not declared yet, or its certificate is still being issued |
| 404 | the request reached your application's server, but the router does not know this name — Custom Domain is empty on the application that serves it. When the field is filled and the router has not caught up, the application's own form says so and offers the button that fixes it |
| 403 | the router accepted the name and an IP whitelist refused you — routing works |
| a sign-in prompt | the name reached your application and Sunray Zero Trust stands in front of it — routing works; see Protect Your App Server with Sunray Zero Trust |
| your application | done |
A 404 and a 403 are both good news about the DNS chain: they are answered by your application's server, which means the name travelled all the way there.