Setting Up Muse Proxy — Step‑by‑Step TutorialMuse Proxy is a lightweight reverse proxy that helps route traffic, add TLS termination, and improve performance and security for web services. This tutorial will walk you through installing, configuring, and operating Muse Proxy on a Linux server, with practical examples for common scenarios: single-site proxying, multiple virtual hosts, TLS via Let’s Encrypt, basic authentication, and logging/monitoring.
What you’ll need
- A Linux server (Ubuntu 20.04/22.04 or similar) with sudo privileges
- A domain name with DNS A/AAAA record pointing to the server’s IP
- Basic familiarity with the shell and editing text files
- Optional: Docker if you prefer containerized deployment
1. Installing Muse Proxy
If Muse Proxy provides prebuilt binaries or a package repository, prefer that for stability. If not, use the official release binary.
Example (generic binary install):
# create a user sudo useradd --system --no-create-home --shell /usr/sbin/nologin muse # download binary (replace URL with latest release) sudo curl -L -o /usr/local/bin/muse-proxy https://example.com/muse-proxy-linux-amd64 sudo chmod +x /usr/local/bin/muse-proxy sudo chown muse:muse /usr/local/bin/muse-proxy If Muse Proxy is available as a Debian package or via a package manager, install it using apt or the provider’s instructions.
2. Basic configuration and file layout
Create a directory for Muse Proxy configuration and runtime files:
sudo mkdir -p /etc/muse-proxy sudo mkdir -p /var/lib/muse-proxy sudo chown -R muse:muse /etc/muse-proxy /var/lib/muse-proxy A minimal config file (YAML/JSON depending on Muse Proxy — here shown as YAML) might look like:
# /etc/muse-proxy/muse.yml listen: - host: 0.0.0.0 port: 80 hosts: example.com: upstream: http://127.0.0.1:3000 extra_headers: X-Forwarded-Proto: http Start Muse Proxy to test the configuration:
sudo -u muse /usr/local/bin/muse-proxy -config /etc/muse-proxy/muse.yml 3. Running Muse Proxy as a systemd service
Create a systemd unit so Muse Proxy starts on boot:
# /etc/systemd/system/muse-proxy.service [Unit] Description=Muse Proxy After=network.target [Service] User=muse Group=muse ExecStart=/usr/local/bin/muse-proxy -config /etc/muse-proxy/muse.yml Restart=on-failure LimitNOFILE=65536 [Install] WantedBy=multi-user.target Enable and start:
sudo systemctl daemon-reload sudo systemctl enable --now muse-proxy sudo journalctl -u muse-proxy -f 4. Proxying multiple virtual hosts
Extend the config to handle several domains and route to different backends:
listen: - host: 0.0.0.0 port: 80 hosts: app1.example.com: upstream: http://127.0.0.1:3001 app2.example.com: upstream: http://127.0.0.1:3002 static.example.com: upstream: http://127.0.0.1:8080 cache: true Reload the service after changes:
sudo systemctl reload muse-proxy 5. Enabling TLS with Let’s Encrypt
Muse Proxy may include ACME support; if so, you can automate certificate issuance. If not, use certbot and point Muse Proxy to the cert files.
Example ACME-enabled block (if supported):
tls: acme: email: [email protected] agree_tos: true domains: - example.com - app1.example.com If using certbot:
-
Install certbot and obtain certificates:
sudo apt install certbot sudo certbot certonly --standalone -d example.com -d app1.example.com -
Configure Muse Proxy to use the certs:
hosts: example.com: upstream: http://127.0.0.1:3000 tls: cert_file: /etc/letsencrypt/live/example.com/fullchain.pem key_file: /etc/letsencrypt/live/example.com/privkey.pem -
Reload Muse Proxy and set up automatic renewal hooks:
# reload on successful renewal via /etc/letsencrypt/renewal-hooks/deploy/reload-muse.sh sudo tee /etc/letsencrypt/renewal-hooks/deploy/reload-muse.sh > /dev/null <<'SH' #!/bin/sh systemctl reload muse-proxy SH sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-muse.sh
6. Basic authentication and access control
For simple HTTP Basic Auth, add credentials to the config (or use an htpasswd file if supported).
Example inline credentials (not recommended for production):
hosts: admin.example.com: upstream: http://127.0.0.1:4000 auth: method: basic users: - username: admin password: "$2y$10$...hashed..." # bcrypt hash if supported Using htpasswd file:
sudo apt install apache2-utils sudo htpasswd -c /etc/muse-proxy/htpasswd admin # update config hosts: admin.example.com: upstream: http://127.0.0.1:4000 auth: method: basic htpasswd: /etc/muse-proxy/htpasswd 7. Logging, metrics, and monitoring
Configure access/error logs and enable metrics (Prometheus) if supported:
logging: access_log: /var/log/muse-proxy/access.log error_log: /var/log/muse-proxy/error.log metrics: prometheus: true listen: 127.0.0.1:9100 Rotate logs via logrotate:
# /etc/logrotate.d/muse-proxy /var/log/muse-proxy/*.log { daily rotate 14 compress missingok notifempty copytruncate } 8. Common troubleshooting
- Muse Proxy won’t start: check
journalctl -u muse-proxyfor errors and validate YAML/JSON config. - DNS not resolving: ensure your domain A/AAAA records point to the server IP.
- TLS errors: verify certificate files paths and permissions; check ACME rate limits.
- ⁄504 upstream errors: confirm upstream service is running and accessible from the proxy host (curl localhost:3000).
- Permission denied on ports <1024: either run as root (not recommended) or use a firewall/redirection (iptables) or systemd socket activation.
9. Advanced tips
- Use upstream health checks and load balancing to distribute traffic across multiple backend servers.
- Put Muse Proxy behind a firewall and allow only necessary ports (⁄443).
- Run Muse Proxy inside a container for easier deployment; map config and certs via volumes.
- Use HSTS, OCSP stapling, and strong TLS ciphers for production security. Example cipher configuration depends on Muse Proxy syntax.
10. Example full config (combines above features)
listen: - host: 0.0.0.0 port: 80 - host: 0.0.0.0 port: 443 tls: acme: email: [email protected] agree_tos: true hosts: example.com: upstream: http://127.0.0.1:3000 tls: redirect: true app1.example.com: upstream: http://127.0.0.1:3001 admin.example.com: upstream: http://127.0.0.1:4000 auth: method: basic htpasswd: /etc/muse-proxy/htpasswd logging: access_log: /var/log/muse-proxy/access.log error_log: /var/log/muse-proxy/error.log metrics: prometheus: true listen: 127.0.0.1:9100 This guide showed installation, configuration, TLS, auth, logging, and troubleshooting for Muse Proxy. Adjust paths, ports, and options according to the actual Muse Proxy feature set and syntax (consult official docs for exact fields).
Leave a Reply