Reverse proxy e URL base

Metti HolyArrs a un indirizzo come https://home.example/holyarrs dietro il tuo reverse proxy.

Un reverse proxy è il server web davanti alle tue app che manda ogni indirizzo al container giusto. La URL base è il percorso sotto cui vive HolyArrs.

Impostare il percorso

1. Aggiungi il percorso al tuo file Compose:

   services:
     holyarrs:
       environment:
         - HOLYARRS_URL_BASE=/holyarrs

2. Riavvia il container.

3. Aggiungi una regola del proxy da Esempi di proxy.

4. Apri https://home.example/holyarrs/. Dovresti vedere la pagina di accesso. Settings > This app (Impostazioni > Questa app) mostra il percorso in uso.

Attenzione

Il tuo proxy deve passare il percorso senza modificarlo. Se toglie /holyarrs, ogni pagina dice che non è stata trovata.

Scelte

Dove impostare il percorso

Dove	Quando ha effetto
HOLYARRS_URL_BASE	All’avvio. Vince sugli altri.
Opzione -url-base /holyarrs	All’avvio, quando la variabile non è impostata.
Settings > This app	Al prossimo avvio, solo quando variabile e opzione non sono impostate.

Esempi di proxy

nginx-proxy-manager. Crea un proxy host per il tuo dominio, poi aggiungi una posizione personalizzata:

• Posizione: /holyarrs
• Nome host di inoltro holyarrs, porta 6262. Nessuno slash alla fine, altrimenti il percorso viene tolto.
• Nella casella dell’ingranaggio di quella posizione:

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_buffering off;
proxy_read_timeout 1h;

Traefik. Non aggiungere un middleware StripPrefix.

labels:
  - traefik.enable=true
  - traefik.http.routers.holyarrs.rule=Host(`home.example`) && PathPrefix(`/holyarrs`)
  - traefik.http.services.holyarrs.loadbalancer.server.port=6262

Caddy. Usa handle. handle_path toglie il percorso.

home.example {
  handle /holyarrs* {
    reverse_proxy holyarrs:6262 {
      flush_interval -1
    }
  }
}

Nomi host e indirizzi del proxy

• Se le persone raggiungono HolyArrs con un nome host, aggiungilo a HOLYARRS_ALLOWED_HOSTS.
• Se il proxy aggiunge X-Forwarded-For, aggiungi l’indirizzo del proxy a HOLYARRS_TRUSTED_PROXIES. Senza, l’accesso non riesce a capire chi è nella tua rete di casa.

Se non funziona

Sintomo	Causa	Soluzione
Ogni pagina dice che non è stata trovata	Il proxy toglie il percorso	Togli l’impostazione che lo rimuove o lo slash finale.
Gli aggiornamenti in tempo reale non arrivano mai	Il proxy mette le risposte in buffer	Disattiva il buffering (proxy_buffering off, flush_interval -1).
Un percorso salvato ti ha chiuso fuori	Il percorso salvato è sbagliato	Avvia con HOLYARRS_URL_BASE=/ per ignorarlo.
L’accesso ti tratta come se fossi fuori dalla tua rete	Il proxy non è tra quelli attendibili	Invia X-Real-IP e X-Forwarded-For, e imposta HOLYARRS_TRUSTED_PROXIES.

Altre soluzioni: Risoluzione dei problemi.

Per esperti

Regole del percorso

• Caratteri consentiti: lettere, cifre, -, _, . e /. Niente .. né //.
• holyarrs, /holyarrs e /holyarrs/ significano tutti /holyarrs.
• Un percorso salvato non valido viene ignorato.
• Tutto si sposta sotto il percorso: pagine, API, aggiornamenti in tempo reale, accesso e i link che HolyArrs costruisce (link di invito, feed del calendario).
• /healthz e /readyz rispondono anche alla radice, così il controllo di salute dell’immagine continua a funzionare.
• Qualsiasi altro indirizzo fuori dal percorso risponde che non è stato trovato.

Cosa deve fare il proxy

Serve	Perché
Passare il percorso senza modificarlo	HolyArrs instrada in base al percorso completo.
Mantenere l’header Host	I controlli sull’host e i link costruiti lo usano.
Nessun buffering delle risposte	Gli aggiornamenti in tempo reale arrivano in streaming su una sola risposta aperta.
Timeout di lettura lungo (1 h)	Il flusso degli aggiornamenti in tempo reale resta aperto.

Correlati

• Installazione
• Accesso
• Variabili d’ambiente