Ospitare Next.js sul tuo server con pubblicazione a ogni git push

Il modo rapido per ospitare Next.js sul tuo server è installare un pannello di pubblicazione come Coolify e collegare il tuo repository GitHub. Dopo, ogni git push compila l'app e mette online la nuova versione su HTTPS. Secondo la documentazione di Next.js, tutte le funzionalità funzionano quando pubblichi con un server Node.js o un container Docker, quindi non sei legato a nessuna piattaforma particolare.

Quali funzionalità funzionano sul tuo server?

La tabella nella documentazione ufficiale è breve: un server Node.js e Docker supportano ogni funzionalità, mentre l'esportazione statica è limitata. Su un singolo server, in pratica significa questo:

• I server component, le route API e le risposte in streaming funzionano con next start.
• next/image non richiede configurazioni extra e le immagini vengono elaborate sul server.
• La cache e la rigenerazione statica incrementale (ISR) funzionano da sole su un solo server con un disco persistente. Se esegui più copie, devi condividere la cache tra loro.
• La raccomandazione ufficiale è mettere davanti un reverse proxy invece di esporre direttamente Next.js. Coolify include Traefik a questo scopo, e Traefik ottiene anche il certificato.

Quanto deve essere potente il server?

È la compilazione a decidere quanta memoria ti serve, non l'app in esecuzione. next build ha un picco, e l'app ne richiede molta meno una volta avviata. Anche Coolify stesso usa memoria. Questi sono i valori che abbiamo misurato su server reali:

Il piccolo progetto era l'app Next.js di esempio di Coolify. Quello più grande era un'app di chat con IA scritta con Next.js 16 e circa 85 pacchetti, e con 2 GB ha finito la memoria durante il controllo TypeScript. Il server aveva 2 GB di swap e le cifre mostrano il punto più alto. L'uso del disco dopo la prima compilazione era di 13-18 GB. Sono misurazioni nostre e il tuo progetto sarà diverso. Se una compilazione fallisce per mancanza di memoria, ingrandisci prima, e riduci di nuovo più tardi se puoi.

Passo dopo passo

1. Collega il repository

Accedi a Coolify, apri il tuo progetto nella pagina Projects e premi New resource. Per un repository pubblico scegli Public Git Repository, inserisci l'indirizzo e premi Check repository.

2. Aggiungi una chiave se il repository è privato

Nel menu a sinistra vai su Private Keys sotto Keys & Tokens e crea una chiave con Generate ED25519. Aggiungi la chiave pubblica in Deploy keys nella pagina Settings del repository su GitHub. Poi usa New resource, scegli Private Git Repository (with Deploy Key) e inserisci [email protected]:user/project.git. Lascia Build pack su Railpack, che riconosce Next.js, e la porta resta 3000. Coolify segnala Railpack come beta, quindi se ti dà problemi scegli il tuo Dockerfile.

3. Inserisci le variabili d'ambiente

Nella pagina Environment Variables passa a Developer view e incolla il contenuto del tuo file .env. Qui conta un dettaglio: le variabili il cui nome inizia con NEXT_PUBLIC_ vengono scritte nel codice durante la compilazione. Quando ne cambi una, premi Redeploy: il pannello vede che un'impostazione di compilazione è cambiata e compila di nuovo. Non dare mai quel prefisso a una chiave che il browser non deve vedere.

4. Collega il tuo dominio

Crea un record A presso il provider del tuo dominio che punti all'indirizzo IP del server. In Coolify vai alla pagina Domains, premi Add domain, scegli https come protocollo, inserisci il tuo dominio, salva e pubblica di nuovo. Il certificato viene richiesto e rinnovato automaticamente. Le porte 80 e 443 devono essere aperte.

5. Pubblica

Premi Deploy. La pagina Deployments mostra in diretta il log della compilazione. Quando la compilazione finisce, il vecchio container continua a servire finché il nuovo non è pronto.

Come diventa una pubblicazione un git push?

A ogni push GitHub invia al pannello una richiesta firmata. Il pannello verifica la firma e ricompila l'app per quel branch, mentre una richiesta con firma non valida viene rifiutata. Ecco come lo imposti:

1. Nella pagina Webhooks dell'app, copia il Webhook URL dalla sezione GitHub, inserisci in Webhook secret un valore casuale di almeno 16 caratteri e salva.
2. Su GitHub apri Settings del repository, vai su Webhooks e premi Add webhook.
3. Metti l'indirizzo in Payload URL e lo stesso valore in Secret. Imposta Content type su application/json e lascia il push come unico evento.

Per provare:

git commit --allow-empty -m "deploy test"

git push

La nuova compilazione compare nella pagina Deployments. Sul piccolo progetto di esempio, un nuovo commit è andato online in 41 secondi grazie alla cache di compilazione. GitHub deve poter raggiungere l'indirizzo del pannello e, dato che il pannello è installato con un indirizzo HTTPS pubblico, non serve altro.

Errori comuni

Con l'opzione Next.js di Seturack, Coolify arriva già installato: il server locale è convalidato, la procedura guidata di benvenuto è già superata e il pannello si apre su HTTPS. L'indirizzo e la password compaiono nel tuo pannello e tu parti collegando GitHub. Hai l'accesso root e, se preferisci, puoi gestire tutto dal pannello. I backup giornalieri sono compresi nel prezzo e il traffico è illimitato. Imposti la dimensione con i cursori nella pagina Next.js VPS.

Già pronto su Seturack: Next.js, Coolify.