Quickstart: fai il deploy della tua prima app

Questa guida effettua il deploy di un piccolo server web Node.js, così puoi vedere l’intero flusso dall’inizio alla fine: tre file, uno zip e un upload. I passaggi sono gli stessi per un bot o per un altro linguaggio.

Prima di iniziare

Square Cloud è una piattaforma a pagamento: è richiesto un piano attivo per effettuare il deploy, così il tuo progetto gira su un’infrastruttura di livello produzione fin dal primo giorno. Crea il tuo account, poi scegli il piano più adatto a te (scopri cosa include ogni piano).

Registrati

Se non hai mai usato Square prima d’ora, registrati per iniziare.

Accedi

Se hai già un account, accedi per iniziare.

Crea il progetto

Crea una cartella con questi tre file.

Scrivi l'app

index.js risponde a ogni richiesta con un breve messaggio. Legge porta e host dalle variabili d’ambiente PORT e HOST, che Square Cloud imposta a 80 e 0.0.0.0:

index.js

const http = require("node:http");

const port = process.env.PORT || 3000;
const host = process.env.HOST || "0.0.0.0";

http
  .createServer((req, res) => {
    res.writeHead(200, { "Content-Type": "text/plain" });
    res.end("Hello from Square Cloud!");
  })
  .listen(port, host, () => {
    console.log(`Listening on http://${host}:${port}`);
  });

Elenca le dipendenze

Ogni progetto Node.js ha bisogno di un package.json: Square Cloud installa i pacchetti che elenca prima di avviare la tua app. Questo esempio non ne ha, ma il file deve esistere e non può essere vuoto.

package.json

{
  "name": "hello-square",
  "version": "1.0.0",
  "private": true,
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  }
}

Aggiungi il file di configurazione

squarecloud.app indica a Square Cloud quale file eseguire, quanta memoria riservare e quale versione del runtime usare. SUBDOMAIN pubblica l’app come sito su https://<subdomain>.squareweb.app, quindi scegli un nome che nessuno abbia già preso.

squarecloud.app

MAIN=index.js
MEMORY=512
VERSION=recommended
DISPLAY_NAME=Hello Square
SUBDOMAIN=hello-square-yourname

Ogni campo è spiegato nel riferimento del file di configurazione. L’estensione per VS Code completa e controlla questo file mentre scrivi.

Un sito deve restare in ascolto sulla porta 80 e sull’host 0.0.0.0. Un server associato a localhost, 127.0.0.1 o a un’altra porta (come 3000 o 8080) non è raggiungibile, e il sito mostra una pagina di timeout. Leggere PORT e HOST, come fa index.js, funziona correttamente su Square Cloud e continua a usare la porta 3000 sulla tua macchina.

Devi pubblicare un bot? Ometti SUBDOMAIN, aggiungi AUTORESTART=true e tieni il token in una variabile d’ambiente, mai nel codice. Il tutorial sul bot Discord mostra un bot completo.

Comprimi il progetto

Effettui il deploy con la CLI? Salta questa sezione: squarecloud upload comprime la cartella per te.

Seleziona i file, non la cartella

Apri la cartella del progetto e seleziona tutto il suo contenuto. squarecloud.app deve trovarsi al primo livello dello zip: se comprimi la cartella stessa, i file finiscono dentro una sottocartella e il deploy fallisce con MISSING_CONFIG.

Crea lo zip

Windows
macOS
Linux

Fai clic destro sui file selezionati e scegli Comprimi in file ZIP (Windows 11) oppure Invia a → Cartella compressa.

Fai clic destro sui file selezionati e scegli Comprimi, oppure esegui zip -r ../app.zip . dentro la cartella.

Controlla la dimensione

Lo zip può arrivare fino a 100 MB. Escludi node_modules, gli ambienti virtuali e le cache di build: le dipendenze vengono installate sul server, e quelle cartelle vengono comunque eliminate durante il deploy.

Effettua il deploy

Carica lo zip nella dashboard, oppure effettua il deploy con un solo comando dalla CLI.

Tramite dashboard

Accedi alla pagina di upload

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

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.

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

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.

Installa la CLI

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

curl -fsSL https://cli.squarecloud.app/install | bash

npm install -g @squarecloud/cli@latest

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.

squarecloud auth login

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:

squarecloud upload

Per caricare uno zip che hai creato tu, passalo con --file:

squarecloud upload --file <path/to/zip>

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:

squarecloud app status
squarecloud app logs

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.

Quando l’app è in esecuzione, https://hello-square-yourname.squareweb.app (con il tuo sottodominio) risponde Hello from Square Cloud!.

Vuoi un deploy a ogni push? Collega un repository GitHub oppure usa il workflow di GitHub Actions.

Prossimi passi

File di configurazione

Ogni campo di squarecloud.app: memoria, comando di avvio, sottodominio e riavvii automatici.

Variabili d'ambiente

Conserva token e stringhe di connessione fuori dal codice.

Risoluzione dei problemi

Risolvi errori di upload, siti che non si caricano e app che non si avviano.

Estensione VS Code

Carica, esegui il commit e segui i log senza uscire dal tuo editor.

Guide per il tuo linguaggio

Ogni guida spiega il file delle dipendenze, il comando di avvio e gli errori più comuni del suo runtime.

Servizi

Risoluzione dei problemi

Runtimes

Piattaforma

Changelog

Quickstart: fai il deploy della tua prima app

Prima di iniziare

Registrati

Accedi

Crea il progetto

Comprimi il progetto

Effettua il deploy

Tramite dashboard

Tramite CLI

Guida al file di configurazione

Prossimi passi

File di configurazione

Variabili d'ambiente

Risoluzione dei problemi

Estensione VS Code

Guide per il tuo linguaggio

JavaScript

Bun

Deno

Python

Java

Rust

Elixir

PHP

Go

C#

Ruby

HTML/CSS

​Prima di iniziare

Registrati

Accedi

​Crea il progetto

​Comprimi il progetto

​Effettua il deploy

​Tramite dashboard

​Tramite CLI

Guida al file di configurazione

​Prossimi passi

File di configurazione

Variabili d'ambiente

Risoluzione dei problemi

Estensione VS Code

​Guide per il tuo linguaggio

JavaScript

Bun

Deno

Python

Java

Rust

Elixir

PHP

Go

C#

Ruby

HTML/CSS

Prima di iniziare

Crea il progetto

Comprimi il progetto

Effettua il deploy

Tramite dashboard

Tramite CLI

Prossimi passi

Guide per il tuo linguaggio