Migrare da Heroku

Migra un'app Heroku con il suo database, le config vars e il dominio.

Questa guida ti aiuta a migrare un'app Heroku a Nodion: codice, config vars, Heroku Postgres, Heroku Key-Value Store, job dello Scheduler e dominio personalizzato. Metti in conto una breve pausa delle scritture mentre il database viene copiato. Non esiste uno strumento di importazione per app.json o heroku.yml; ogni passaggio qui sotto richiede pochi clic o comandi.

Corrispondenze tra Heroku e Nodion

1. Crea il progetto e il database

Crea un progetto e, al suo interno, un database PostgreSQL nella regione in cui deve girare l'app (EU Central per Francoforte). L'app e il suo database devono trovarsi nella stessa regione: Nodion non li collega tra regioni diverse. Scegli una versione di Postgres non precedente a quella del tuo database Heroku. Maggiori dettagli in Database.

2. Copia il database

Per prima cosa blocca tutte le scritture. Con la maintenance mode di Heroku i dyno worker e i job dello Scheduler continuano a girare. Porta quindi a zero ogni process type che scrive (non solo worker) e rimuovi i job da Heroku Scheduler per tutta la durata della copia. Secondo Heroku, la maintenance mode non è disponibile per le app Fir; lì porta a zero anche web oppure blocca le scritture direttamente nell'app:

bashheroku maintenance:on --app example-app
heroku ps:scale worker=0 --app example-app   # every process type that writes

Su Fir:

bashheroku ps:scale web=0 worker=0 --app example-app   # Fir: no maintenance mode

Poi crea e scarica un backup. Heroku lo salva come latest.dump nel formato custom di pg_dump (documentazione Heroku). Heroku consiglia PGBackups per database fino a 20 GB; per quelli più grandi, esegui pg_dump direttamente sull'URL restituito da heroku pg:credentials:url (database classic) o heroku data:pg:credentials:url (database Advanced, documentazione Heroku).

bashheroku pg:backups:capture --app example-app
heroku pg:backups:download --app example-app

I database Advanced non supportano PGBackups; per questi, e per i database oltre i 20 GB, fai il dump direttamente nello stesso formato custom, usando l'URL restituito dal comando per le credenziali corrispondente. Secondo Heroku, i database Private e Shield non accettano connessioni esterne (e Shield non ha PGBackups); per questi segui la procedura che Heroku descrive per i Private Spaces.

bashpg_dump -Fc --no-acl --no-owner -f latest.dump \
  "postgres://USER:PASSWORD@HOST:5432/DATABASE?sslmode=require"

In Nodion apri la scheda Overview del database e clicca Enable public access. Aspetta che l'endpoint non mostri più Provisioning, poi copia l'URL di connessione che mostra la dashboard (sempre TLS, sslmode=require). Aggiungi il tuo IP tra le sorgenti consentite, così solo tu puoi connetterti. Poi esegui il restore:

bashpg_restore --verbose --no-owner --no-acl \
  --dbname "postgresql://nodion:PASSWORD@HOST:PORT/DATABASE?sslmode=require" \
  latest.dump

Usa un pg_restore almeno recente quanto il più recente dei due server. Se il restore segnala errori sullo schema heroku_ext, crealo prima: CREATE SCHEMA heroku_ext; (è un consiglio di Heroku stesso). Controlla il numero di righe nella scheda Browse del database, poi disattiva di nuovo l'accesso pubblico; il database continua a funzionare internamente.

Un Valkey vuoto basta solo se la tua app usa Heroku Key-Value Store come cache o come coda che hai prima lasciato svuotare. Se contiene dati che ti servono (per esempio sessioni o chiavi persistenti), spostali prima di spegnere tutto, oppure mantieni la risorsa originale finché non servono più.

3. Crea l'applicazione

Crea un'applicazione dal tuo repository Git con la strategia Buildpacks. I buildpack leggono il tuo Procfile: web è il processo predefinito e le altre righe diventano tipi di processo (Buildpack). Per Node.js, uno script heroku-postbuild viene eseguito dopo la build. Come su Heroku, il processo web riceve la variabile PORT.

