Skip to main content

​
Cos’è il file di configurazione?

Il file di configurazione indica a Square Cloud come eseguire la tua applicazione: quale file avviare, quanta memoria riservare, quale versione del runtime usare e, per un sito, quale sottodominio pubblicare. È un file di testo semplice con una coppia KEY=VALUE per riga.
squarecloud.app

​
Creare il file di configurazione

Crea un file chiamato squarecloud.app o squarecloud.config nella radice del progetto. I due nomi funzionano allo stesso modo. Quando carichi uno zip, il file deve trovarsi al primo livello dello zip, non dentro una sottocartella, altrimenti il deploy fallisce con MISSING_CONFIG.
Su macOS, consigliamo il nome squarecloud.config.
L’estensione per VS Code completa ogni chiave qui sotto e sottolinea i valori non validi mentre scrivi.

​
Parametri di configurazione

MEMORY, VERSION e DISPLAY_NAME sono sempre obbligatori. MAIN è obbligatorio a meno che tu non imposti RUNTIME. I parametri modificabili possono essere cambiati nella dashboard dopo il deploy. Per cambiare un parametro non modificabile devi caricare di nuovo l’applicazione.

​
MAIN

Il file che avvia la tua applicazione, relativo alla radice del progetto.
  • L’estensione del file sceglie il runtime: .js viene eseguito su Node.js, .ts su TypeScript, .py su Python e così via.
  • Il file deve esistere nel tuo upload e non può essere vuoto.
  • Fino a 32 caratteri: lettere, cifre, _, ., / e -, senza spazi.
Un MAIN mancante (senza RUNTIME) fallisce con MISSING_MAIN; un file che non esiste, non ha estensione o viola le regole qui sopra fallisce con INVALID_MAIN.

​
MEMORY

La RAM riservata alla tua applicazione, in megabyte. Determina anche le vCPU e la banda della tua applicazione.
Il valore deve essere almeno il minimo per il tuo tipo di progetto e non superare la RAM ancora libera nel tuo piano. Altrimenti il deploy fallisce con INSUFFICIENT_MEMORY.

​
VERSION

La versione del runtime: recommended o latest. Qualsiasi altro valore, incluso un numero di versione esatto, fa fallire il deploy con INVALID_VERSION.
Usa recommended, a meno che non ti serva una funzionalità presente solo nella release più recente. Le versioni dietro ciascun valore sono elencate nella tabella delle versioni dei runtime.

​
DISPLAY_NAME

Il nome mostrato nella dashboard, nella CLI e nell’API.
Fino a 32 caratteri: lettere senza accenti, cifre, spazi, - e _. Qualsiasi altro carattere, come lettere accentate o emoji, fallisce con INVALID_DISPLAY_NAME.

​
DESCRIPTION

Una breve descrizione dell’applicazione, fino a 280 caratteri (oltre si ottiene INVALID_DESCRIPTION).

​
AUTORESTART

Riavvia automaticamente l’applicazione dopo un crash. Accetta true o false e il valore predefinito è false, quindi attivalo per i bot e per tutto ciò che deve restare online.
Un riavvio automatico avviene solo quando sono vere tutte queste condizioni:
  • L’applicazione è terminata con stato 1, il codice di uscita abituale di un errore non gestito in Node.js e Python.
  • Era in esecuzione da almeno 60 secondi, così un’app che va in crash subito all’avvio non viene riavviata in loop.
  • Non è stata riavviata automaticamente nell’ultima ora.
  • I log non mostrano un errore che un riavvio non può risolvere: un token del bot non valido, un modulo mancante, un errore di sintassi o di tipo TypeScript, oppure un’installazione delle dipendenze non riuscita.
Un riavvio mantiene l’app online nonostante un errore temporaneo, ma il bug di fondo va comunque corretto nel codice. Consulta anche l’articolo del centro assistenza sul riavvio automatico.

​
SUBDOMAIN

Pubblica l’applicazione come sito su https://<subdomain>.squareweb.app.
  • Fino a 63 caratteri: lettere, cifre e trattini, senza iniziare né terminare con un trattino. Il nome viene salvato in minuscolo.
  • Un nome già in uso, riservato (come admin o api) o non valido fallisce con INVALID_SUBDOMAIN.
  • Un sito richiede più RAM di un bot: vedi la RAM minima.
  • Il tuo server deve restare in ascolto sulla porta 80 e sull’host 0.0.0.0 (vedi il sito non si carica).
Decidi al primo upload se l’applicazione è un sito. Su un sito puoi cambiare il sottodominio in seguito, ma non puoi rimuoverlo (CANNOT_SET_SUBDOMAIN). Un’applicazione pubblicata senza SUBDOMAIN non può diventare un sito: caricala di nuovo come nuova applicazione con SUBDOMAIN impostato.
Per servire il sito sul tuo dominio, consulta come configurare il tuo dominio nel centro assistenza.

​
RUNTIME

Imposta il runtime in modo esplicito, invece di ricavarlo dall’estensione di MAIN. Un valore sconosciuto fallisce con INVALID_RUNTIME.
Con RUNTIME impostato puoi omettere MAIN. In quel caso imposta anche START: la maggior parte dei runtime avvia l’applicazione eseguendo il file MAIN.

​
START

Un comando di avvio personalizzato. Sostituisce il comando predefinito, che esegue il tuo file MAIN.
  • Fino a 256 caratteri (oltre si ottiene INVALID_START).
  • Le dipendenze vengono comunque installate prima dell’esecuzione del comando.
  • Il comando viene letto dal file a ogni avvio, quindi puoi cambiarlo modificando squarecloud.app nella dashboard e riavviando.
Richiama solo script che esistono nel tuo progetto. START=npm run build && npm run start, per esempio, fallisce su un’app Express senza uno script build in package.json. Ometti START quando basta il comando predefinito.

​
ID

Non scrivi tu questa chiave. Dopo squarecloud upload, la CLI di Square Cloud aggiunge ID=<app ID> al file, così i comandi successivi come squarecloud commit sanno quale applicazione usare. Square Cloud la ignora durante il deploy.

​
Esempi

​
Bot

squarecloud.app

​
Sito o API

squarecloud.app
Il sito risponde su https://mysite.squareweb.app.

​
Next.js

Un framework che richiede una fase di build usa START. Qui MAIN serve solo a selezionare il runtime Node.js, quindi puntalo al tuo file di configurazione reale (come next.config.mjs); gli script di build e di avvio vengono da package.json.
squarecloud.app

​
Prossimi passi

Variabili d'ambiente

Tieni token e stringhe di connessione fuori dal codice e dallo zip.

squarecloud.ignore

Scegli quali file la CLI e VS Code escludono dall’upload.

Runtime

Versioni, file delle dipendenze e come ogni runtime avvia la tua app.

Risoluzione dei problemi

Cosa significa ogni errore di deploy e come risolverlo.