Changed app for proxy and https++
This commit is contained in:
322
PROXY_SETUP.md
Normal file
322
PROXY_SETUP.md
Normal file
@@ -0,0 +1,322 @@
|
||||
# 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:
|
||||
|
||||
1. **Upstream Target**: `http://localhost:5172` (or your Docker IP)
|
||||
2. **Enable WebSocket**: Yes (optional, recommended)
|
||||
3. **Enable Proxy Headers**: Yes (should be default)
|
||||
|
||||
**Example Zoraxy Config:**
|
||||
```json
|
||||
{
|
||||
"name": "mailcow-alias-manager",
|
||||
"upstream": "http://localhost:5172",
|
||||
"domain": "aliases.yourdomain.com"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **Authelia** (Authentication Proxy)
|
||||
|
||||
If using Authelia in front of the app:
|
||||
|
||||
1. **Authelia forwards the user after login** - this should work automatically
|
||||
2. **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**
|
||||
|
||||
```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:**
|
||||
```yaml
|
||||
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**
|
||||
|
||||
```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:**
|
||||
1. Mixed HTTP/HTTPS content
|
||||
2. CORS blocking requests
|
||||
3. Session cookie not being set
|
||||
4. 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**
|
||||
```bash
|
||||
# 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
|
||||
|
||||
---
|
||||
|
||||
### **Issue: Login works but redirects to HTTP instead of HTTPS**
|
||||
|
||||
**Solution**: Already fixed in latest version via `PREFERRED_URL_SCHEME='https'` in app config.
|
||||
|
||||
If still happening:
|
||||
1. Verify proxy sends `X-Forwarded-Proto: https`
|
||||
2. Check `docker compose logs -f mailcow-alias-manager`
|
||||
3. 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:
|
||||
```bash
|
||||
# Reset password
|
||||
docker exec -it mailcow-alias-manager python3 reset_password.py "newpass"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **Issue: 502 Bad Gateway**
|
||||
|
||||
**Causes:**
|
||||
1. App not running
|
||||
2. Wrong upstream port
|
||||
3. Container network issue
|
||||
|
||||
**Check:**
|
||||
```bash
|
||||
# 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
|
||||
# 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:
|
||||
```python
|
||||
# In app.py, change:
|
||||
SESSION_COOKIE_SECURE=True # Only send cookie over HTTPS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Testing Your Setup
|
||||
|
||||
### **1. Basic Connectivity**
|
||||
```bash
|
||||
curl -v https://aliases.yourdomain.com/
|
||||
# Should return 200 OK with HTML
|
||||
```
|
||||
|
||||
### **2. Login Test**
|
||||
```bash
|
||||
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**
|
||||
```bash
|
||||
curl -v https://aliases.yourdomain.com/ \
|
||||
-b cookies.txt
|
||||
|
||||
# Should return main page HTML (not login redirect)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Still Having Issues?
|
||||
|
||||
### **Enable Debug Logging**
|
||||
|
||||
**docker-compose.yml:**
|
||||
```yaml
|
||||
environment:
|
||||
- FLASK_DEBUG=True # Enable debug mode
|
||||
```
|
||||
|
||||
Restart:
|
||||
```bash
|
||||
docker compose down
|
||||
docker compose up -d
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
### **Check Application Logs**
|
||||
```bash
|
||||
# View logs
|
||||
docker compose logs -f mailcow-alias-manager
|
||||
|
||||
# Check for errors
|
||||
docker compose logs mailcow-alias-manager | grep -i error
|
||||
```
|
||||
|
||||
### **Test Without Proxy**
|
||||
Temporarily bypass proxy to isolate the issue:
|
||||
```bash
|
||||
# Direct access test
|
||||
curl http://localhost:5172/
|
||||
```
|
||||
|
||||
If this works, the issue is with proxy configuration, not the app.
|
||||
|
||||
---
|
||||
|
||||
## ✅ Summary
|
||||
|
||||
**The app is already configured for reverse proxies!**
|
||||
|
||||
Key points:
|
||||
- ✅ ProxyFix middleware is enabled
|
||||
- ✅ Handles X-Forwarded-* headers automatically
|
||||
- ✅ HTTPS redirect support built-in
|
||||
- ✅ Session cookies work behind proxies
|
||||
- ✅ No code changes needed
|
||||
|
||||
Just make sure your proxy forwards the standard headers and you're good to go! 🚀
|
||||
Reference in New Issue
Block a user