Dominio personalizzato e TLS automatico su Dockup

Una configurazione con dominio personalizzato e TLS automatico comprende tre livelli distinti: il servizio Dockup deve essere operativo, il DNS deve indirizzare l'hostname verso la piattaforma e l'hostname deve superare la verifica prima che sia possibile emettere un certificato. Gestire questi livelli separatamente rende prevedibile il passaggio e impedisce che gli errori DNS vengano scambiati per problemi dell'applicazione.

Dockup assegna inoltre a ogni servizio un indirizzo *.dockup.tech. Mantieni questo indirizzo disponibile durante la propagazione DNS, così puoi testare l'applicazione indipendentemente dall'hostname personalizzato.

Cosa deve essere pronto prima di aggiungere un dominio personalizzato Dockup?

Inizia con un servizio già in esecuzione che superi il relativo readiness gate:

dockup status production/web --json
dockup health production/web --json

Apri o testa l'URL *.dockup.tech esistente. Se l'applicazione non funziona su quell'URL, aggiungere un dominio non risolverà il problema. Esamina prima i runtime logs.

Raccogli le seguenti informazioni:

Elemento	Esempio	Perché è importante
Target esatto	production/web	Impedisce di associare il dominio al servizio sbagliato
Hostname	app.example.com	Il nome DNS che visiteranno gli utenti
Accesso DNS	Registrar o provider DNS	Necessario per creare il record
TTL attuale	300 secondi	Controlla la velocità di propagazione e rollback
URL canonico dell'applicazione	https://app.example.com	Può influire su redirect e cookie
Health route	/health	Conferma lo stato del servizio prima del passaggio

Riduci in anticipo il TTL DNS esistente quando sostituisci un provider in produzione. Non eliminare il vecchio record finché non sono noti il target Dockup, la configurazione dell'applicazione e il piano di rollback.

Esamina il comportamento dell'applicazione che dipende dall'host. Potrebbe essere necessario aggiornare callback di autenticazione, allowlist CORS, domini dei cookie, URL di redirect OAuth, destinazioni dei webhook e link assoluti generati con il nuovo hostname HTTPS.

Come si aggiunge e si verifica il dominio?

Per prima cosa, elenca i domini attuali:

dockup domain list production/web --json

Aggiungi l'hostname:

dockup domain add app.example.com production/web --json

La risposta fornisce il target DNS da configurare. Crea il record CNAME indicato presso il provider DNS. Non inventare un indirizzo IP e non copiare un valore da un altro servizio: usa il target restituito per questo dominio.

Dopo la propagazione DNS, esegui la verifica usando l'ID del dominio restituito:

dockup domain verify <domainId> production/web --json

La verifica conferma che il record DNS pubblico viene risolto come richiesto. Un errore indica generalmente una di queste quattro condizioni:

1. Il nome del record è errato.
2. Il target CNAME è errato.
3. Esiste ancora un vecchio record A, AAAA o CNAME in conflitto.
4. Le cache dei resolver non hanno ancora recepito il nuovo valore.

Controlla il DNS autorevole invece di rimuovere e ricreare ripetutamente il dominio. La propagazione è un processo di cache distribuito, non un processo di build di Dockup.

Come viene emesso e gestito il certificato HTTPS?

Dopo aver completato la verifica, richiedi il certificato:

dockup domain ssl <domainId> production/web --json

Dockup gestisce l'emissione del certificato per l'hostname verificato e serve il dominio personalizzato tramite HTTPS. La piattaforma gestisce l'intero ciclo di vita del TLS, quindi il container dell'applicazione non deve archiviare file di certificato né eseguire un processo di rinnovo.

Convalida il risultato dall'esterno della piattaforma:

curl -I https://app.example.com

Verifica che:

• Il certificato corrisponda all'hostname.
• La risposta venga servita tramite HTTPS.
• I redirect non creino loop.
• L'applicazione restituisca lo status previsto.
• I flussi di autenticazione e callback usino la nuova origin.
• Gli asset statici vengano caricati senza errori di mixed content.

L'emissione del certificato può fallire anche quando l'applicazione è perfettamente operativa. Mantieni separati i diagnostici DNS e quelli del servizio. Usa domain verify per la proprietà DNS e i log del servizio per il comportamento dell'applicazione.

