Introduzione
Per sviluppare e ospitare un'applicazione Django 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.
Creare il progetto
Ti servono Python e pip sul tuo computer. Se non li hai, scarica Python dal sito ufficiale di Python.Installazione delle librerie
Installa Django, il server di produzione Gunicorn e WhiteNoise, che serve i tuoi file statici:Sviluppo del progetto
Crea un nuovo progetto Django ed entra nella sua cartella:manage.py e un pacchetto mysite/ con settings.py, urls.py e wsgi.py. Per aggiungere una route di base, modifica mysite/urls.py:
mysite/urls.py
Configurare le impostazioni per la produzione
Non inserire mai segreti direttamente nel codice. Inmysite/settings.py, leggi la chiave segreta e i flag di produzione dalle variabili d’ambiente, considera attendibile l’origine HTTPS del tuo sito e abilita WhiteNoise. Lascia il resto delle impostazioni generate così com’è:
mysite/settings.py
mysite.squareweb.app con il tuo sottodominio o dominio personalizzato. Poi imposta queste variabili d’ambiente nella tua applicazione, dalla dashboard o con squarecloud app env set:
Per eseguire il progetto in locale, imposta
DJANGO_SECRET_KEY (qualsiasi valore) e DJANGO_DEBUG=True nel tuo terminale, poi esegui python manage.py runserver.requirements.txt accanto a manage.py. Square Cloud le installa con pip prima di avviare l’app. Deve elencare almeno:
requirements.txt
Scegliere un server di produzione
Il server di sviluppo integrato di Django (runserver) non è adatto all’uso in produzione. Usa Gunicorn, un server WSGI pronto per la produzione, avviato dal comando START qui sotto. Per le impostazioni dei worker e altre opzioni, consulta la guida di Gunicorn:
Gunicorn
Gunicorn è un server HTTP WSGI Python per UNIX. È un modello worker pre-fork, il che significa che effettua il fork di più processi worker per gestire le richieste.
Questo lo rende un’ottima scelta per eseguire applicazioni web Python in produzione.
Porta e host
Il comandoSTART qui sotto collega Gunicorn a 0.0.0.0:80: tutte le interfacce di rete, sulla porta a cui Square Cloud instrada la tua app. Django di per sé non ha un’impostazione di porta da cambiare.
Configurare Square Cloud
Crea un filesquarecloud.app accanto a manage.py:
squarecloud.app
collectstaticcopia i tuoi file statici inSTATIC_ROOT, da dove WhiteNoise li serve.migrateapplica le migrazioni del database in sospeso. Non fa nulla quando il database è già aggiornato.python -m gunicorn mysite.wsgi --bind 0.0.0.0:80serve l’applicazione WSGI del progettomysitesulla porta 80 e su tutte le interfacce di rete.
MAIN=manage.py seleziona il runtime Python. Nell’upload dalla dashboard, imposta lo stesso file principale e lo stesso comando di avvio.
Cosa mettere nello ZIP
manage.pye il pacchettomysite/, con le tue app e i tuoi template.requirements.txt.squarecloud.app.
manage.py, requirements.txt e squarecloud.app devono trovarsi nella radice dello ZIP. Lascia fuori .venv, __pycache__, staticfiles/ (ricreata da collectstatic a ogni avvio) e il tuo db.sqlite3 locale.
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.
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.
Dopo il deploy, puoi monitorare lo stato e i log del tuo progetto dalla dashboard.

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
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.
Tramite CLI
Per utilizzare questo metodo, il tuo progetto deve avere un file di configurazione chiamatosquarecloud.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 Per caricare uno zip che hai creato tu, passalo con
squarecloud.ignore, e la carica:--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.
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.KeyError: ‘DJANGO_SECRET_KEY’
Manca la variabile d’ambiente. ImpostaDJANGO_SECRET_KEY come mostrato in Configurare le impostazioni per la produzione, poi riavvia l’applicazione.
Bad Request (400)
L’indirizzo che hai aperto non è inDJANGO_ALLOWED_HOSTS. Aggiungici il tuo sottodominio o dominio personalizzato, poi riavvia l’applicazione.
Prossimi passi
Variabili d'ambiente
Tieni segreti e impostazioni fuori dal codice e leggili in fase di esecuzione.
Dominio personalizzato
Pubblica la tua app sul tuo dominio, dal piano Standard in su.
Risoluzione dei problemi
Sistema un’app che non si avvia o un sito che non risponde.

