Running on umbrelOS
Traefik Manager and its agent are in a community app store for umbrelOS, kept in chr0nzz/tm-UmbrelOS. Each app brings its own Traefik.
| App | Install it when |
|---|---|
| Traefik Manager | You want Traefik Manager and a Traefik on your Umbrel |
| Traefik Manager Agent | You run Traefik Manager on another machine and want it to manage a Traefik on your Umbrel. Needs umbrelOS 2.0 or later. See Agent |
Setup outside umbrelOS is required
umbrelOS keeps ports 80 and 443 for its own reverse proxy, so the Traefik in these apps listens on other ports. Nothing outside your network reaches it until you forward ports on your router, point your DNS at your public IP, and route your apps as described below. Behind CGNAT, or for your own network only, see Local network only or behind CGNAT.
Add the app store
- In umbrelOS, open the App Store.
- Open the menu in the top right corner and choose Community App Stores.
- Paste
https://github.com/chr0nzz/tm-UmbrelOSand click Add. - Open Traefik Manager App Store and install the app you want.
Required setup
Forward ports on your router
| App | External port 80 to | External port 443 to |
|---|---|---|
| Traefik Manager | 42080 on your Umbrel | 42443 on your Umbrel |
| Traefik Manager Agent | 43080 on your Umbrel | 43443 on your Umbrel |
The two apps use different ports, so they can be installed side by side.
DNS and certificates
Point an A record (and AAAA for IPv6) for each domain at your public IP. Certificates come from Let's Encrypt through the certificate resolver letsencrypt, using the HTTP challenge. The challenge arrives on port 80, so it works once port 80 is forwarded. New routes use this resolver by default.
Routing to other Umbrel apps
Route to an app's container, not to umbrel.local: a request through umbrel.local goes through that app's Umbrel login page. The container and port are APP_HOST and APP_PORT under app_proxy in the app's docker-compose.yml in the official Umbrel app repository.
| App | Backend URL |
|---|---|
| Immich | http://immich_server_1:2283 |
| Jellyfin | http://jellyfin_server_1:8096 |
| Nextcloud | http://nextcloud_web_1:80 |
| Vaultwarden | http://vaultwarden_server_1:8089 |
Apps that use host networking, such as Home Assistant and Plex, have no container to route to. Reach them through the host:
| App | Backend URL |
|---|---|
| Home Assistant | http://host.docker.internal:8123 |
| Plex | http://host.docker.internal:32400 |
TIP
If a host.docker.internal route times out, a firewall on the Umbrel is blocking containers from reaching the host. umbrelOS does not run one by default.
DANGER
A route published through this Traefik is not behind the Umbrel login. Protect anything sensitive with the app's own login or an authentication middleware.
Local network only or behind CGNAT
Behind CGNAT nothing from the internet can reach your Umbrel, so port forwarding and the Let's Encrypt HTTP challenge cannot work. The same goes when you only want your apps on your own network. Let something else hold the certificate and send plain http to this Traefik:
- Behind a reverse proxy you already run. Point it at
http://<umbrel-ip>:43080for the agent app, or42080for the Traefik Manager app, and keep the certificate there. A local DNS rewrite (AdGuard Home, Pi-hole) sends your domain to that proxy. - Through a tunnel, such as Cloudflare Tunnel. It takes the HTTPS connection and passes plain http on to
http://<umbrel-ip>:43080(or42080).
Either way, create the route with Cert Resolver set to No TLS and only the web entry point.
A route with TLS returns 404 on plain http
A router with a tls block only matches HTTPS connections, so plain http on web gets 404 page not found, even when web is listed on the route. The route form warns when TLS is on and web is selected.
The route on your front proxy
A request reaches the Umbrel only when the reverse proxy in front has a route for its domain. Without one, that proxy answers 404 page not found itself. If the proxy in front is a Traefik managed by Traefik Manager, add this route there:
| Field | Value |
|---|---|
| Hostname | The app's domain, or *.my-domain.com to cover every app at once |
| Backend | http://<umbrel-ip>:43080, or 42080 for the Traefik Manager app |
| Entry point | Your HTTPS entry point, for example websecure |
| Cert Resolver | The one your other working routes use |
| Middlewares | The same as your other routes, if any |
| Pass Host Header | On (the default), so the Umbrel's Traefik sees the original domain |
On the Umbrel, each app then gets its own route for the same domain, with No TLS and only web.
Wildcard hostnames
*.my-domain.com matches one level of subdomain: app.my-domain.com, not a.b.my-domain.com or my-domain.com itself. Its certificate must cover the wildcard, which needs a DNS challenge resolver. With an HTTP challenge resolver, add one route per domain instead.
Traefik Manager app
The first time you open it, the setup wizard asks you to create a Traefik Manager login. The Umbrel login is switched off for this app, so the Traefik Manager login, API keys and the mobile app all work.
Changes to the static config restart Traefik through the poison pill method, with no Docker socket access.
Data lives in ~/umbrel/app-data/tm-traefik-manager/data/ by default. App updates never overwrite it.
| Path | Holds |
|---|---|
traefik/static/traefik.yml | Traefik's static config, editable in Traefik Manager |
traefik/dynamic/ | Your routes, middlewares and services |
traefik/acme/ | Certificates |
tm/config/ | manager.yml, its companion files and the generated keys |
tm/backups/ | Backups taken before every change |
Traefik Manager Agent app
- Install the app. It keeps restarting until step 3 is done, which is expected.
- In your Traefik Manager, open Settings, Agents, add an agent and copy the API key it shows.
- In umbrelOS, open this app's settings and paste the key into TMA_API_KEY. The agent starts.
- In Traefik Manager, use
http://umbrel.local:4490as the agent's URL, or your Umbrel's IP address with port4490.
The agent has no web interface of its own. Opening it from the Umbrel dashboard shows its health status.
How this fits with umbrelOS
This Traefik runs next to the reverse proxy built into umbrelOS and does not replace it. umbrelOS keeps serving its dashboard and your apps on ports 80 and 443. Traefik only answers on its own ports, for the domains you route through it.
Limitations
- The Docker provider is not available, because the apps do not mount the Docker socket. Routes go through Traefik's file provider, which is what Traefik Manager edits.
- The apps are in a community app store, not the official Umbrel App Store.
Password reset
Open a terminal on the Umbrel, either over SSH or from Settings, Advanced settings, Terminal in umbrelOS, then run:
sudo docker exec -it tm-traefik-manager_web_1 flask reset-password --promptOther recovery methods: Reset Password.
Updating
New versions arrive through the umbrelOS App Store like any other app update. Your routes, settings and certificates are kept.