Cambiare il dominio di un'applicazione self-hosted: checklist delle dipendenze prima della migrazione

Perché un cambio di dominio è una modifica dell'applicazione, non solo del DNS

Per cambiare in sicurezza il dominio di un'applicazione self-hosted, considera l'URL pubblico come configurazione dell'applicazione anziché come un semplice dettaglio di instradamento. Il DNS determina dove viene risolto un hostname, mentre un reverse proxy determina quale servizio riceve una richiesta. Nessuno dei due aggiorna automaticamente gli URL generati dall'applicazione, gli indirizzi di callback registrati presso servizi esterni o i link già utilizzati dalle persone.

Il dominio può essere presente in variabili d'ambiente, impostazioni di amministrazione dell'applicazione, record del database, configurazioni del provider di identità, sottoscrizioni webhook, configurazioni dei client API e modelli email. Può anche essere implicito nei controlli di sicurezza del browser: un cambio di host crea una diversa origine web, poiché un'origine è definita da schema, host e porta.[1] Di conseguenza, un'integrazione basata su browser che funzionava con il vecchio hostname può richiedere un aggiornamento esplicito delle origini consentite.

Separa il lavoro in due filoni. I responsabili dell'infrastruttura gestiscono record DNS, convalida TLS, instradamento del reverse proxy e reindirizzamenti dal vecchio dominio. I responsabili dell'applicazione individuano impostazioni dell'URL canonico, servizi collegati, link rivolti agli utenti e flussi di lavoro aziendali. Entrambi i filoni devono essere completati prima di dismettere il vecchio dominio.

• Non presumere che una risoluzione DNS riuscita dimostri che la migrazione sia completa.
• Non presumere che una regola hostname del reverse proxy aggiorni l'URL di base interno dell'applicazione.
• Non rimuovere il vecchio hostname finché non sono stati testati reindirizzamenti, integrazioni e percorsi utente.
• Assegna responsabili nominativi per infrastruttura, configurazione dell'applicazione, integrazioni di identità e test di accettazione.

Mappa l'URL canonico e ogni hostname in uso

Inizia con un inventario degli hostname. L'obiettivo è individuare ogni indirizzo che l'applicazione accetta, pubblica o da cui dipende. Includi l'attuale URL pubblico canonico, il nuovo URL canonico previsto, eventuali alternative con o senza www, hostname amministrativi, hostname API, hostname per upload o asset e sottodomini usati da servizi incorporati.

Per ciascun hostname, registra scopo, destinazione DNS attuale, destinazione DNS prevista, requisito del certificato TLS, route del reverse proxy, team responsabile e decisione di dismissione. Una route wildcard o un certificato wildcard non devono essere considerati la prova che ogni hostname funzioni. Per esempio, un wildcard a singolo livello come *.example.com non copre il dominio apex example.com né un nome multilivello come api.eu.example.com.[2]

Poi determina quale URL l'applicazione considera canonico. È l'indirizzo che usa per generare link assoluti, reindirizzamenti, URL API, URL di asset o notifiche. Se l'URL canonico resta old.example.com mentre gli utenti accedono a new.example.com, l'interfaccia può apparire funzionante finché un'email, un flusso di accesso o una risposta API non rimanda un utente al vecchio dominio.

• Elenca separatamente gli hostname di produzione, staging e amministrativi.
• Registra sia lo schema sia la porta quando sono pertinenti: http e https non sono origini intercambiabili.
• Cerca il vecchio hostname nelle impostazioni dell'applicazione, nei file di deployment, nei secret store e nella documentazione.
• Controlla preferiti del browser, link nella wiki interna, documentazione pubblica e link incorporati che potrebbero richiedere un responsabile e una data di aggiornamento.
• Decidi se ogni vecchio hostname verrà reindirizzato, resterà temporaneamente supportato o verrà dismesso.

Individua le dipendenze che comunemente si interrompono dopo un cambio di hostname

Le impostazioni di identità e integrazione sono frequenti punti di errore perché associano intenzionalmente un client o un endpoint a un indirizzo preciso. Gli URI di reindirizzamento OAuth meritano attenzione fin da subito: le attuali linee guida di sicurezza OAuth richiedono ai server di autorizzazione di usare una corrispondenza esatta delle stringhe per gli URI di reindirizzamento preregistrati, salvo un caso localhost limitato per le app native.[3] Aggiungere un nuovo dominio presso il provider di identità è quindi un'attività necessaria prima del cutover, non una comodità successiva alla modifica.

