Vai al contenuto principale

​
Introduzione

Per sviluppare e ospitare un'istanza n8n su Square Cloud, è essenziale seguire una sequenza strutturata di configurazioni e prerequisiti. Questa guida tecnica coprirà l’intero processo, dalla configurazione iniziale al deploy in produzione.

​
Prerequisiti

  • Account Square Cloud: Registrati tramite la pagina di registrazione usando la tua email.
  • Piano attivo: Garantisce risorse dedicate e prestazioni ottimizzate per la tua applicazione. Consulta i nostri piani disponibili e scegli quello più adatto alle tue esigenze.
n8n gira con 3 GB di RAM (MEMORY=3072 qui sotto), quindi richiede un piano con almeno 4 GB, come lo Standard: i piani più piccoli non hanno così tanta RAM. Questa guida usa il runtime Node.js.

​
Ottenere il progetto

n8n gira su Node.js, quindi al progetto serve solo un package.json che elenca n8n tra le dipendenze e ha uno script per avviarlo:
package.json
La versione di n8n è fissata di proposito: latest può saltare a una nuova versione major con modifiche incompatibili a ogni reinstallazione. n8n 2.x richiede Node.js 24 o superiore, fornito da VERSION=recommended. Per aggiornare in seguito, controlla la versione più recente con npm view n8n version, leggi le note di rilascio di n8n, cambia la versione nel package.json e carica di nuovo il tuo progetto.
Abbiamo già tutto pronto per il deploy nelle nostre release di n8n-web. Devi solo scaricare il project.zip e caricarlo.

​
Configurare Square Cloud

Crea un file squarecloud.app nella radice del tuo progetto:
squarecloud.app
START=npm run start esegue lo script start del tuo package.json. Quando carichi dalla dashboard, imposta manualmente il runtime su Node.js e usa npm run start come comando di avvio. Il valore di MEMORY segue le regole di dimensionamento della piattaforma: consulta perché esistono i minimi di RAM se vuoi modificarlo.

​
Variabili d’ambiente

Imposta le variabili qui sotto. Puoi inserirle in un file .env nella radice del progetto (n8n lo carica all’avvio) oppure impostarle come variabili d’ambiente dell’applicazione, in Configurazione avanzata del modulo di upload o nella dashboard. Sostituisci my-n8n-subdomain con il tuo SUBDOMAIN.
.env
  • N8N_PORT e N8N_LISTEN_ADDRESS fanno sì che n8n sia in ascolto sulla porta 80 su tutte le interfacce, dove Square Cloud consegna il traffico del tuo sottodominio. n8n non legge la variabile PORT impostata da Square Cloud, quindi N8N_PORT è obbligatoria.
  • N8N_HOST, N8N_PROTOCOL e N8N_WEBHOOK_URL indicano a n8n il suo indirizzo pubblico. Le guide più vecchie chiamano l’ultima WEBHOOK_URL, deprecata in n8n 2.x. Consulta le variabili degli endpoint di n8n per altre opzioni.
Le variabili impostate nella dashboard hanno la precedenza sul file .env.

​
Cosa mettere nello ZIP

  • package.json
  • squarecloud.app
  • .env, se ci tieni le variabili qui sopra
Lascia fuori node_modules/: Square Cloud installa n8n sul server.

​
Deploy e verifica

​
Tramite dashboard

1

Accedi alla pagina di upload

Accedi alla pagina di upload e carica il file zip del tuo progetto.
2

Configura il tuo ambiente

Dopo aver caricato il tuo zip, dovrai configurare il nome, il file principale o il runtime environment e altre impostazioni per il tuo progetto.
Se stai caricando un progetto web, assicurati di selezionare “Web Publication” e di impostare un sottodominio per il tuo progetto.
3

Esegui il deploy del tuo progetto

Infine, clicca sul pulsante “Deploy” per ospitare il tuo progetto su Square Cloud.
Dopo il deploy, puoi monitorare lo stato e i log del tuo progetto dalla dashboard.
Caricamento dell'applicazione su Square Cloud
4

Conferma che la tua app sia online

Il primo deploy richiede di solito meno di un minuto. Nella dashboard, attendi che lo stato della tua applicazione mostri “in esecuzione” e controlla i log per eventuali errori di avvio.
Se hai fatto il deploy di un sito web o di un’API, apri https://<tuo-sottodominio>.squareweb.app nel tuo browser: dovresti vedere la tua applicazione rispondere. Se hai fatto il deploy di un bot, invia un comando per confermare che sia online.
La tua app non si avvia? Consulta la guida alla risoluzione dei problemi per le cause più comuni e le relative soluzioni.

​
Tramite CLI

