Sottodominio, sottodirectory o dominio separato? Come scegliere una struttura URL per un'applicazione self-hosted
La scelta di dove ospitare un'applicazione self-hosted influisce sulla configurazione del reverse proxy, sui cookie, sui callback di autenticazione, sui webhook, su TLS, sul lavoro di migrazione e sui confini amministrativi. Usa questa guida per selezionare una struttura URL e convalidarla prima del lancio.
Perché la struttura URL è una decisione operativa, non solo una decisione di branding
Un URL fa parte del contratto pubblico di un'applicazione. Gli utenti lo salvano, i browser gli applicano regole di origine e cookie, i provider di identità possono registrarlo, i mittenti di webhook vi inviano richieste e i client API o i contenuti incorporati possono memorizzarlo. Di conseguenza, modificare l'URL in un secondo momento può influire su molto più che segnalibri e link di ricerca.
I tre modelli più comuni sono un sottodominio dedicato come https://app.example.com, una sottodirectory dietro un sito esistente come https://example.com/app e un dominio separato come https://exampleapp.com. La scelta migliore dipende dal modello di distribuzione documentato dell'applicazione e dai requisiti operativi, non semplicemente dall'indirizzo che sembra più corto.
Una distinzione tecnica fondamentale è l'origine. Un'origine web si basa su schema, host e porta; il percorso non fa parte dell'origine. Di conseguenza, https://example.com/app condivide un'origine con gli altri contenuti su https://example.com, mentre https://app.example.com usa un host diverso e quindi un'origine diversa. Questa differenza può essere rilevante per il comportamento del browser, la progettazione delle integrazioni e le aspettative di isolamento.
- Scegli l'URL pubblico prima di invitare utenti, collegare un provider di identità o pubblicare endpoint webhook.
- Considera l'URL canonico dell'applicazione come una configurazione da registrare e mantenere.
- Non presumere che un reverse proxy possa far funzionare correttamente ogni applicazione sotto un prefisso di percorso.
I tre modelli in sintesi
Un sottodominio dedicato colloca l'applicazione a un indirizzo come https://crm.example.com. Per molte applicazioni self-hosted, questa è la configurazione pubblica più lineare, perché l'applicazione può solitamente trattare / come percorso di base. Il reverse proxy instrada in base al nome host e i link generati, le risorse statiche e i reindirizzamenti non devono includere un prefisso di percorso pubblico aggiuntivo.
Una sottodirectory colloca l'applicazione sotto un hostname esistente, ad esempio https://example.com/analytics. Può creare un sito pubblico unificato e risultare utile quando un'azienda deve presentare un unico hostname. Tuttavia, introduce il requisito che sia il reverse proxy sia l'applicazione comprendano correttamente il percorso di base /analytics.
Un dominio separato colloca l'applicazione su un nome distinto, come https://example-portal.com. Questo può rendere più chiari i confini relativi a prodotto, cliente, unità aziendale o governance. Crea inoltre una superficie separata di DNS, TLS, proprietà del dominio e ciclo di vita da gestire.
- Sottodominio dedicato: di solito è l'opzione predefinita meno complessa per un'applicazione con login e integrazioni propri.
- Sottodirectory: appropriata solo dopo che la documentazione ufficiale dell'applicazione e un ambiente di staging hanno confermato il supporto degli URL relativi.
- Dominio separato: utile quando un chiaro confine pubblico, amministrativo o organizzativo è più importante del mantenere l'applicazione sotto il dominio principale del brand.
Parti dall'applicazione: verifica il supporto documentato per URL di base e reverse proxy
Inizia dalla documentazione dell'applicazione per l'installazione e il reverse proxy. Cerca nello specifico impostazioni supportate denominate base URL, external URL, site URL, root URL, relative URL, webroot, public URL, trusted proxy, forwarded headers o termini simili. La terminologia varia da prodotto a prodotto e il supporto è specifico per ciascun prodotto.
Un proxy può rimuovere un prefisso pubblico prima di inoltrare una richiesta. Ad esempio, un proxy può accettare /app e inoltrare la richiesta a un backend in ascolto su /. Il middleware StripPrefix di Traefik esegue questo tipo di rimozione del prefisso e inserisce il prefisso rimosso in X-Forwarded-Prefix. Tuttavia, rimuovere un percorso nel proxy non rende automaticamente l'applicazione consapevole che il suo indirizzo pubblico include quel percorso.
L'applicazione deve comunque generare link pubblici, URL delle risorse, reindirizzamenti, destinazioni dei moduli e URL di callback con il prefisso corretto. La documentazione ufficiale può inoltre rivelare delle limitazioni. GitLab, ad esempio, documenta l'installazione con URL relativi come alternativa, ma in circostanze normali raccomanda un dominio o sottodominio proprio e descrive alcune limitazioni. È un utile promemoria per non generalizzare il comportamento di un prodotto agli altri.
- Leggi la documentazione di distribuzione del fornitore prima di scegliere una sottodirectory.
- Conferma che l'applicazione supporti un URL relativo o un webroot, non soltanto un reverse proxy generico.
- Identifica gli header proxy richiesti e le impostazioni del proxy attendibile.
- Registra l'esatto URL esterno canonico nella documentazione di distribuzione.
- Esegui un test in staging usando l'URL pubblico previsto, non solo un indirizzo diretto del container o interno.
Autenticazione e integrazioni: URL di callback, link email, contenuti incorporati e webhook
L'autenticazione rende spesso visibile una migrazione dell'URL. Le integrazioni OAuth possono richiedere la registrazione degli endpoint di reindirizzamento presso il server di autorizzazione. Quando viene registrato un URI di reindirizzamento completo, OAuth 2.0 richiede il confronto come stringa semplice dell'URI richiesto. Il passaggio da https://example.com/app/callback a https://app.example.com/callback può quindi richiedere una modifica di configurazione presso il provider di identità, anche se l'applicazione stessa funziona.
Crea un inventario di ogni servizio esterno che memorizza o visualizza l'URL pubblico. Questo include comunemente impostazioni di single sign-on, email di reimpostazione password e invito, pagine incorporate esternamente, configurazione dei client API, client mobili o desktop e mittenti di webhook. Un valore precedente potrebbe non essere notato finché un utente non segue un raro flusso email o un'integrazione in background non tenta una consegna.
I webhook meritano una fase di convalida separata poiché il loro mittente è un client HTTP esterno. L'URL del payload configurato deve essere aggiornato quando necessario e la consegna deve essere testata dopo l'attivazione del nuovo indirizzo. Per i servizi che convalidano i certificati TLS, conferma che l'endpoint esponga il certificato valido previsto e sia raggiungibile pubblicamente sul percorso richiesto.
- Elenca ogni URI di reindirizzamento OAuth o SSO prima del lancio o della migrazione.
- Invia inviti di prova reali, richieste di reimpostazione password ed email di notifica a una casella di posta controllata.
- Testa i contenuti incorporati dal sito o prodotto che li ospiterà effettivamente.
- Fai l'inventario dei mittenti di webhook in entrata, aggiorna la configurazione dei loro endpoint e attiva una consegna di test.
- Controlla i client API e gli strumenti di automazione per individuare URL di base codificati in modo statico.
DNS, certificati TLS e instradamento per ciascun modello
La scelta di un hostname crea lavoro relativo a DNS e certificati. Le autorità di certificazione convalidano il controllo dei nomi di dominio inclusi in un certificato, pertanto l'hostname selezionato deve risolvere e instradare in modo da supportare il metodo di convalida scelto. La convalida HTTP-01 di Let's Encrypt recupera una challenge sotto /.well-known/acme-challenge/ sulla porta 80. DNS e instradamento pubblico fanno quindi parte della preparazione al lancio dell'applicazione, non sono un'attività da rimandare a dopo la configurazione dell'applicazione.
Un sottodominio necessita normalmente di un record DNS per quell'hostname e di un certificato che lo copra. Un dominio separato richiede lo stesso lavoro per un nome di dominio differente. Una sottodirectory non aggiunge un hostname, ma richiede regole precise di instradamento per percorso e coesistenza con percorsi, reindirizzamenti e gestione delle challenge del sito principale.
I certificati wildcard sono una scelta progettuale distinta. Let's Encrypt documenta che HTTP-01 non può emettere certificati wildcard; l'emissione wildcard richiede la convalida DNS-01. Non scegliere un approccio wildcard soltanto per evitare di pianificare singoli hostname, a meno che tu non possa gestire in sicurezza il processo di convalida DNS richiesto.
- Conferma la proprietà del DNS e chi può modificare i record pertinenti.
- Verifica che l'hostname previsto risolva prima dell'emissione del certificato e del lancio pubblico.
- Controlla che la porta 80 e il percorso della challenge ACME siano raggiungibili quando usi la convalida HTTP-01.
- Definisci la precedenza di instradamento affinché sito principale, percorsi dell'applicazione e percorsi delle challenge non entrino in conflitto.
- Dove viene usato Docker, esponi solo le porte che richiedono accesso esterno; un reverse proxy può raggiungere i servizi attraverso la rete host o Docker senza pubblicare ogni porta del container.
Dati e governance: decidi chi possiede il confine
La struttura del dominio deve riflettere la proprietà operativa oltre all'esperienza utente. Considera chi controlla la registrazione del dominio, i record DNS, le modifiche relative ai certificati, l'amministrazione dell'applicazione, i contatti di fatturazione e l'accesso di emergenza. Un URL tecnicamente comodo può diventare un rischio operativo se dipende da un account personale o dall'accesso DNS di un team non correlato.
Un dominio separato può essere utile quando un cliente, un'azienda acquisita, un'unità regolamentata o un prodotto autonomo necessita di un confine pubblico e amministrativo più chiaro. Un sottodominio dedicato può fornire un confine pratico all'interno di un dominio padre gestito centralmente. Una sottodirectory è spesso da riservare ai casi in cui un hostname condiviso è realmente richiesto e il supporto dell'applicazione è stato verificato.
Nessuna di queste scelte risolve automaticamente la governance degli accessi. Definisci chi amministra l'applicazione, chi detiene l'accesso DNS, chi approva le modifiche alle integrazioni, dove viene governata la gestione dei backup e come vengono trasferiti gli accessi in caso di cambiamento del personale o dei fornitori.
- Documenta il proprietario legale e operativo di ogni dominio e zona DNS.
- Evita il controllo da parte di una sola persona degli accessi a registrar, DNS e amministrazione dell'applicazione.
- Assegna responsabili per impostazioni del provider di identità, configurazioni webhook e procedure di ripristino.
- Usa un dominio separato quando un ciclo di vita indipendente o un confine di proprietà è un requisito prioritario.
Pianifica la migrazione: i reindirizzamenti aiutano, ma non aggiornano ogni dipendenza
Un sottodominio è spesso più facile da modificare rispetto a una distribuzione in sottodirectory perché l'applicazione può comunemente rimanere radicata su /. Ciò non significa che le modifiche all'hostname siano prive di conseguenze. Il nuovo hostname cambia l'origine del browser, può richiedere un nuovo certificato e record DNS e può imporre aggiornamenti a callback registrati, destinazioni webhook, client API, modelli email e allowlist.
Un passaggio da sottodirectory a sottodominio può semplificare la configurazione futura del proxy, ma cambia comunque l'URL canonico. La guida alla migrazione documentata da GitLab è un utile esempio concreto: la modifica dell'URL cambia gli URL dei repository remoti, che gli utenti potrebbero dover aggiornare manualmente. I reindirizzamenti possono preservare i link legacy accessibili dal browser, ma non riscrivono la configurazione remota detenuta da ogni utente o sistema di terze parti.
Testa i reindirizzamenti in base ai tipi effettivi di richieste ricevute dall'applicazione. I reindirizzamenti HTTP sono comportamento del client, non una garanzia che tutti i client rispondano allo stesso modo. La semantica HTTP distingue anche il comportamento dei metodi: 301 e 302 possono far diventare una POST una GET, mentre 307 e 308 preservano il metodo. Non presumere che un reindirizzamento testato nel browser dimostri che un client API o un mittente di webhook si comporterà correttamente.
- Crea un inventario dei vecchi URL prima di modificare l'indirizzo canonico.
- Aggiorna la configurazione dell'applicazione, i provider di identità, i mittenti di webhook, i client API, la documentazione e le comunicazioni rivolte agli utenti.
- Mantieni un piano intenzionale di reindirizzamento per il traffico del browser, includendo una data di ritiro e un approccio di monitoraggio.
- Testa i flussi basati su POST e i client esterni separatamente dalla normale navigazione GET.
- Informa gli utenti quando devono aggiornare manualmente remoti salvati, segnalibri, impostazioni client o allowlist.
Domande frequenti
Per un'applicazione self-hosted è meglio un sottodominio o una sottodirectory?
Un sottodominio dedicato è solitamente l'opzione predefinita più semplice perché l'applicazione può operare da /. Scegli una sottodirectory solo quando hai bisogno di un hostname condiviso e la documentazione ufficiale dell'applicazione, insieme a un test in staging, conferma un supporto affidabile per URL relativi o webroot.
Un reverse proxy può far funzionare qualsiasi applicazione in una sottodirectory?
No. Un reverse proxy può rimuovere un prefisso di percorso pubblico prima di inoltrare le richieste, ma l'applicazione deve comunque generare risorse, reindirizzamenti, link e integrazioni usando il prefisso pubblico. Il solo instradamento proxy non fornisce il supporto a livello applicativo per l'URL di base.
I cookie rendono insicure le sottodirectory?
Cookie Path limita quando un browser invia un cookie, ma non costituisce un confine di sicurezza. Le applicazioni sotto un unico hostname richiedono una configurazione deliberata dei cookie e non dovrebbero fare affidamento sulla separazione per percorso come protezione tra servizi amministrati in modo indipendente.
Cosa deve cambiare quando si sposta un'applicazione a un nuovo hostname?
Esamina l'URL canonico dell'applicazione, DNS, certificato TLS, URI di reindirizzamento OAuth o SSO, link per reimpostazione password e invito, URL dei payload webhook, client API, contenuti incorporati, documentazione, allowlist e client configurati dagli utenti. I reindirizzamenti possono aiutare con i link del browser, ma non aggiornano automaticamente le configurazioni esterne.
Come può aiutare Airbip con l'instradamento URL per una distribuzione di applicazioni gestita?
Airbip distribuisce le applicazioni del catalogo come carichi di lavoro Docker sui server cloud Airbip e automatizza instradamento e certificati TLS tramite Traefik e Let's Encrypt. Include inoltre controlli DNS, gestione del ciclo di vita dei servizi e backup giornalieri, settimanali e mensili configurabili. I clienti possono usare un sottodominio Airbip o un dominio personalizzato compatibile. Il cliente deve comunque scegliere l'URL appropriato per l'applicazione, verificare il supporto a livello applicativo per l'URL di base, configurare identità e integrazioni e prendere le pertinenti decisioni su dati, accessi e governance.
Fonti e approfondimenti
- Traefik StripPrefix middleware documentation — Traefik Labs
- GitLab: Install under a relative URL — GitLab
- GitLab: Migrate from a relative URL to a subdomain — GitLab
- Nextcloud Server Administration Manual — Nextcloud GmbH
- RFC 6265: HTTP State Management Mechanism — IETF
- RFC 6749: The OAuth 2.0 Authorization Framework — IETF
- RFC 6454: The Web Origin Concept — IETF
- RFC 9110: HTTP Semantics — IETF
- Challenge Types — Let’s Encrypt / Internet Security Research Group
- Docker networking overview — Docker