Esamina sia le connessioni in ingresso sia quelle in uscita. Le dipendenze in ingresso includono callback del provider di identità, callback di pagamenti o moduli e webhook di terze parti diretti all'applicazione. Le dipendenze in uscita includono webhook inviati dall'applicazione a un altro servizio, client API che chiamano il vecchio hostname e widget o script incorporati che caricano risorse dal vecchio host.

CORS è un altro confine comune. Se un'API o un proxy usa un elenco esplicito di origini consentite, aggiungi la nuova origine composta da schema e host prima del cutover.[4] Non ampliare con leggerezza le regole sulle origini solo per far superare un test; conserva il confine di accesso previsto e apporta la modifica giustificata più piccola.

Anche le comunicazioni generate richiedono la stessa verifica. Messaggi per reimpostare la password, inviti, notifiche di commenti, esportazioni, report pianificati e modelli di marketing o transazionali possono includere link assoluti. Esegui i test con una casella email non privilegiata oltre che con un account amministratore, poiché percorsi dei modelli e autorizzazioni possono differire.

• URL di reindirizzamento e logout OAuth e OpenID Connect.
• URL del consumer di asserzioni SAML e riferimenti a entità o metadati, ove utilizzati.
• Destinazioni webhook e allowlist dei mittenti webhook.
• URL di base API in script, client mobili, estensioni del browser e strumenti interni.
• Elenchi di origini CORS consentite, incorporamenti basati su browser e impostazioni iframe.
• Modelli email, reimpostazioni password, inviti, link a calendari e link di notifica.
• URL hard-coded in flussi di automazione, job pianificati e documentazione.

Controlla la configurazione specifica dell'applicazione, inclusa quella che raggiunge effettivamente il container

Ogni applicazione usa nomi diversi per queste impostazioni, ma cerca concetti come URL di base, URL pubblico, URL del sito, URL esterno, URL canonico, host attendibili, host consentiti, origini consentite, modalità proxy e attendibilità degli header inoltrati. Consulta la documentazione del fornitore dell'applicazione per i nomi esatti delle impostazioni e i requisiti di riavvio. Non dedurre che un'impostazione sia facoltativa solo perché l'applicazione si avvia anche senza di essa.

Per i deployment basati su Docker, esamina la configurazione runtime effettiva anziché fare affidamento su un solo file o su un valore ricordato. Docker Compose può fornire configurazione tramite variabili d'ambiente del container e i valori di un file .env possono essere interpolati in un file Compose. La precedenza delle variabili d'ambiente può modificare il valore che raggiunge un container.[5] Quando appropriato per il deployment, docker compose config è utile per confermare la configurazione Compose risolta, soprattutto quando sono coinvolti più file Compose o fonti di variabili.[6]

Ispeziona anche le impostazioni archiviate al di fuori della definizione Compose: pannelli di amministrazione dell'applicazione, configurazioni memorizzate nel database, file di configurazione montati, sistemi di gestione dei segreti e script di avvio. Registra lo stato prima e dopo per ogni valore modificato. Questo registro rende molto più rapidi la revisione tra pari e il rollback.

Se l'applicazione si trova dietro un reverse proxy, conferma le sue aspettative riguardo host e protocollo originali. Un proxy può inoltrare queste informazioni a monte, ma l'attendibilità degli header inoltrati deve essere configurata deliberatamente.[7] Una gestione errata può generare link http, loop di reindirizzamento o una discrepanza tra l'hostname pubblico e quello che l'applicazione ritiene di servire.

• L'URL canonico o esterno corrisponde all'hostname HTTPS pianificato.
• L'elenco degli host attendibili o consentiti include il nuovo hostname e, durante la transizione, quello vecchio se resta servito.
• Le impostazioni relative a origini CORS e CSRF includono solo le origini necessarie.
• Le impostazioni di proxy e protocollo inoltrato corrispondono all'effettiva architettura del proxy.
• Le impostazioni relative a OAuth, SSO, webhook e SMTP vengono controllate sia nell'applicazione sia presso il provider esterno.
• La configurazione del container risolta viene esaminata prima del riavvio o del redeploy.
• È disponibile una copia sicura delle impostazioni precedenti per il rollback.

Pianifica DNS, TLS e reverse proxy senza confonderli con la configurazione dell'applicazione

Le modifiche infrastrutturali devono essere pianificate come una sequenza controllata separata. Crea i nuovi record DNS, assicurati che il reverse proxy disponga di una route che corrisponda al nuovo hostname e verifica che sia selezionato il corretto servizio backend. In Traefik, i router HTTP utilizzano regole di corrispondenza delle richieste, come le regole Host, per collegare le richieste ai servizi.[2] Le regole sovrapposte richiedono ulteriore attenzione: l'ordinamento predefinito delle regole può essere influenzato dalla loro lunghezza, quindi una regola ampia può intercettare traffico se le priorità non sono progettate esplicitamente.[2]