L'articolo sui deployment senza downtime spiega il readiness gate indipendente del rilascio.

Come si trasferisce il traffico senza interruzioni?

Un passaggio sicuro mantiene disponibile il percorso precedente finché il nuovo hostname non è stato verificato.

1. Esegui il deploy e verifica il servizio Dockup tramite il relativo URL della piattaforma.
2. Aggiungi il dominio personalizzato in Dockup.
3. Crea il record DNS.
4. Verifica il DNS.
5. Emetti il certificato TLS.
6. Testa direttamente HTTPS.
7. Aggiorna callback, URL canonici e monitoraggio.
8. Invia una piccola parte del traffico operativo, se la configurazione DNS lo consente.
9. Osserva i log e l'uptime.
10. Dismetti il vecchio provider solo dopo che il nuovo percorso è stabile.

I controlli di uptime di Dockup vengono eseguiti ogni minuto e riportano statistiche sui tempi di risposta, incluso il p95:

dockup uptime production/web --hours 24 --json

Mantieni un monitoraggio esterno indipendente per i domini critici. Un probe della piattaforma conferma la raggiungibilità pubblica, mentre un monitor esterno verifica il percorso dell'utente da un altro sistema.

Se il dominio personalizzato sostituisce un host attualmente in produzione, conserva un record di rollback: valore DNS precedente, TTL precedente, stato del vecchio provider e condizione che farebbe scattare il ripristino.

Come funzionano i domini per porte aggiuntive?

Un servizio può esporre una seconda porta HTTP per un'interfaccia di amministrazione, un endpoint di metriche o un altro processo web. Dockup può creare un dominio aggiuntivo della piattaforma senza DNS personalizzato:

dockup port list production/web --json
dockup port add 8080 production/web --name admin --json

Il dominio restituito instrada il traffico verso la porta del container selezionata. Questo è separato dal dominio personalizzato principale.

Non esporre una porta solo perché un processo è in ascolto. Verifica se l'endpoint dispone di autenticazione, se contiene dati di produzione e se debba essere pubblico. Un'interfaccia di amministrazione solo interna non dovrebbe diventare accessibile da Internet per comodità.

Rimuovi un dominio per una porta non più utilizzato tramite la sola interfaccia dei domini supportata, dopo aver verificato che nessun monitor, callback o flusso operativo lo utilizzi ancora. Le modifiche ai domini delle porte sono mutazioni e compaiono nell'audit log.

Come si risolvono gli errori DNS, TLS e dell'applicazione?

Procedi con una diagnosi a livelli:

Sintomo	Primo controllo	Comando Dockup
Il dominio non viene risolto	Record DNS e propagazione	domain verify
Il certificato non viene emesso	Stato della verifica del dominio	domain list, domain ssl
HTTPS funziona ma l'app restituisce errori	Runtime logs	logs --json
Redirect loop	Impostazioni proxy/host dell'applicazione	env list, runtime logs
L'URL della piattaforma funziona, ma l'host personalizzato no	Livello DNS/TLS	Comandi del dominio
Entrambi gli URL non funzionano	Deployment e runtime	status, build/runtime logs
La porta secondaria non funziona	Mapping del dominio della porta e processo	port list, runtime logs

Esamina l'output del servizio senza confonderlo con le conclusioni sul DNS:

dockup logs production/web --json
dockup status production/web --json

Se una modifica recente all'ambiente ha aggiunto l'URL canonico, ricorda che è necessario un nuovo deploy:

dockup env set APP_URL=https://app.example.com \
  -s production/web \
  --json

dockup deploy production/web --wait --json

La guida alle variabili d'ambiente e ai secret descrive questo ciclo di vita.

Rimozione del dominio e rollback

La rimozione dell'associazione Dockup è distruttiva per il route, quindi sposta o rimuovi prima il record DNS pubblico e conferma la sostituzione prevista. Poi rimuovi l'associazione tramite l'interfaccia dei domini supportata usando l'ID esatto del dominio.

Non rimuovere il dominio durante un problema temporaneo del certificato o della propagazione, a meno che il piano di ripristino non lo richieda. Lasciare la configurazione in essere consente alla verifica di riuscire quando le cache si aggiornano.

Esamina le mutazioni con:

dockup audit --search domains --json

