Traefik Servers¶
A Traefik Server is the Traefik reverse proxy Muppy installs and drives on a host: it
receives the HTTPS traffic of the host and routes it to the applications published there
(Muppy › Network › Reverse Proxies › Traefik servers). Muppy installs the Traefik binary
under /opt/muppy/traefik/, writes its configuration, and runs it as a systemd unit.
What protects the applications of a server, and the request limits of its Hardening tab, are described in Hardening your Traefik server with Muppy.
Traefik version¶
The field Traefik version of a Traefik Server names the Software Release it runs: a
release of type traefik, listed in Muppy › Configuration › Software Releases. A release
says which version it is and where its binary is downloaded from — for the releases Muppy
ships, the official linux_amd64 archive published on GitHub.
Muppy ships Traefik 3.7.17 as its newest system release, beside the older ones it still supports.
New servers take the release chosen in Settings ▸ Muppy Network ▸ Traefik ▸ Default version, which
the Install LXD App. Server wizard pre-fills. Until a release is saved there, the setting
offers traefik-3.7.17. An instance that saved another release keeps it: select
traefik-3.7.17 there for the servers you install from now on to run it. The servers that
already exist keep the release they name.
Changing the Traefik version¶
- Open the Traefik Server, and pick another release in Traefik version.
- Click Reconfigure, then Launch.
The Reconfigure downloads and installs the binary of the new release, uploads the configuration and restarts Traefik. When the installed version is already the one the server names, the binary is left as it is. Tick Reinstall the Traefik program in the dialog to download and reinstall it anyway; the certificates are kept unless Wipe the certificate store is ticked too.
The Reconfigure runs in the background: the dialog closes at once. Follow it in Qs (the
task journal), where its name gives the version and the options, such as
Reconfigure Traefik server 'lair.ovh@nucus' (traefik-3.7.14, regenerate applications).
Last Reconfigure, on the server's form, updates when Traefik is back up.
An AI agent launches the same Reconfigure through the infrastructure MCP, except that it cannot wipe the certificate store. See Reconfiguring a server.
Regenerate the application files, ticked by default, writes each application's file again in place, then removes only the files no application claims. Traefik keeps serving every application while the files are written.
When a step fails¶
A Reconfigure goes on past a step that fails — an application file that cannot be sent, a DNS record the provider refuses — and does the rest. It then ends failed. Its message says what is in place, what failed, and what to do. The task's result lists each failure: the object, the file, the host and the cause. The same holds for Reconfigure Application, for the reconfiguration of an App Server's applications, and for the provisioning of an App Server: a provisioning that ends failed leaves a usable App Server, and its message names the step to run again.
A failure of the main configuration still stops the Reconfigure before Traefik restarts.
A failed Reconfigure holds back the next Reconfigures of the same host: they wait in Qs until the failed message is retried or archived. Fix the cause, then retry it.
The ACME account and the certificates are kept. They live in
/opt/muppy/traefik/acme.json (and, for the DNS resolvers, in
/opt/muppy/traefik/resolvers_certs_storage/), which a change of version does not touch:
Traefik serves the same certificates after the restart, and renews them from the same Let's
Encrypt account. The file is created when it does not exist yet, and is always owned by
traefik with mode 0600.
The option Wipe the certificate store of the Reconfigure wizard is the one gesture that empties them. Traefik then requests every certificate again from Let's Encrypt, within the rate limits of the domain, and serves its default certificate until each one is issued. Keep it to recover a corrupted store.
Warning
A server that requests its certificates by DNS-01 needs a working DNS challenge chain before its store is wiped: with the chain broken, it is left with no certificate at all.
Upgrading from Traefik 3.6 to 3.7¶
Start with a Traefik Server that has no Let's Encrypt certificates, then move the others.
- Open the Traefik Server, and pick
traefik-3.7.17in Traefik version. - Click Reconfigure, then Launch. Leave Wipe the certificate store unticked.
- Check that the applications answer, and read the log of the Traefik unit.
The ACME account and the certificates come through unchanged: the same acme.json, the same
certificates served after the restart. No new certificate is requested.
What the log shows under 3.7.
- Two
WRNlines aboutaliasHeadersStrategy, and one aboutencodedCharacters, at each start. They are advice from Traefik 3.7, and change nothing in the routing. - Every step of a certificate request:
Obtaining bundled SAN certificate,Use solver type=dns-01,The server validated our request,Server responded with a certificate. Under 3.6 the same requests leave no line at theINFOlevel; their trace is in Muppy's DNS challenge log only. - No
ERRline. AnERRnames its router or resolver: read it before moving another server.
Going back to 3.6. Pick traefik-3.6.10 in Traefik version, then Reconfigure and
Launch, again without Wipe the certificate store. Every certificate, including those
issued under 3.7, is still served. A wildcard application
stops answering under 3.6: Traefik 3.6 refuses its *. host name.
Apex¶
An application whose Host name is @ serves the domain itself: on a Traefik Server whose
DNS domain is example.com, the application @ answers on https://example.com, where the
application erp answers on https://erp.example.com. Its routers, its certificate and its
FQDN read the domain alone.
An apex application is available on a Traefik Server set up as an HTTP LoadBalancer, the only setup type today. A Forced DNS Domain on the application names the domain it serves.
An apex is served directly, or through a Cloudflare tunnel: see No CNAME at the apex.
The template must serve the apex¶
Two application templates serve the apex: Generic Application v8 and Odoo Application
v9. An older template, or a Code Server template, would route @.example.com and ask a
certificate for that name. Muppy refuses it when the application is saved, before anything is
deployed: an application whose host name is @ is not saved when neither its App Config
Template nor its Template Body (the copy of the template stored on the application, which
is what gets rendered) serves the apex. While the Template Body is empty, the chosen template is
what gets rendered.
To move an existing application to a template that serves the apex: choose Generic Application v8 or Odoo Application v9 in App Config Template, save, then press (Re)load next to Template Body. Until the (Re)load, the application still renders its older copy, and its form warns Template Body not reloaded. An application generated by a Traefik Application Definition takes its template from the Definition: choose the template there, then reconfigure the reverse proxy of the App Server or Code Server. Until then, its provisioning stops with the same message.
What Muppy writes at the DNS provider¶
When the application creates its DNS records, Muppy writes one record at the apex: the A record pointing at the address the application is served from, or, when the host sends the apex through a Cloudflare tunnel, a proxied CNAME to that tunnel. It writes nothing else there, and removes nothing else when the application is deactivated or its DNS records are deleted: the NS, MX and TXT records of the apex, and any A record that points elsewhere, are never touched.
What Muppy refuses¶
The apex of a domain often carries an A record that someone relies on, such as the web redirection a registrar sets up for a new domain. Before it writes anything, Muppy reads the records of the apex at the provider; if an A, AAAA or CNAME record of the apex points anywhere other than what the application would write, or another object wrote it, the reconfiguration stops. Its message names the record found, and nothing has been written at the provider or uploaded to the server.
How the apex is read depends on the provider:
| DNS provider | What Muppy reads |
|---|---|
| OVH, Cloudflare, Scaleway, MBD Client | the A, AAAA and CNAME records of the apex only, in a few calls and a few seconds; Muppy updates its copy of those records, and of no other record of the zone |
| MBD Server | the same records, read at the provider of its backend domain |
| Unmanaged, Tailscale | the DNS records Muppy keeps for the zone, as they are: Muppy has no provider to ask |
To go on: remove that record or redirection at your DNS provider, then reconfigure. If the apex cannot be read (a refused credential, a zone the provider does not know, a provider that does not answer), the reconfiguration stops as well, since an A record already at the apex cannot be ruled out: its message names the zone, the provider and the class of the error.
When the apex is managed somewhere else, or the A record at the apex is the right one and must
stay as it is, set the application's DNS Records Creation Strategy to Don't create:
Muppy then neither reads nor writes the apex, and only serves the name. With Let's
Encrypt over a DNS challenge, the only record written is the temporary TXT record
_acme-challenge.<domain>, removed once the certificate is issued.
No CNAME at the apex¶
A CNAME cannot sit at the apex of a zone: the apex carries the NS and SOA records, which a CNAME forbids. The apex therefore takes an A record, and a name that must be a CNAME is served as a Custom Domain instead. Cloudflare is the exception: it serves a CNAME at the apex of its zones, and an apex can go through a Cloudflare Tunnel.
The configuration on the host¶
A Traefik Server renders two files from its settings: the main configuration and the certificates configuration. A Traefik Application renders one. Refresh renders them and stores the result; Reconfigure (server) and Reconfigure Application render, then send the files to the host.
Muppy keeps a copy of the file the host carries, the effective configuration, and the time it was recorded. A successful send, Download from Server and the removal of the file record it. The form warns Settings not applied when what the settings produce now differs from that copy. When the host's file is absent (a recorded, empty copy), an active application and a server warn with that reason. A file that remains on the host although none is expected (an application deactivated and not reconfigured) warns too: Reconfigure removes it. Refresh changes the stored rendering and not the host, so it does not clear the warning: Reconfigure does. Until a copy is recorded, the warning compares with the stored rendering.
The difference appears next to each configuration, under Pending Changes on an application.
It runs from the file on the host to what Reconfigure would write, and its first line says what
it compares with: on the host, absent from the host, or prepared by Muppy (host file not read)
while Muppy has not read the file. When no file is expected, as on a deactivated application, it
shows what Reconfigure would remove, if the host has it. In debug mode, the effective configuration
and two buttons appear beside it.
- Download from Server reads the file on the host into the effective configuration. It changes nothing on the host: use it after editing a file by hand. Muppy reads a regular file only, and refuses a symbolic link.
- Upload to Server sends the stored configuration to the host as it is, without rendering it again. On an application it sends the file only: no DNS record and no tunnel route, and an application that is inactive or has no service is refused. Traefik reads the certificates configuration and the applications by itself. It reads the main configuration at its start only, and Upload does not restart it: the file is applied at the next restart, and Reconfigure restarts Traefik.
An application renders from its own copy of its template, so Reconfigure Application never applies a newer template. When (Re)load would change what Reconfigure Application sends, the Configuration tab says so, and Changes after (Re)load appears under the (Re)load button of the Config Template tab: it shows what (Re)load then Reconfigure Application would change. When the file would stay as it is, a message says that only the stored copy would change it. A newly selected template counts once the form is saved.
Duplicating a Software Release¶
Duplicate on a Software Release (from its form, or on several lines selected in the list) creates a release that belongs to you:
- its version takes the suffix
(copy), so its name reads<name> (copy)— duplicatingtraefik-3.6.10givestraefik-3.6.10 (copy); - it is not a system release: you can edit it, and Muppy's upgrades leave it alone;
- a release of type
v2carries the lines of its Config files and Systemd units tabs, as copies of its own. Those lines still point at the same templates as the original's.
Edit the version of the copy to make it the release you need — a version a Traefik Server can
install is the version string of the Traefik binary, such as 3.7.14. Until then, a server
that names the copy reinstalls its binary at every Reconfigure: the installed version never
matches 3.7.14 (copy).