Esegui il provisioning e la convalida di TLS prima di dichiarare pronto il nuovo dominio. L'emissione del certificato richiede la convalida del controllo del dominio. Con la challenge ACME HTTP-01, il token di convalida deve essere raggiungibile sul nuovo hostname in /.well-known/acme-challenge/ sulla porta 80.[8] Controlla firewall, DNS, instradamento del proxy ed eventuali comportamenti di reindirizzamento che potrebbero impedire la convalida.

I clienti Airbip possono usare un sottodominio Airbip o un dominio personalizzato compatibile. Airbip gestisce le istanze delle applicazioni come workload Docker su server cloud Airbip e automatizza routing e certificati TLS tramite Traefik e Let's Encrypt, con controlli DNS inclusi nel servizio. Questo supporto infrastrutturale non sostituisce la verifica da parte del responsabile dell'applicazione di URL di base, registrazioni di identità, webhook, modelli e flussi di lavoro aziendali.

Usa una finestra di modifica DNS che consenta l'osservazione, non un semplice passaggio rapido. Conferma il nuovo hostname da una rete esterna, ispeziona il certificato e prova la route prevista. Mantieni disponibile il vecchio percorso finché i controlli sull'applicazione e sulle integrazioni non forniscono evidenza che sia sicuro dismetterlo.

• Crea e verifica il DNS per ogni nuovo hostname, incluso il nome apex quando necessario.
• Conferma che il nuovo hostname disponga di una route del reverse proxy esplicita e non ambigua.
• Conferma l'emissione TLS e il nome del certificato presentato ai client.
• Controlla i reindirizzamenti HTTPS ed evita di instradare il percorso di convalida ACME lontano dalla risposta alla challenge richiesta.
• Testa il comportamento tra proxy e applicazione per l'host previsto e il protocollo HTTPS.
• Documenta la configurazione DNS e proxy precedente prima di apportare modifiche irreversibili.

Scegli un approccio di cutover: convalida in parallelo, reindirizza deliberatamente e conserva il vecchio dominio per un periodo definito

L'approccio a minor rischio consiste di solito nel predisporre il nuovo hostname prima di renderlo canonico. Instradalo verso l'applicazione, ottieni TLS e completa test controllati mentre il vecchio dominio resta disponibile. La possibilità di servire in sicurezza entrambi gli hostname contemporaneamente dipende dalla convalida degli host dell'applicazione, dal comportamento delle sessioni, dalla generazione dei link e da vincoli di licenza o integrazione. Convalida questi aspetti con la documentazione dell'applicazione e, ove possibile, in un ambiente controllato.

Dopo che il nuovo hostname è stato accettato come canonico, reindirizza i vecchi URL pubblici ai corrispondenti nuovi URL quando è appropriato preservare i percorsi. HTTP 308 è uno stato di reindirizzamento permanente che usa un header Location e conserva il metodo della richiesta.[9] Questa proprietà può essere importante per richieste non GET, ma non è un'istruzione generalizzata per reindirizzare ogni endpoint. Per API, webhook, URL firmati, percorsi di upload e client automatici, determina se un reindirizzamento è supportato e sicuro prima di abilitarlo.

Definisci un periodo esplicito per il dominio legacy anziché lasciare entrambi i domini attivi indefinitamente per errore. Durante questo periodo, monitora gli accessi al vecchio host, correggi i link hard-coded ancora presenti e avvisa utenti interessati o responsabili delle integrazioni. Conservare un dominio comporta implicazioni operative e di governance, quindi la decisione deve essere intenzionale e riesaminata.

• Fase 1: aggiungi il nuovo dominio, instradalo, emetti TLS e testalo senza modificare le impostazioni canoniche dell'applicazione quando l'accesso parallelo è sicuro.
• Fase 2: aggiorna l'URL canonico e le dipendenze dell'applicazione, quindi testa i flussi critici sul nuovo hostname.
• Fase 3: reindirizza il traffico browser appropriato dal vecchio dominio, convalidando separatamente il comportamento di API e webhook.
• Fase 4: osserva l'uso del vecchio dominio, risolvi le dipendenze residue e approva la dismissione in base a criteri definiti.
• Evita di presumere che un reindirizzamento preservi richieste firmate, convalida delle callback o comportamento di client di terze parti.

Esegui uno script di test post-modifica che rifletta il lavoro reale