L'audit trail dovrebbe indicare chi ha aggiunto, verificato, protetto o rimosso l'hostname.

Checklist per il passaggio in produzione

Un passaggio completo con dominio personalizzato e TLS automatico include il target del servizio, l'hostname, l'ID del dominio, il tipo e il target del record DNS, il risultato della verifica, il risultato del certificato, le modifiche ai callback dell'applicazione, l'URL di monitoraggio e il valore DNS per il rollback.

Non archiviare la chiave privata del certificato nel repository o nel container. Il confine del TLS gestito da Dockup esiste proprio per consentire al team dell'applicazione di gestire l'hostname senza distribuire materiale del certificato.

Per tutti i flag disponibili, consulta il riferimento della Dockup CLI. Per il deployment iniziale prima delle attività sul dominio, segui Dal repository Git alla produzione.

Pianificare le scelte tra apex e sottodominio

Un sottodominio come app.example.com è generalmente l'hostname più semplice per un'applicazione, perché i provider DNS possono rappresentarlo con un CNAME. Un apex come example.com può richiedere funzionalità di flattening o alias specifiche del provider. Segui il target DNS restituito da Dockup e le funzionalità del provider DNS autorevole.

Scegli un host canonico e reindirizza le alternative a livello applicativo o di routing. Servire sia www sia l'apex senza una policy canonica può suddividere cookie, dati analytics, voci di cache e indicizzazione nei motori di ricerca.

Verificare le ipotesi sul rinnovo del certificato

Il TLS gestito elimina la necessità di eseguire un client di rinnovo all'interno del container, ma l'hostname deve continuare a essere risolto correttamente. Una futura migrazione DNS, una modifica al proxy o un record eliminato possono interrompere la validazione.

Includi lo stato del dominio nelle revisioni periodiche:

dockup domain list production/web --json
dockup uptime production/web --hours 24 --json

La runbook sul dominio personalizzato e TLS automatico dovrebbe indicare il responsabile DNS, il contatto per i rinnovi e la data dell'ultimo controllo esterno del certificato. In questo modo non dovrai scoprire chi è il responsabile solo quando si verifica un incidente relativo al certificato.

Proteggere gli hostname non di produzione

Gli hostname di staging e preview possono esporre funzionalità non concluse e dati con struttura simile a quelli di produzione. Usa l'autenticazione dell'applicazione quando necessario, definisci una policy di indicizzazione a livello applicativo e limita la diffusione degli URL non di produzione.

Le direttive per i motori di ricerca non sono un controllo degli accessi. Un ambiente protetto richiede comunque autenticazione e una gestione appropriata dei dati.

Ricontrollare dopo la propagazione

Ripeti i test HTTPS esterni e i test dei callback dopo che è trascorso interamente il TTL DNS originale.

Inizia con un deployment verificabile

Collega prima un hostname non critico, mantieni l'URL della piattaforma durante la propagazione e registra l'esatto valore DNS necessario per il rollback.

Inizia gratis su app.dockup.ai. Il piano Free costa 0 $ al mese, include un credito iniziale di 10 $ e supporta un workspace, tre database e tre deployment.

FAQ

Quale record DNS richiede un dominio personalizzato Dockup?

Esegui dockup domain add e crea il record DNS mostrato nella risposta. Usa il target restituito invece di copiare un valore da un altro servizio.

Quando può Dockup emettere il TLS per un dominio personalizzato?

Dopo che il record DNS dell'hostname ha superato la verifica del dominio Dockup, richiedi l'emissione del certificato con il comando documentato domain ssl.

Il mio container deve archiviare i certificati TLS?

No. Dockup gestisce il TLS per il dominio personalizzato verificato, quindi il container dell'applicazione non ha bisogno di file di certificato né di un processo di rinnovo.

Dockup può esporre una porta aggiuntiva del container?

Sì. I comandi per le porte possono creare un dominio separato generato automaticamente per una porta pubblica aggiuntiva senza richiedere DNS personalizzato.

Cosa devo controllare quando l'URL della piattaforma funziona ma il dominio personalizzato no?

Concentrati sui record DNS, sulla propagazione, sulla verifica del dominio e sullo stato del certificato. Se l'URL della piattaforma è operativo, è probabile che il livello applicativo funzioni.