Repository navigation
gateway examples
3.1.0 note: The recipes below are written as gateway Caddyfile blocks for reference. In 3.1.0+ the supported configuration form is
server.gateway_sites:declarative YAML. On first boot, Muximux auto-migrates a 3.0.x Caddyfile to the YAML form. Use the Configuration Reference for the YAML schema. Use Settings -> Gateway in the dashboard to edit visually. The Caddyfile snippets here still describe what each gateway-site option does. Map them to the YAML equivalents by hand. Or feed your existing Caddyfile throughmuximux migrate-gatewayto see the conversion side-by-side.
This page has practical recipes for using Muximux's embedded Caddy as a reverse proxy (a server that forwards requests to another server) for your other services. See TLS & HTTPS for initial setup.
Your config.yaml needs TLS configured plus one or more gateway_sites: entries:
server:
listen: ":8080"
tls:
domain: "muximux.example.com" # or cert/key for manual TLS
email: "admin@example.com"
gateway_sites:
- domain: grafana.example.com
backend_url: http://grafana:3000
tls: auto # auto | none | customExpose ports 80 and 443. Caddy needs both, for ACME (automatic certificate requests) and for HTTPS. When you add or remove gateway_sites: entries, Caddy reloads in place. You do not need a full restart. Schema changes to existing sites (TLS-mode flip, auth gate toggle) also reload in place.
The recipe sections below show the Caddyfile shape for each scenario. Translate each one into the matching gateway_sites: entry fields (see Configuration Reference for the full schema).
Each gateway site proxies one backend_url per domain. The fields you can set are:
-
backend_url-- thehttp://orhttps://backend (no path, query, or transport flags) -
tls-- certificate mode (auto,none, orcustom) -
proxy_headers-- extra headers sent to the backend -
forwarded_headers-- emitX-Forwarded-*andX-Real-IP(default true) -
streaming-- disable response buffering for streaming backends -
strip_frame_blockers-- removeX-Frame-Options/CSP frame headers so the app can load in an iframe -
backend_skip_tls_verify-- skip verifying a self-signed / untrustedhttpsbackend certificate (e.g. Proxmox) -
require_auth/min_role/allowed_groups-- gate the site behind Muximux auth (see Gateway Auth)
Anything outside this list is not a gateway-site option. This includes basic auth, rate limiting, subpath routing, wildcard host matching, and arbitrary transport tuning like read_buffer. Those recipes are marked below. They need an external proxy in front of Muximux.
The simplest case: one domain, one backend.
grafana.example.com {
reverse_proxy localhost:3000
}
Caddy gets a Let's Encrypt certificate. It redirects HTTP to HTTPS. It proxies all traffic without any further configuration.
Add as many site blocks as you need:
grafana.example.com {
reverse_proxy localhost:3000
}
sonarr.example.com {
reverse_proxy localhost:8989
}
radarr.example.com {
reverse_proxy localhost:7878
}
prowlarr.example.com {
reverse_proxy localhost:9696
}
jellyfin.example.com {
reverse_proxy localhost:8096
}
Each domain gets its own certificate. Caddy handles renewals automatically.
Those backends can run as Docker containers. Then Apps tab → Discover from Docker (or Gateway tab → Discover from Docker) builds the same site list in one click:
- Pick "Gateway" routing for each row.
- Enter the public domain. Muximux creates the gateway site and reloads Caddy in the same transaction.
URLs refresh automatically when container IPs change. See Docker Discovery.
Or enable discovery.docker.auto_import. Then labeled containers appear automatically, without opening the modal (see Docker Discovery). Note: in update/sync mode, Muximux also applies gateway-only label changes, with no app-field change. For example, muximux.gateway.require_auth=false turns off the authentication gate for that site on the next poll. See Gateway labels and update/sync.
Labels on your compose file pre-fill name, icon, port, and a stable tracking key:
# docker-compose.yml
services:
sonarr:
image: linuxserver/sonarr
labels:
- muximux.discovery.id=sonarr-stable # survives docker-compose --force-recreate
- muximux.app.name=Sonarr
- muximux.app.icon=sonarr
- muximux.app.group=Media
# port + scheme auto-detected from the catalog for known imagesCaddy proxies WebSocket connections automatically, so apps like Homeassistant, Code Server, Portainer, and Gotify work with no extra configuration.
homeassistant.example.com {
reverse_proxy localhost:8123
}
Some apps need specific headers to work behind a reverse proxy.
On a gateway site, Muximux sends the forwarded headers for you. Put any other backend headers in proxy_headers:
gateway_sites:
- domain: app.example.com
backend_url: http://app:8080
proxy_headers: # extra headers sent to the backend
X-Api-Key: "secret"
forwarded_headers: true # X-Forwarded-* + X-Real-IP (default true; set false to suppress)Plex needs large header buffers and the real client IP:
plex.example.com {
reverse_proxy localhost:32400 {
header_up X-Real-IP {remote_host}
header_up X-Forwarded-For {remote_host}
header_up X-Forwarded-Proto {scheme}
transport http {
read_buffer 8192
}
}
}
Not available via
gateway_sites: this requires an external Caddy/nginx in front of Muximux. The embedded gateway only proxies onebackend_urlper domain. The gateway sends forwarded headers (X-Real-IP,X-Forwarded-*) automatically. You cannot configure the customtransport/read_buffertuning on a gateway site.
Proxmox serves its web UI on :8006 with a self-signed certificate. Set backend_skip_tls_verify: true, so that the gateway does not reject that certificate:
gateway_sites:
- domain: proxmox.example.com
backend_url: https://192.168.1.10:8006 # https + self-signed
tls: auto
backend_skip_tls_verify: true # skip verifying the backend certbackend_skip_tls_verify only applies to an https:// backend_url. It affects only the hop from the gateway to the backend. It does not affect the public-facing certificate that Caddy serves for proxmox.example.com. (Label form: muximux.gateway.skip_tls_verify=true.)
Vaultwarden needs both the web vault and WebSocket notifications:
vault.example.com {
reverse_proxy localhost:8082
}
Vaultwarden v1.29+ handles WebSocket on the same port, so a simple reverse_proxy is sufficient.
Harden responses with security headers:
sonarr.example.com {
header {
X-Content-Type-Options nosniff
X-Frame-Options DENY
Referrer-Policy strict-origin-when-cross-origin
-Server
}
reverse_proxy localhost:8989
}
The -Server removes Caddy's Server header from responses.
Protect a service that has no built-in authentication:
filebrowser.example.com {
basicauth {
admin $2a$14$... # bcrypt hash
}
reverse_proxy localhost:8085
}
Generate a bcrypt hash with Caddy's own tool (caddy hash-password) or any bcrypt utility. For example: htpasswd -nbBC 12 "" 'your-password' | cut -d: -f2. Muximux's embedded Caddy runs internally only. It does not have a command-line tool of its own.
Not available via
gateway_sites: this requires an external Caddy/nginx in front of Muximux. The embedded gateway only proxies onebackend_urlper domain. To gate a site behind Muximux's own login instead, setrequire_authon the gateway site (see Gateway Auth).
Protect public-facing services from abuse:
api.example.com {
rate_limit {
zone dynamic_zone {
key {remote_host}
events 10
window 1s
}
}
reverse_proxy localhost:9000
}
Note: Rate limiting requires the third-party
rate_limitCaddy module. This module is not compiled into Muximux's embedded Caddy. Only the standard module set is included: reverse proxying, headers, TLS, and basic auth. So this directive will not work here. For rate limiting, put Muximux behind an external proxy that provides it.
Route different paths on the same domain to different backends:
services.example.com {
handle /grafana/* {
reverse_proxy localhost:3000
}
handle /prometheus/* {
reverse_proxy localhost:9090
}
handle {
respond "Not found" 404
}
}
Configure each service to serve from its own subpath (e.g., Grafana's GF_SERVER_ROOT_URL=https://services.example.com/grafana/).
Not available via
gateway_sites: this requires an external Caddy/nginx in front of Muximux. The embedded gateway only proxies onebackend_urlper domain (no path orhandlerouting).
You can use a wildcard DNS record (*.example.com → your-server-ip). Then you add new services by just appending site blocks to the Caddyfile. You need no DNS changes per service.
Not available via
gateway_sites: this requires an external Caddy/nginx in front of Muximux. The embedded gateway only proxies onebackend_urlper domain, with no wildcard host matching. Add each subdomain as its own gateway site instead.
For wildcard TLS certificates, you need a DNS provider plugin for the ACME DNS-01 challenge (a check that proves domain control through a DNS record):
*.example.com {
tls {
dns cloudflare {env.CF_API_TOKEN}
}
@grafana host grafana.example.com
handle @grafana {
reverse_proxy localhost:3000
}
@sonarr host sonarr.example.com
handle @sonarr {
reverse_proxy localhost:8989
}
handle {
abort
}
}
Note: DNS provider plugins (like
cloudflare) must be compiled into the Caddy binary. Muximux's embedded Caddy includes the standard modules only. If you need DNS-01 challenges, you have two choices. Run Muximux behind an external Caddy instance that includes the DNS plugin. Or run certbot separately and usetls.cert/tls.keywith manual certificates.
When you run Muximux in Docker, Muximux must be able to reach your gateway backends. There are two approaches:
Add your services to the same Docker network as Muximux and use container names:
# docker-compose.yml
services:
muximux:
image: ghcr.io/mescon/muximux:latest
ports:
- "80:80"
- "443:443"
volumes:
- ./data:/app/data
networks:
- proxy
grafana:
image: grafana/grafana
networks:
- proxy
# No need to expose ports -- Caddy connects via the Docker network
networks:
proxy:
name: proxyThen in your gateway site, use the container name as the backend host:
gateway_sites:
- domain: grafana.example.com
backend_url: http://grafana:3000Alternatively, use network_mode: host or reference host.docker.internal:
gateway_sites:
- domain: grafana.example.com
backend_url: http://host.docker.internal:3000Note:
host.docker.internalworks on Docker Desktop and on Linux with Docker 20.10+ (addextra_hosts: ["host.docker.internal:host-gateway"]to your compose file).
A complete example for a typical homelab:
config.yaml:
server:
listen: ":8080"
tls:
domain: "home.example.com"
email: "admin@example.com"
gateway_sites:
- domain: grafana.example.com
backend_url: http://grafana:3000
tls: auto
- domain: sonarr.example.com
backend_url: http://sonarr:8989
tls: auto
apps:
- name: Grafana
url: https://grafana.example.com
icon: { type: dashboard, name: grafana }
open_mode: iframe
enabled: true
- name: Sonarr
url: https://sonarr.example.com
icon: { type: dashboard, name: sonarr }
open_mode: iframe
enabled: true
- name: Proxmox
url: https://proxmox.example.com
icon: { type: lucide, name: server }
open_mode: new_tab # Proxmox doesn't work in iframes
health_check: false # Proxmox health endpoint isn't standard
enabled: trueGateway sites only accept an http:// or https:// backend_url with no path, query, or subpath routing. This example shows Proxmox as a new_tab dashboard app, because its UI does not embed in an iframe. But it could also be a gateway site, because backend_skip_tls_verify handles its self-signed backend (see the Proxmox recipe above).
docker-compose.yml:
services:
muximux:
image: ghcr.io/mescon/muximux:latest
ports:
- "80:80"
- "443:443"
volumes:
- ./data:/app/data
networks:
- proxy
restart: unless-stopped
networks:
proxy:
external: trueEach gateway site you add automatically gets HTTPS. Add a corresponding app entry in config.yaml to see it on your dashboard.
-
In-place reload: Adding, editing, or removing
gateway_sitesreloads Caddy in place. You do not need a full restart. -
Validated before apply: Muximux validates gateway sites when the config loads, or when you save in Settings → Gateway. It rejects an invalid entry (bad domain, backend with a path, unknown
tlsmode) with a specific error. It does not silently break Caddy. -
Certificate storage: Caddy stores certificates in its data directory. The Docker image sets
XDG_DATA_HOME=/app/data, so this is/app/data/caddy, inside the data volume. The certificates survive when you recreate the container. Images up to 3.7.1 kept them in/app/.local/share/caddy, outside the volume, so Caddy requested new certificates after each recreate. Outside Docker, Caddy uses$XDG_DATA_HOME/caddy, or~/.local/share/caddyon Linux. -
Dashboard integration: Caddy proxies gateway sites directly. They do not go through Muximux's built-in reverse proxy. To see them on the dashboard, add them as apps in
config.yamlwith theirhttps://domain URLs. - Debug: If a gateway service isn't working, check Muximux's logs. Caddy logs through Muximux's logging system. It reports certificate errors and backends that it cannot reach.
Getting Started
Features
- Apps
- HTTP Actions
- Reverse Proxy
- Docker Discovery
- Docker Labels
- Docker Swarm & Compose
- Navigation
- Split View
- Themes
- Keyboard Shortcuts
- Keyboard & Accessibility
- Health Monitoring
- Icons
- Translations
Security
Identity provider guides
Operations