> ## Documentation Index > Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt > Use this file to discover all available pages before exploring further. # Deploy a Django App with Gunicorn > Deploy a Django app on Square Cloud: read settings from env vars, serve static files with WhiteNoise, and run Gunicorn on port 80 with a START command. export const PyDepFiles = ({lang}) => { const desc = { "en": { requirements: "Standard file used in Python projects to list all the external libraries and dependencies that your project needs. Each line in this file specifies a package to be installed using pip, the Python package manager.", pyproject: "A modern configuration file for Python projects that declares the project metadata and its dependencies. When there is no requirements.txt, Square Cloud installs them with pip install ." }, "pt-br": { requirements: "Arquivo padrão usado em projetos Python para listar todas as bibliotecas externas e dependências necessárias para o seu projeto. Cada linha neste arquivo especifica um pacote a ser instalado usando o pip, o gerenciador de pacotes do Python.", pyproject: "Arquivo de configuração moderno para projetos Python que declara os metadados e as dependências do projeto. Quando não há requirements.txt, a Square Cloud as instala com pip install ." }, "es": { requirements: "Archivo estándar usado en proyectos Python para listar todas las bibliotecas externas y dependencias que tu proyecto necesita. Cada línea de este archivo especifica un paquete que se instalará usando pip, el gestor de paquetes de Python.", pyproject: "Archivo de configuración moderno para proyectos Python que declara los metadatos y las dependencias del proyecto. Cuando no hay requirements.txt, Square Cloud las instala con pip install ." }, "fr": { requirements: "Fichier standard utilisé dans les projets Python pour lister toutes les bibliothèques externes et dépendances nécessaires à votre projet. Chaque ligne de ce fichier spécifie un paquet à installer avec pip, le gestionnaire de paquets de Python.", pyproject: "Fichier de configuration moderne pour les projets Python qui déclare les métadonnées et les dépendances du projet. En l'absence de requirements.txt, Square Cloud les installe avec pip install ." }, "de": { requirements: "Standarddatei in Python-Projekten, die alle externen Bibliotheken und Abhängigkeiten Ihres Projekts auflistet. Jede Zeile dieser Datei gibt ein Paket an, das mit pip, dem Paketmanager von Python, installiert wird.", pyproject: "Moderne Konfigurationsdatei für Python-Projekte, die die Projektmetadaten und die Abhängigkeiten festlegt. Ohne requirements.txt installiert Square Cloud die Abhängigkeiten mit pip install ." }, "it": { requirements: "File standard usato nei progetti Python per elencare tutte le librerie esterne e le dipendenze necessarie al tuo progetto. Ogni riga di questo file specifica un pacchetto da installare con pip, il gestore di pacchetti di Python.", pyproject: "File di configurazione moderno per i progetti Python che dichiara i metadati e le dipendenze del progetto. Se manca il requirements.txt, Square Cloud installa le dipendenze con pip install ." }, "ja": { requirements: "Python プロジェクトで、必要な外部ライブラリと依存関係をすべて列挙するための標準ファイルです。このファイルの各行は、Python のパッケージマネージャーである pip でインストールするパッケージを指定します。", pyproject: "プロジェクトのメタデータと依存関係を宣言する、Python プロジェクト向けのモダンな設定ファイルです。requirements.txt がない場合、Square Cloud は pip install . で依存関係をインストールします。" }, "zh": { requirements: "Python 项目中用于列出项目所需的所有外部库和依赖项的标准文件。文件中的每一行指定一个通过 pip（Python 的包管理器）安装的包。", pyproject: "Python 项目的现代配置文件，用于声明项目元数据和依赖项。没有 requirements.txt 时，Square Cloud 会使用 pip install . 安装这些依赖项。" } }; const l = desc[lang] ? lang : "en"; const d = desc[l]; return {d.requirements} {d.pyproject} ; }; export const PortNote = ({lang}) => { const t = { 'en': { q: 'Which port and host should my server use?', a1: <>Listen on port 80 and host 0.0.0.0. Square Cloud sends your site's HTTPS traffic to that port; a server bound to localhost, 127.0.0.1 or another port can't be reached and the site times out., a2: <>The runtime sets PORT=80 and HOST=0.0.0.0 for you, so read the PORT and HOST environment variables instead of hard-coding them. }, 'pt-br': { q: 'Qual porta e host meu servidor deve usar?', a1: <>Escute na porta 80 e no host 0.0.0.0. A Square Cloud envia o tráfego HTTPS do seu site para essa porta; um servidor preso a localhost, 127.0.0.1 ou a outra porta não é alcançado e o site dá timeout., a2: <>O runtime já define PORT=80 e HOST=0.0.0.0, então leia as variáveis de ambiente PORT e HOST em vez de fixar os valores no código. }, 'es': { q: '¿Qué puerto y host debe usar mi servidor?', a1: <>Escucha en el puerto 80 y en el host 0.0.0.0. Square Cloud envía el tráfico HTTPS de tu sitio a ese puerto; un servidor vinculado a localhost, 127.0.0.1 u otro puerto no es accesible y el sitio agota el tiempo de espera., a2: <>El runtime define PORT=80 y HOST=0.0.0.0 por ti, así que lee las variables de entorno PORT y HOST en lugar de escribirlas a mano en el código. }, 'fr': { q: 'Quel port et quel hôte mon serveur doit-il utiliser ?', a1: <>Écoutez sur le port 80 et l'hôte 0.0.0.0. Square Cloud envoie le trafic HTTPS de votre site vers ce port ; un serveur lié à localhost, 127.0.0.1 ou à un autre port est injoignable et le site expire., a2: <>Le runtime définit PORT=80 et HOST=0.0.0.0 pour vous : lisez les variables d'environnement PORT et HOST plutôt que de les écrire en dur dans le code. }, 'de': { q: 'Welchen Port und Host sollte mein Server verwenden?', a1: <>Ihr Server muss auf Port 80 und Host 0.0.0.0 lauschen. Square Cloud leitet den HTTPS-Traffic Ihrer Website an diesen Port weiter; ein Server, der an localhost, 127.0.0.1 oder einen anderen Port gebunden ist, ist nicht erreichbar und die Website läuft in einen Timeout., a2: <>Die Runtime setzt PORT=80 und HOST=0.0.0.0 für Sie. Lesen Sie daher die Umgebungsvariablen PORT und HOST, statt die Werte fest im Code einzutragen. }, 'it': { q: 'Quale porta e quale host deve usare il mio server?', a1: <>Resta in ascolto sulla porta 80 e sull'host 0.0.0.0. Square Cloud inoltra il traffico HTTPS del tuo sito a quella porta; un server legato a localhost, 127.0.0.1 o a un'altra porta non è raggiungibile e il sito va in timeout., a2: <>Il runtime imposta già PORT=80 e HOST=0.0.0.0, quindi leggi le variabili d'ambiente PORT e HOST invece di scrivere i valori nel codice. }, 'ja': { q: 'サーバーはどのポートとホストを使えばよいですか？', a1: <>ポート80、ホスト0.0.0.0で待ち受けてください。Square Cloudはサイトへの HTTPS トラフィックをこのポートに転送します。localhost、127.0.0.1、または別のポートにバインドしたサーバーには到達できず、サイトはタイムアウトします。, a2: <>ランタイムが PORT=80 と HOST=0.0.0.0 を自動で設定するため、値をコードに直接書かずに環境変数 PORT と HOST を読み取ってください。 }, 'zh': { q: '我的服务器应该使用哪个端口和主机？', a1: <>请监听端口 80 和主机 0.0.0.0。Square Cloud 会把网站的 HTTPS 流量转发到该端口；绑定到 localhost、127.0.0.1 或其他端口的服务器无法访问，网站会超时。, a2: <>运行时已自动设置 PORT=80 和 HOST=0.0.0.0，因此请读取 PORT 和 HOST 环境变量，而不要在代码中写死这些值。 } }; const c = t[lang] || t['en']; return {c.q}
{c.a1}
{c.a2} ; }; export const RecommendedPlan = ({lang, plan, tier, cpu, appType, min}) => { const t = { 'en': { q: <>Which plan should you choose for {appType}?, rec: p => <>We recommend the {p} plan: its {tier} GB of RAM and {cpu} vCPU handle most projects of this kind, with headroom for traffic spikes., min: m => <> Lighter projects also run on the {m} plan., pro: p => <> For larger projects, the {p} plan adds more RAM and CPU. }, 'pt-br': { q: <>Qual plano escolher para {appType}?, rec: p => <>Recomendamos o plano {p}: seus {tier} GB de RAM e {cpu} vCPU atendem a maioria dos projetos desse tipo, com folga para picos de tráfego., min: m => <> Projetos mais leves também rodam no plano {m}., pro: p => <> Para projetos maiores, o plano {p} oferece mais RAM e CPU. }, 'es': { q: <>¿Qué plan elegir para {appType}?, rec: p => <>Te recomendamos el plan {p}: sus {tier} GB de RAM y {cpu} vCPU cubren la mayoría de los proyectos de este tipo, con margen para picos de tráfico., min: m => <> Los proyectos más ligeros también funcionan en el plan {m}., pro: p => <> Para proyectos más grandes, el plan {p} ofrece más RAM y CPU. }, 'fr': { q: <>Quel plan choisir pour héberger {appType} ?, rec: p => <>Nous recommandons le plan {p} : ses {tier} Go de RAM et {cpu} vCPU suffisent pour la plupart des projets de ce type, avec une marge pour les pics de trafic., min: m => <> Les projets plus légers fonctionnent aussi avec le plan {m}., pro: p => <> Pour les projets plus importants, le plan {p} offre davantage de RAM et de CPU. }, 'de': { q: <>Welcher Plan eignet sich für {appType}?, rec: p => <>Wir empfehlen den {p}-Plan: {tier} GB RAM und {cpu} vCPU reichen für die meisten Projekte dieser Art, mit Reserven für Lastspitzen., min: m => <> Kleinere Projekte laufen auch mit dem {m}-Plan., pro: p => <> Für größere Projekte bietet der {p}-Plan mehr RAM und CPU. }, 'it': { q: <>Quale piano scegliere per {appType}?, rec: p => <>Ti consigliamo il piano {p}: i suoi {tier}GB di RAM e {cpu}vCPU bastano per la maggior parte dei progetti di questo tipo, con margine per i picchi di traffico., min: m => <> I progetti più leggeri funzionano anche con il piano {m}., pro: p => <> Per progetti più grandi, il piano {p} offre più RAM e CPU. }, 'ja': { q: <>{appType}にはどのプランを選べばよいですか？, rec: p => <>{p}プランをおすすめします。{tier}GBのRAMと{cpu}vCPUがあれば、この種のプロジェクトの多くをトラフィックのピークにも余裕を持って動かせます。, min: m => <>軽量なプロジェクトは{m}プランでも動作します。, pro: p => <>より大規模なプロジェクトには、RAMとCPUが増える{p}プランをご検討ください。 }, 'zh': { q: <>托管{appType}应该选择哪个套餐？, rec: p => <>我们推荐 {p} 套餐：{tier}GB RAM 和 {cpu}vCPU 足以运行大多数此类项目，并能从容应对流量高峰。, min: m => <>较轻量的项目也可以在 {m} 套餐上运行。, pro: p => <>对于更大的项目，{p} 套餐提供更多 RAM 和 CPU。 } }; const siteLang = t[lang] ? lang : 'en'; const c = t[siteLang]; const pay = (name, query) => {name}; const isPro = plan.toLowerCase() === 'pro'; return {c.q}
{c.rec(pay(plan, `plan=${plan.toLowerCase()}&tier=${tier}`))} {min ? c.min(pay(min, `plan=${min.toLowerCase()}`)) : null} {isPro ? null : c.pro(pay('Pro', 'plan=pro'))} ; }; export const appType_0 = "a Django application" ## Introduction To develop and host {appType_0} on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Python runtime](/en/articles/getting-started-with-python). Tested with Django 6 on Python 3.13 in September 2026. ## Create the project You need Python and pip on your machine. If you don't have them, download Python from the [official Python website](https://www.python.org/downloads/). ### Installing libraries Install Django, the Gunicorn production server and WhiteNoise, which serves your static files: ```bash theme={"system"} pip install django gunicorn whitenoise ``` ### Developing project Create a new Django project and enter its folder: ```bash theme={"system"} django-admin startproject mysite cd mysite ``` This creates `manage.py` and a `mysite/` package with `settings.py`, `urls.py` and `wsgi.py`. To add a basic route, edit `mysite/urls.py`: ```python mysite/urls.py theme={"system"} from django.contrib import admin from django.http import HttpResponse from django.urls import path def index(request): return HttpResponse("Hello, World!") urlpatterns = [ path("", index), path("admin/", admin.site.urls), ] ``` ### Configuring settings for production Never hardcode secrets in your code. In `mysite/settings.py`, read the secret key and the production flags from environment variables, trust your site's HTTPS origin and enable WhiteNoise. Keep the rest of the generated settings as they are: ```python mysite/settings.py theme={"system"} import os from pathlib import Path BASE_DIR = Path(__file__).resolve().parent.parent SECRET_KEY = os.environ["DJANGO_SECRET_KEY"] DEBUG = os.environ.get("DJANGO_DEBUG", "False") == "True" ALLOWED_HOSTS = os.environ.get("DJANGO_ALLOWED_HOSTS", "localhost,127.0.0.1").split(",") # HTTPS address of your site, required for forms (CSRF) behind the Square Cloud proxy CSRF_TRUSTED_ORIGINS = ["https://mysite.squareweb.app"] MIDDLEWARE = [ "django.middleware.security.SecurityMiddleware", "whitenoise.middleware.WhiteNoiseMiddleware", # right after SecurityMiddleware # ... keep the other middleware generated by Django ] STATIC_URL = "static/" STATIC_ROOT = BASE_DIR / "staticfiles" STORAGES = { "default": {"BACKEND": "django.core.files.storage.FileSystemStorage"}, "staticfiles": {"BACKEND": "whitenoise.storage.CompressedManifestStaticFilesStorage"}, } ``` Replace `mysite.squareweb.app` with your subdomain or custom domain. Then set these [environment variables](/en/platform/environment-variables) in your application, from the dashboard or with [`squarecloud app env set`](/en/cli-reference/environment-variables#squarecloud-app-env-set): | Variable | Value | | - | - | | `DJANGO_SECRET_KEY` | A long random value, for example the output of `python -c "import secrets; print(secrets.token_urlsafe(50))"` | | `DJANGO_DEBUG` | `False` (never `True` in production) | | `DJANGO_ALLOWED_HOSTS` | Your domain, for example `mysite.squareweb.app`. Separate multiple domains with commas | To run the project locally, set `DJANGO_SECRET_KEY` (any value) and `DJANGO_DEBUG=True` in your terminal, then run `python manage.py runserver`. Then list your dependencies in a `requirements.txt` file next to `manage.py`. Square Cloud installs them with pip before starting the app. It must list at least: ```txt requirements.txt theme={"system"} django gunicorn whitenoise ``` ## Choose a production server Django's built-in development server (`runserver`) is not suitable for production use. Use Gunicorn, a production-ready WSGI server, started by the `START` command below. For worker settings and other options, see the Gunicorn guide: Gunicorn is a Python WSGI HTTP server for UNIX. It's a pre-fork worker model, which means that it forks multiple worker processes to handle requests. This makes it a great choice for running python web applications in production. ## Port and host The `START` command below binds Gunicorn to `0.0.0.0:80`: all network interfaces, on the port Square Cloud routes to your app. Django itself has no port setting to change. ## Configure Square Cloud Create a `squarecloud.app` file next to `manage.py`: ```systemd squarecloud.app theme={"system"} MAIN=manage.py MEMORY=512 VERSION=recommended DISPLAY_NAME=My Django app SUBDOMAIN=mysite START=python manage.py collectstatic --noinput && python manage.py migrate --noinput && python -m gunicorn mysite.wsgi --bind 0.0.0.0:80 ``` On every start, this command: * `collectstatic` copies your static files to `STATIC_ROOT`, where WhiteNoise serves them. * `migrate` applies pending database migrations. It does nothing when the database is already up to date. * `python -m gunicorn mysite.wsgi --bind 0.0.0.0:80` serves the WSGI application of the `mysite` project on port 80 and all network interfaces. `MAIN=manage.py` selects the Python runtime. In the dashboard upload, set the same main file and start command. ## What goes in the ZIP * `manage.py` and the `mysite/` package, with your apps and templates. * `requirements.txt`. * `squarecloud.app`. `manage.py`, `requirements.txt` and `squarecloud.app` must be at the root of the ZIP. Leave out `.venv`, `__pycache__`, `staticfiles/` (rebuilt by `collectstatic` on every start) and your local `db.sqlite3`. ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Uploading application to Square Cloud Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### KeyError: 'DJANGO\_SECRET\_KEY' The environment variable is missing. Set `DJANGO_SECRET_KEY` as shown in [Configuring settings for production](#configuring-settings-for-production), then restart the application. ### Bad Request (400) The address you opened is not in `DJANGO_ALLOWED_HOSTS`. Add your subdomain or custom domain to it, then restart the application. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Django, see the [official Django documentation](https://docs.djangoproject.com/en/stable/) and its [deployment checklist](https://docs.djangoproject.com/en/stable/howto/deployment/checklist/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.