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
- Ask your Muppy operator to declare your name. They register it on the zone that serves your applications; validation is automatic and takes about two minutes.
-
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.
-
Fill Custom Domain (CNAME) on the App Server's Traefik Application, then press Reconfigure Application. The router starts accepting your name straight away.
Leaving the field empty removes the name again: the router stops accepting it at the next reconfiguration, and visitors get a 404.
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¶
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, or the application was not reconfigured |
| 403 | the router accepted the name and an IP whitelist refused you — routing works |
| 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.