Repository navigation
deployment
Muximux supports three deployment styles. Pick the one that matches your setup.
| Style | You provide | Muximux does | Ports to expose |
|---|---|---|---|
| Behind an external proxy | Traefik / nginx / Caddy handles TLS and auth | Serves the dashboard on a single port | 8080 (internal only) |
| Standalone with built-in proxy | Direct access, optional built-in auth | Dashboard + per-app /proxy/{slug}/ for iframe embedding |
8080 |
| Full reverse proxy appliance | DNS records | TLS certificates, HTTP→HTTPS redirects, gateway for other services | 80, 443 |
The built-in per-app reverse proxy (proxy: true, a proxy that forwards each app's requests through Muximux) works in all three styles. It runs inside the Go server, and it is independent of Caddy or any external proxy.
The recommended way to run Muximux in production.
# docker-compose.yml
services:
muximux:
image: ghcr.io/mescon/muximux:latest
ports:
- "8080:8080"
volumes:
- ./data:/app/data
restart: unless-stoppedSet auth.method: none or forward_auth in config.yaml. Let your external proxy handle TLS and authentication.
# docker-compose.yml
services:
muximux:
image: ghcr.io/mescon/muximux:latest
ports:
- "80:80"
- "443:443"
volumes:
- ./data:/app/data
restart: unless-stoppedConfigure tls.domain and gateway_sites in config.yaml. See TLS & HTTPS for a full walkthrough. You do not need to expose port 8080. Caddy handles all traffic on 80/443.
Note: 3.1.0 removed the legacy
server.gateway:Caddyfile path. The declarativeserver.gateway_sites:YAML replaced it. Under 3.1.0, Muximux migrates a 3.0.x config (and any mountedsites.Caddyfile) automatically on first boot.
You can configure single sign-on entirely from the environment, with the client secret in a Docker secret. So the container needs no config.yaml to start on OIDC. See Configuring OIDC with environment variables for the variables, precedence and startup checks.
Both examples assume that Muximux is already reachable at https://muximux.example.com through your HTTPS reverse proxy (or the built-in TLS above). The reason is that the identity provider sends the browser back to that address. Plain http:// on port 8080 is not enough for the callback.
Docker Compose with a file-based secret. Compose mounts it at /run/secrets/<name>. The container user (PUID) must be able to read the file.
# docker-compose.yml
services:
muximux:
image: ghcr.io/mescon/muximux:latest
ports:
- "8080:8080"
volumes:
- ./data:/app/data
environment:
- MUXIMUX_AUTH_METHOD=oidc
- MUXIMUX_OIDC_ISSUER_URL=https://auth.example.com/application/o/muximux/
- MUXIMUX_OIDC_CLIENT_ID=muximux
- MUXIMUX_OIDC_CLIENT_SECRET_FILE=/run/secrets/muximux_oidc_secret
- MUXIMUX_OIDC_REDIRECT_URL=https://muximux.example.com/api/auth/oidc/callback
- MUXIMUX_OIDC_ADMIN_GROUPS=muximux-admins
secrets:
- muximux_oidc_secret
restart: unless-stopped
secrets:
muximux_oidc_secret:
file: ./secrets/muximux_oidc_secret.txtDocker Swarm stack with an external secret. Create the secret once. Then deploy the stack:
printf '%s' 'the-client-secret-from-your-provider' | docker secret create muximux_oidc_secret -
docker stack deploy -c muximux-stack.yml muximux# muximux-stack.yml
services:
muximux:
image: ghcr.io/mescon/muximux:latest
ports:
- "8080:8080"
volumes:
- muximux-data:/app/data
environment:
MUXIMUX_AUTH_METHOD: oidc
MUXIMUX_OIDC_ISSUER_URL: https://auth.example.com/application/o/muximux/
MUXIMUX_OIDC_CLIENT_ID: muximux
MUXIMUX_OIDC_CLIENT_SECRET_FILE: /run/secrets/muximux_oidc_secret
MUXIMUX_OIDC_REDIRECT_URL: https://muximux.example.com/api/auth/oidc/callback
MUXIMUX_OIDC_ADMIN_GROUPS: muximux-admins
secrets:
- muximux_oidc_secret
deploy:
replicas: 1 # sessions are held in memory, so run one replica
secrets:
muximux_oidc_secret:
external: true
volumes:
muximux-data:The client ID can come from a secret in the same way, with MUXIMUX_OIDC_CLIENT_ID_FILE. Register https://muximux.example.com/api/auth/oidc/callback as the redirect URL at your provider. The first start creates no setup token. It opens the login page with the SSO button. Add MUXIMUX_OIDC_AUTO_REDIRECT=true to skip that page and go straight to the provider.
Mount a directory to /app/data. This stores:
-
config.yaml-- Configuration -
themes/-- Custom themes -
icons/-- Icon caches and custom uploads
The Docker image includes a built-in health check (GET /api/health every 30s).
To use JSON log format (recommended for container log drivers like Loki or ELK):
environment:
- MUXIMUX_LOG_FORMAT=jsondocker compose pull
docker compose up -dFor running Muximux as a native binary on Linux.
Create /etc/systemd/system/muximux.service:
[Unit]
Description=Muximux - Web Application Portal
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=muximux
Group=muximux
WorkingDirectory=/opt/muximux
ExecStart=/opt/muximux/muximux --data /opt/muximux/data
Restart=on-failure
RestartSec=5
# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/muximux/data
PrivateTmp=true
[Install]
WantedBy=multi-user.target# Create user
sudo useradd -r -s /bin/false muximux
# Create directories
sudo mkdir -p /opt/muximux/data
sudo chown -R muximux:muximux /opt/muximux
# Copy binary
sudo cp muximux /opt/muximux/
# Create config
sudo cp config.example.yaml /opt/muximux/data/config.yaml
sudo chown muximux:muximux /opt/muximux/data/config.yaml
# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable muximux
sudo systemctl start muximux
# Check status
sudo systemctl status muximux
sudo journalctl -u muximux -f
# Enable debug logging temporarily
sudo systemctl set-environment MUXIMUX_LOG_LEVEL=debug
sudo systemctl restart muximuxIf you run Muximux behind Nginx, Traefik, or Caddy (external), you do not need Muximux's built-in TLS or gateway. Your external proxy handles TLS termination (decrypting HTTPS), and optionally authentication. In config.yaml, set auth.method: none if your proxy handles auth. Or set forward_auth for Authelia/Authentik.
The per-app reverse proxy (proxy: true) still works in this setup. It runs inside the Go server and is unrelated to the external proxy.
server {
listen 443 ssl;
server_name muximux.example.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# WebSocket support
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}services:
muximux:
image: ghcr.io/mescon/muximux:latest
labels:
- "traefik.enable=true"
- "traefik.http.routers.muximux.rule=Host(`muximux.example.com`)"
- "traefik.http.routers.muximux.tls.certresolver=letsencrypt"
- "traefik.http.services.muximux.loadbalancer.server.port=8080"
volumes:
- ./data:/app/dataIf your reverse proxy serves Muximux at a subpath (e.g., https://example.com/muximux/ instead of a dedicated domain), configure the base path. Muximux then generates correct URLs for assets, API calls and WebSocket connections.
Set the base path using any of these methods (in order of precedence):
# CLI flag
muximux --base-path /muximux
# Environment variable
MUXIMUX_BASE_PATH=/muximux muximux
# Or in config.yaml
server:
base_path: /muximuxThe path must start with / and have no trailing slash. If you do not set it, Muximux serves from the root.
location /muximux/ {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# WebSocket support
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}services:
muximux:
image: ghcr.io/mescon/muximux:latest
environment:
- MUXIMUX_BASE_PATH=/muximux
labels:
- "traefik.enable=true"
- "traefik.http.routers.muximux.rule=PathPrefix(`/muximux`)"
- "traefik.http.routers.muximux.tls.certresolver=letsencrypt"
- "traefik.http.services.muximux.loadbalancer.server.port=8080"
volumes:
- ./data:/app/dataNote: Muximux handles its own path stripping internally. Do not use Traefik's
StripPrefixmiddleware: Muximux expects the full path including the base prefix and strips it itself.
services:
muximux:
image: ghcr.io/mescon/muximux:latest
environment:
- MUXIMUX_BASE_PATH=/muximux
ports:
- "8080:8080"
volumes:
- ./data:/app/data
restart: unless-stopped- Same network as apps: Muximux needs to reach your apps (for health checks and the built-in reverse proxy). In Docker, use the same Docker network or host networking.
- WebSocket support: If you run behind an external reverse proxy, make sure that it supports WebSocket connections. Real-time health updates need them.
-
Ports:
- Behind an external proxy: only 8080 (or your configured listen port). It does not need to be publicly accessible.
- Standalone: 8080 (or your configured listen port).
- Full reverse proxy appliance: 80 and 443. You do not need to expose port 8080 externally.
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