Se il Procfile non ha una riga web:, la sua prima riga diventa quella predefinita e gira nel processo web di Nodion. Nodion controlla quel processo via HTTP prima che sia online, perciò un worker senza server HTTP non supera il controllo. Tieni una riga web: per il server HTTP della tua app.

Le righe del Procfile non creano processi. Per una riga worker:, apri Processes, New process, chiamalo worker e lascia vuoto il comando; così esegue il process type con lo stesso nome.

Una riga release: viene eseguita una volta per ogni deploy, prima che parta web. Se fallisce, fallisce anche il deploy e la release precedente continua a servire il traffico. Se su Heroku facevi la build con heroku.yml, usa la strategia Dockerfile: lì non c'è un Procfile, quindi imposta il release command dell'app (Settings, nel riquadro Preview environments, dove il campo compare una volta attivate le anteprime, oppure release_command tramite l'API). Nodion non imposta PORT sulle app Dockerfile; l'app resta in ascolto sulla porta del processo web (altrimenti sulla porta indicata da EXPOSE nell'immagine, altrimenti su 8080).

4. Trasferisci le config vars

Esporta le config vars in formato shell (Heroku CLI):

bashheroku config -s --app example-app > heroku.env

Incolla le righe in Environment, Add many, e importale. Controlla il risultato: i valori con virgolette o backslash possono richiedere una correzione a mano, e i valori su più righe (per esempio chiavi PEM) vanno inseriti tramite CLI o API. Le variabili importate non sono segrete; imposta i secret con nodion env set KEY=value --secret.

Poi elimina DATABASE_URL e REDIS_URL dalle variabili importate: una variabile impostata da te sovrascrive il valore che inietta un database collegato. Usa Attach database per il database Postgres (url come DATABASE_URL) e per Valkey (url come REDIS_URL).

All'interno di Nodion la connessione passa sulla rete privata senza TLS (sslmode=disable). Se il tuo codice forza SSL per il database, come richiede Heroku, disattivalo per questo URL; lo stesso vale per rediss:// verso Valkey.

5. I job dello Scheduler diventano cron job

Aggiungi ogni job di Heroku Scheduler nella scheda Cron dell'app: una pianificazione cron a cinque campi in UTC, lo stesso comando, un timeout fino a 30 minuti. Un'app supporta fino a 8 cron job; se un'esecuzione è ancora in corso, quella successiva viene saltata.

6. Fai il deploy e verifica

Fai il deploy, segui la scheda Logs e apri l'app sul suo hostname Nodion. Se / non risponde rapidamente con un 2xx o un 3xx, imposta un percorso di health check personalizzato in Settings.

7. Sposta il dominio

Aggiungi il dominio nella scheda Domains. Nodion mostra due record: un record TXT _nodion-challenge.your-domain e un CNAME (un ALIAS sull'apex) verso l'hostname predefinito dell'app. Puoi aggiungere il record TXT in anticipo. Il certificato viene emesso appena il CNAME punta a Nodion, quindi metti in conto qualche minuto senza un certificato valido dopo il passaggio, e abbassa prima il TTL.

8. Spegni Heroku

Quando traffico e dati girano su Nodion, elimina l'app Heroku. Secondo Heroku l'operazione non si può annullare, quindi conserva latest.dump.

bashheroku apps:destroy --app example-app

Cosa funziona diversamente

• Non c'è una maintenance mode e non ci sono pipeline con promozione tra app.
• Al posto dei dyno one-off, la scheda Shell apre un terminale in un processo in esecuzione.
• La CLI recupera i log ma non può seguirli; per vederli in tempo reale usa la scheda Logs.
• Gli ambienti di anteprima non richiedono app.json; ognuno riceve un database vuoto.
• Un rollback rifà il deploy di un'immagine precedente con le variabili d'ambiente attuali.

Prossimi passi

Nodion e Heroku a confronto, Prezzi, Applicazioni e Database.