Reverse proxy

Se vuoi accedere a XIQUIL da Internet con un dominio personalizzato e certificato HTTPS valido, hai bisogno di un reverse proxy.

Quando serve un reverse proxy

Scenario	Reverse proxy necessario?
Accesso solo dalla rete locale (LAN)	No — usa https://ip-locale
Accesso da Internet con dominio personalizzato	Si
Certificato HTTPS valido (no avvisi browser)	Si
Piu servizi sullo stesso server	Si

Configurazione .env per reverse proxy

Quando usi un reverse proxy, aggiorna il file .env:

ALLOWED_HOSTS=tuodominio.com
FORCE_HTTPS=True
ENABLE_HSTS=True

Nota

ALLOWED_HOSTS e fondamentale. Se il dominio non e nella lista, XIQUIL rifiuta le richieste con un errore “Invalid host header”.

Traefik (consigliato per Docker)

Traefik gestisce automaticamente i certificati Let’s Encrypt. Aggiungi queste labels al servizio app:

services:
  app:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.xiquil.rule=Host(`tuodominio.com`)"
      - "traefik.http.routers.xiquil.entrypoints=websecure"
      - "traefik.http.routers.xiquil.tls.certresolver=letsencrypt"
      - "traefik.http.services.xiquil.loadbalancer.server.port=8443"
      - "traefik.http.services.xiquil.loadbalancer.server.scheme=https"
      - "traefik.http.services.xiquil.loadbalancer.serversTransport=insecureTransport@file"
    ports: []  # Rimuovi il port mapping diretto — Traefik gestisce il routing

Aggiungi un serversTransport nella configurazione dinamica di Traefik:

http:
  serversTransports:
    insecureTransport:
      insecureSkipVerify: true

Nota

insecureSkipVerify e necessario perche XIQUIL usa un certificato self-signed internamente. Traefik presenta il certificato Let’s Encrypt valido all’utente.

Caddy

Caddy gestisce automaticamente HTTPS con Let’s Encrypt:

tuodominio.com {
    reverse_proxy https://localhost:443 {
        transport http {
            tls_insecure_skip_verify
        }
    }
}

nginx

server {
    listen 443 ssl http2;
    server_name tuodominio.com;

    ssl_certificate     /etc/letsencrypt/live/tuodominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/tuodominio.com/privkey.pem;

    client_max_body_size 30m;

    location / {
        proxy_pass https://127.0.0.1:443;
        proxy_ssl_verify off;
        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_http_version 1.1;

        # Supporto SSE (log streaming)
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_buffering off;
        proxy_read_timeout 86400;
    }
}

server {
    listen 80;
    server_name tuodominio.com;
    return 301 https://$host$request_uri;
}

Nota

Note importanti per nginx:

• proxy_ssl_verify off accetta il certificato self-signed interno
• proxy_buffering off e necessario per lo streaming dei log in tempo reale
• client_max_body_size 30m deve corrispondere al limite di upload interno

Certificati personalizzati (senza reverse proxy)

Se non vuoi un reverse proxy ma vuoi usare i tuoi certificati:

1. Posiziona server.crt e server.key in una cartella
2. Monta la cartella nel container:

services:
  app:
    volumes:
      - /path/to/certs:/etc/nginx/certs:ro

3. Riavvia: docker compose up -d

Verifica

Dopo la configurazione:

1. Accedi a https://tuodominio.com
2. Verifica che il certificato sia valido (lucchetto verde nel browser)
3. Controlla i cookie in DevTools > Application > Cookies: devono avere il flag Secure
4. Testa il health endpoint: curl https://tuodominio.com/health

---

Domande frequenti

Perche vedo “Invalid host header”? Il dominio non e in ALLOWED_HOSTS. Aggiungilo nel file .env e riavvia.

Perche il reverse proxy non riesce a connettersi? XIQUIL usa HTTPS internamente (porta 8443). Il reverse proxy deve connettersi via https:// con verifica SSL disabilitata.

I log in tempo reale non funzionano dietro il reverse proxy Aggiungi proxy_buffering off nella configurazione nginx. Traefik e Caddy gestiscono lo streaming automaticamente.