Files

Rune Olsen e4fed12143 Changed app for proxy and https++

2026-01-22 16:32:02 +01:00

7.3 KiB

Raw Blame History

Reverse Proxy Setup Guide

This guide helps you configure reverse proxies (Nginx, Traefik, Zoraxy, Authelia, Caddy, etc.) to work with Mailcow Alias Manager.

✅ Built-in Proxy Support

The application includes ProxyFix middleware that automatically handles:

✅ HTTPS detection via X-Forwarded-Proto
✅ Host header forwarding via X-Forwarded-Host
✅ Client IP forwarding via X-Forwarded-For
✅ Path prefix support via X-Forwarded-Prefix

No configuration changes needed in most cases!

Common Proxy Configurations

Zoraxy (Your Current Setup)

Zoraxy automatically sets the required headers. Just configure:

Upstream Target: http://localhost:5172 (or your Docker IP)
Enable WebSocket: Yes (optional, recommended)
Enable Proxy Headers: Yes (should be default)

Example Zoraxy Config:

{
  "name": "mailcow-alias-manager",
  "upstream": "http://localhost:5172",
  "domain": "aliases.yourdomain.com"
}

Authelia (Authentication Proxy)

If using Authelia in front of the app:

Authelia forwards the user after login - this should work automatically
Make sure Authelia passes these headers:
- X-Forwarded-Proto
- X-Forwarded-Host
- X-Forwarded-For

Common Issue: Authelia redirects → App login page
Solution: The app has its own authentication. You have two options:

Option A: Disable app login (requires code modification)
Option B: Use Authelia for network access, app login for API access

Nginx

server {
    listen 443 ssl http2;
    server_name aliases.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:5172;
        
        # Required headers for ProxyFix
        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;
        proxy_set_header X-Forwarded-Host $host;
        
        # Optional: WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Traefik

docker-compose.yml:

services:
  mailcow-alias-manager:
    image: gitlab.pm/rune/malias-web:latest
    container_name: mailcow-alias-manager
    volumes:
      - ./data:/app/data
    restart: unless-stopped
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.malias.rule=Host(`aliases.yourdomain.com`)"
      - "traefik.http.routers.malias.entrypoints=websecure"
      - "traefik.http.routers.malias.tls=true"
      - "traefik.http.routers.malias.tls.certresolver=letsencrypt"
      - "traefik.http.services.malias.loadbalancer.server.port=5172"
    networks:
      - traefik

networks:
  traefik:
    external: true

Traefik automatically sets X-Forwarded-* headers by default.

Caddy

aliases.yourdomain.com {
    reverse_proxy localhost:5172
}

Caddy automatically handles all proxy headers - no configuration needed!

🔧 Troubleshooting

Issue: "NetworkError when attempting to fetch resource"

Causes:

Mixed HTTP/HTTPS content
CORS blocking requests
Session cookie not being set
Proxy not forwarding headers

Solutions:

1. Check Proxy Headers

Your proxy MUST forward these headers:

X-Forwarded-Proto: https
X-Forwarded-Host: aliases.yourdomain.com
X-Forwarded-For: <client-ip>

2. Check Browser Console

Open browser DevTools (F12) → Console tab → Look for errors:

CORS errors: Proxy misconfiguration
Mixed content: HTTP resources on HTTPS page
401 Unauthorized: Session/cookie issue

3. Test Direct Access

# Test without proxy
curl http://localhost:5172/

# Should return HTML (login page)

If this works but proxy doesn't, it's a proxy configuration issue.

4. Check Session Cookies

In browser DevTools → Application tab → Cookies:

Domain: Should match your proxy domain
Path: /
HttpOnly: Should be true
Secure: Depends on your setup

Solution: Already fixed in latest version via PREFERRED_URL_SCHEME='https' in app config.

If still happening:

Verify proxy sends X-Forwarded-Proto: https
Check docker compose logs -f mailcow-alias-manager
Rebuild image: docker compose up -d --build

Issue: "Invalid password" but password is correct

This is NOT a proxy issue - this is an authentication issue:

# Reset password
docker exec -it mailcow-alias-manager python3 reset_password.py "newpass"

Issue: 502 Bad Gateway

Causes:

App not running
Wrong upstream port
Container network issue

Check:

# Is container running?
docker ps | grep mailcow-alias-manager

# Check logs
docker compose logs -f mailcow-alias-manager

# Test internal connectivity
docker exec mailcow-alias-manager curl http://localhost:5172

🔒 Security Best Practices

1. HTTPS Only

Always use HTTPS in production. HTTP is only for local testing.

2. Restrict Access

Use firewall or proxy rules to restrict access:

# Nginx: Restrict to internal network only
allow 192.168.1.0/24;
deny all;

3. Use Authelia/Authentik

Add SSO layer for additional security:

Users authenticate via Authelia
Then app login provides API access
Two-factor authentication recommended

4. Keep Session Cookies Secure

The app sets:

HttpOnly=True - Prevents JavaScript access
SameSite=Lax - CSRF protection

For HTTPS-only deployments, you can enforce secure cookies:

# In app.py, change:
SESSION_COOKIE_SECURE=True  # Only send cookie over HTTPS

📊 Testing Your Setup

1. Basic Connectivity

curl -v https://aliases.yourdomain.com/
# Should return 200 OK with HTML

curl -v -X POST https://aliases.yourdomain.com/login \
  -H "Content-Type: application/json" \
  -d '{"password":"yourpassword"}' \
  -c cookies.txt

# Check response - should be JSON with status: success

3. Session Test

curl -v https://aliases.yourdomain.com/ \
  -b cookies.txt

# Should return main page HTML (not login redirect)

🆘 Still Having Issues?

Enable Debug Logging