Un controllo della pagina iniziale è necessario ma insufficiente. Usa uno script di test scritto con risultati attesi, risultati effettivi, timestamp e un tester nominativo. Eseguilo con un account utente ordinario e con un account amministratore e testa da una sessione browser pulita per evitare di fare affidamento su sessioni o autorizzazioni memorizzate nella cache.

Dai priorità ai flussi di lavoro che creano link esterni, attraversano confini di identità o scrivono dati importanti. Raccogli evidenze quali screenshot dell'indirizzo nel browser, link ricevuti via email, record di consegna webhook e log pertinenti dell'applicazione o del proxy. Le evidenze sono più utili di una conferma verbale per decidere se mantenere un reindirizzamento o dismettere il dominio legacy.

Se un test fallisce, classificane la causa prima di modificare la configurazione: risoluzione DNS, certificato, route proxy, URL canonico dell'applicazione, policy di origine del browser, registrazione dell'integrazione esterna o URL hard-coded lato client. Ciò evita una risposta comune: indebolire i controlli di sicurezza o applicare reindirizzamenti ampi per mascherare una lacuna di responsabilità o configurazione.

• Apri il nuovo URL in una sessione browser pulita e conferma HTTPS, hostname previsto e normale accesso all'applicazione.
• Accedi tramite ogni percorso supportato di autenticazione locale, OAuth, SSO o amministratore.
• Completa i flussi di reimpostazione password, invito e verifica account; ispeziona l'hostname nei link email ricevuti.
• Crea contenuti o record che generano link, quindi apri tali link in una nuova sessione.
• Testa upload, download, anteprime e contenuti archiviati esternamente o incorporati, ove applicabile.
• Esegui client API, integrazioni browser e richieste frontend cross-origin che usano il servizio.
• Attiva webhook in ingresso e in uscita e conferma endpoint previsto, gestione della firma e comportamento della risposta.
• Esegui i principali flussi amministrativi, inclusi gestione utenti e modifiche di configurazione appropriate al processo di modellazione dei ruoli dell'applicazione. Presta attenzione a non esporre segreti nelle evidenze di test o nei log durante il processo.

Definisci responsabilità, condizioni di rollback ed evidenze di dismissione prima della finestra di modifica

Una migrazione di dominio è più semplice da governare quando i punti decisionali sono stabiliti prima che cambino record o impostazioni. Nomina un responsabile tecnico della modifica, un responsabile dell'applicazione, un responsabile di identità e integrazioni, un responsabile delle comunicazioni e un approvatore per la dismissione del vecchio dominio. In un team piccolo, una persona può ricoprire più ruoli, ma le responsabilità devono comunque essere esplicite.

Definisci il rollback in termini operativi. Per esempio, il rollback può significare ripristinare il precedente URL canonico, riabilitare la precedente route proxy, ripristinare la precedente destinazione DNS o sospendere un reindirizzamento mentre viene corretta una registrazione di identità esterna. Individua quali modifiche sono rapidamente reversibili e quali richiedono propagazione o un'azione di terze parti. Conserva un registro sicuro dei valori precedenti e dell'ordine in cui devono essere ripristinati.

Infine, richiedi evidenze prima della dismissione. Evidenze adeguate includono test riusciti dei percorsi critici sul nuovo hostname, callback OAuth o SSO confermate, link email verificati, test webhook riusciti, assenza di traffico irrisolto sul vecchio dominio che richieda azioni durante il periodo di osservazione concordato e approvazione da parte dei responsabili delle integrazioni ad alto impatto. La dismissione è una decisione aziendale e di governance oltre che tecnica; dovrebbe tenere conto delle comunicazioni agli utenti, dei preferiti conservati e di eventuali requisiti contrattuali o normativi della tua organizzazione.

Una piattaforma gestita può ridurre il carico operativo relativo a routing, certificati, controlli DNS, gestione del ciclo di vita dei servizi e backup. Non può decidere quali provider di identità, applicazioni client, link o impegni relativi al trattamento dei dati siano importanti per la tua organizzazione. Mantieni questa responsabilità a livello applicativo presso le persone che possiedono il servizio.

• Pubblica un registro della modifica con hostname pianificato, finestra temporale, responsabili, dipendenze e piano di comunicazione a clienti o utenti.
• Registra in modo sicuro la configurazione precedente di DNS, proxy e applicazione.
• Stabilisci trigger di rollback misurabili, come accesso non riuscito, reimpostazione password non funzionante, webhook critico non riuscito o link canonici errati.
• Decidi chi può autorizzare il rollback e come verranno informati gli utenti interessati.
• Definisci i criteri per la dismissione del dominio legacy e un periodo di osservazione.
• Archivia le evidenze di test e l'inventario finale della configurazione dopo il completamento.