Per utilizzare questo metodo, il tuo progetto deve avere un file di configurazione chiamato squarecloud.app nella sua radice. Indica a Square Cloud come eseguire la tua applicazione.

Guida al file di configurazione

Scopri come creare il file di configurazione squarecloud.app che definisce l’ambiente della tua applicazione.
1

Installa la CLI

Installa la CLI di Square Cloud. Se ce l’hai già, esegui lo stesso comando per aggiornarla:
2

Accedi

Esegui il comando qui sotto. Apre il tuo browser: approva l’accesso lì e la CLI è pronta. Non c’è nessuna chiave API da copiare. Per script e CI, consulta Autenticazione della CLI.
3

Carica il tuo progetto

Dalla cartella del tuo progetto, esegui il comando qui sotto. La CLI comprime la cartella corrente, escludendo ciò che elenca squarecloud.ignore, e la carica:
Per caricare uno zip che hai creato tu, passalo con --file:
4

Conferma che la tua app sia online

Il primo deploy richiede di solito meno di un minuto. Controlla lo stato e i log della tua applicazione direttamente dal terminale:
Se hai fatto il deploy di un sito web o di un’API, apri https://<tuo-sottodominio>.squareweb.app nel tuo browser: dovresti vedere la tua applicazione rispondere. Se hai fatto il deploy di un bot, invia un comando per confermare che sia online.
La tua app non si avvia? Consulta la guida alla risoluzione dei problemi per le cause più comuni e le relative soluzioni.

​
Primo accesso

Subito dopo il deploy, apri https://my-n8n-subdomain.squareweb.app e crea l’account owner. Chi apre la pagina per primo diventa il proprietario dell’istanza, quindi fallo prima di condividere l’URL con chiunque.

​
Errori comuni

​
Dominio personalizzato

Per utilizzare un dominio personalizzato (ad esempio, mysite.com) invece dell’URL predefinito mysite.squareweb.app, hai bisogno del piano Standard o superiore. L’URL predefinito deriva dal campo SUBDOMAIN nel file di configurazione. Per collegare il tuo dominio, segui come configurare il tuo dominio.

​
Requisiti minimi di RAM

Minimo: 512MB di RAM per siti web e API, sufficienti per una build statica sul runtime statico. Per le app che generano le pagine su un server (Next.js, Nuxt, Angular SSR e simili), consigliamo almeno 1GB di RAM. Per applicazioni più grandi, alloca più RAM per evitare che l’applicazione esaurisca la memoria e si arresti in modo anomalo.

​
Impossibile trovare questo sito.

Verifica che il sottodominio/dominio corrisponda a quanto configurato nel campo SUBDOMAIN o nelle impostazioni del dominio personalizzato. Se hai appena caricato il sito, attendi fino a 60 secondi affinché Square abiliti il primo accesso.

​
Il sito ha impiegato troppo tempo per rispondere…

Il tuo server deve ascoltare sulla porta 80 e sull’host 0.0.0.0. Square Cloud imposta le variabili d’ambiente PORT (80) e HOST (0.0.0.0) nella tua applicazione: leggile nel codice invece di scrivere altri valori fissi. Un server che ascolta solo su localhost o 127.0.0.1 non riceve mai richieste.

​
n8n non risponde sul tuo sottodominio

n8n ignora le variabili PORT e HOST. Controlla che N8N_PORT=80 e N8N_LISTEN_ADDRESS=0.0.0.0 siano impostate, poi riavvia l’applicazione.

​
Gli URL dei webhook puntano alla porta interna

Senza N8N_WEBHOOK_URL, gli URL dei webhook che n8n mostra nei tuoi workflow puntano alla porta interna e i servizi esterni non riescono a raggiungerli. Imposta N8N_WEBHOOK_URL sul tuo indirizzo pubblico, ad esempio https://my-n8n-subdomain.squareweb.app/, poi riavvia l’applicazione.

​
Prossimi passi

Variabili d'ambiente

Gestisci le impostazioni e i segreti di n8n dalla dashboard o dalla CLI.

Dominio personalizzato

Servi n8n dal tuo dominio, poi aggiorna N8N_HOST e N8N_WEBHOOK_URL.

Uptime Kuma

Monitora n8n e gli altri tuoi servizi.
Per saperne di più su n8n, consulta la documentazione ufficiale di n8n.

​
Contattaci

Se continui a riscontrare difficoltà tecniche, il nostro team di supporto specializzato è disponibile ad assisterti. Contattaci e saremo felici di aiutarti a risolvere qualsiasi problema: la qualità del supporto è una parte importante del motivo per cui gli sviluppatori valutano Square Cloud 4,9/5 su 402 recensioni su Google e Trustpilot.