> ## Documentation Index > Fetch the complete documentation index at: https://developer.upsun.com/llms.txt > Use this file to discover all available pages before exploring further. # Deploy Django on Upsun Cloud > A step-by-step guide to deploy a Django application on Upsun Cloud, from a blank project to a live URL. This guide walks you through deploying a Django application on Upsun Cloud step by step — from a blank project to a live URL. If you have read the [Getting started guide](https://developer.upsun.com/docs/get-started/here), this page adds Django-specific detail that the generic guide skips. If you haven't, no problem — this guide is self-contained. ## Before you begin You need: You also need **Python 3.9+** and `pip` installed locally. ## 1. Create a Django project Create a directory, activate a virtual environment, and install Django: ```bash theme={null} mkdir djangotutorial && cd djangotutorial python -m venv venv source venv/bin/activate pip install Django ``` > [!NOTE] > > Windows > Replace `source venv/bin/activate` with `venv\Scripts\activate`. Scaffold the project. The trailing `.` places all files directly in the current directory and avoids a nested folder: ```bash theme={null} django-admin startproject mysite . ``` Your directory now looks like this: ``` djangotutorial/ ├── manage.py └── mysite/ ├── __init__.py ├── asgi.py ├── settings.py ├── urls.py └── wsgi.py ``` Initialize a Git repository and make your first commit: ```bash theme={null} git init && git branch -M main git add . git commit -m "Initial Django project" ``` ## 2. Add production dependencies Upsun Cloud runs your Django app using [Gunicorn](https://gunicorn.org), a production-grade WSGI server. You also need a database adapter that matches your chosen database. > [tab] MariaDB > > ```bash theme={null} > pip install gunicorn mysqlclient > ``` > [tab] PostgreSQL > > ```bash theme={null} > pip install gunicorn psycopg2-binary > ``` Save the dependency list so Upsun Cloud can install it at build time: ```bash theme={null} pip freeze > requirements.txt git add requirements.txt git commit -m "Add production dependencies" ``` ## 3. Set environment variables Create a `.environment` file at the root of your project. Upsun Cloud sources this file automatically before starting your app, on every environment (production, preview branches, etc.). ```bash .environment theme={null} export DJANGO_SETTINGS_MODULE="mysite.settings" export DJANGO_SECRET_KEY="$PLATFORM_PROJECT_ENTROPY" export DJANGO_ALLOWED_HOSTS="$(echo "$PLATFORM_ROUTES" | base64 --decode | jq -r 'to_entries[] | select(.value.primary == true) | .key' | sed 's:/*$::' | sed 's|https\?://||')" ``` What each variable does: * **`DJANGO_SETTINGS_MODULE`** — tells Django which settings file to load. * **`DJANGO_SECRET_KEY`** — uses `PLATFORM_PROJECT_ENTROPY`, a unique value Upsun Cloud generates per project. The key is never stored in your repository. * **`DJANGO_ALLOWED_HOSTS`** — dynamically extracts the hostname of the current environment from your project routes, so every preview branch and production environment works automatically. > [!WARNING] > > Commit .environment to Git > This file contains no secrets — the values are resolved at runtime from Upsun Cloud variables. > It must be committed so Upsun Cloud can source it on every deploy. ```bash theme={null} git add .environment git commit -m "Add Upsun Cloud environment variables" ``` ## 4. Update `settings.py` Open `mysite/settings.py` and make three changes. **Add `import os`** at the top of the file, after `from pathlib import Path`: ```python mysite/settings.py theme={null} import os ``` **Replace the `ALLOWED_HOSTS` line.** The default `[]` rejects all requests when `DEBUG = False`. Use the environment variable set in the previous step: ```python mysite/settings.py theme={null} ALLOWED_HOSTS = os.getenv('DJANGO_ALLOWED_HOSTS', 'localhost').split(',') ``` **Add the Upsun Cloud production block** at the very bottom of the file. It only activates when `PLATFORM_APPLICATION_NAME` is present — a variable Upsun Cloud injects automatically at runtime. Your local development settings are untouched. > [tab] MariaDB > > ```python mysite/settings.py theme={null} > # Upsun Cloud production settings > if os.getenv('PLATFORM_APPLICATION_NAME') is not None: > DEBUG = False > > if os.getenv('PLATFORM_APP_DIR') is not None: > STATIC_ROOT = os.path.join(os.getenv('PLATFORM_APP_DIR'), 'static') > > if os.getenv('PLATFORM_PROJECT_ENTROPY') is not None: > SECRET_KEY = os.getenv('PLATFORM_PROJECT_ENTROPY') > > if os.getenv('PLATFORM_ENVIRONMENT') is not None: > DATABASES = { > 'default': { > 'ENGINE': 'django.db.backends.mysql', > 'NAME': os.getenv('DATABASE_PATH'), > 'USER': os.getenv('DATABASE_USERNAME'), > 'PASSWORD': os.getenv('DATABASE_PASSWORD'), > 'HOST': os.getenv('DATABASE_HOST'), > 'PORT': os.getenv('DATABASE_PORT'), > } > } > ``` > [tab] PostgreSQL > > ```python mysite/settings.py theme={null} > # Upsun Cloud production settings > if os.getenv('PLATFORM_APPLICATION_NAME') is not None: > DEBUG = False > > if os.getenv('PLATFORM_APP_DIR') is not None: > STATIC_ROOT = os.path.join(os.getenv('PLATFORM_APP_DIR'), 'static') > > if os.getenv('PLATFORM_PROJECT_ENTROPY') is not None: > SECRET_KEY = os.getenv('PLATFORM_PROJECT_ENTROPY') > > if os.getenv('PLATFORM_ENVIRONMENT') is not None: > DATABASES = { > 'default': { > 'ENGINE': 'django.db.backends.postgresql', > 'NAME': os.getenv('DATABASE_PATH'), > 'USER': os.getenv('DATABASE_USERNAME'), > 'PASSWORD': os.getenv('DATABASE_PASSWORD'), > 'HOST': os.getenv('DATABASE_HOST'), > 'PORT': os.getenv('DATABASE_PORT'), > } > } > ``` The `DATABASE_*` environment variables are exposed automatically by the relationship you define in the next step. ```bash theme={null} git add mysite/settings.py git commit -m "Add Upsun Cloud production settings" ``` ## 5. Create your Upsun Cloud project If you don't have an Upsun Cloud project yet, create one with the CLI: ```bash theme={null} upsun project:create ``` The CLI asks for a project name and region, then automatically links your local repository to the new project. > [!NOTE] > > Already have a project? > If you created a project from the [Upsun Cloud Console](https://console.upsun.com), link your local repository to it: > > ```bash theme={null} > upsun project:set-remote > ``` > > Find your project ID in the Console or by running `upsun project:list`. ## 6. Configure Upsun Cloud Create a `.upsun/` directory at the root of your project, then add a `config.yaml` file inside it. This single file defines your application container, database service, and routing. > [tab] MariaDB > > applications: > mysite: > type: python:3.14 > > build: > flavor: none > > relationships: > database: "db:mysql" > > hooks: > build: | > set -eux > pip install --upgrade pip > pip install -r requirements.txt > deploy: | > set -eux > python manage.py collectstatic --noinput > python manage.py migrate > > mounts: > static: > source: storage > source\_path: static > > web: > commands: > start: "gunicorn mysite.wsgi:application -b unix:\$SOCKET" > upstream: > socket\_family: unix > locations: > /: > passthru: true > /static: > allow: true > expires: 1h > root: static > > routes: > https\://\{default}/: > type: upstream > upstream: "mysite:http" > > services: > db: > type: mariadb:12.3 > > [tab] PostgreSQL > > applications: > mysite: > type: python:3.14 > > build: > flavor: none > > relationships: > database: "db:postgresql" > > hooks: > build: | > set -eux > pip install --upgrade pip > pip install -r requirements.txt > deploy: | > set -eux > python manage.py collectstatic --noinput > python manage.py migrate > > mounts: > static: > source: storage > source\_path: static > > web: > commands: > start: "gunicorn mysite.wsgi:application -b unix:\$SOCKET" > upstream: > socket\_family: unix > locations: > /: > passthru: true > /static: > allow: true > expires: 1h > root: static > > routes: > https\://\{default}/: > type: upstream > upstream: "mysite:http" > > services: > db: > type: postgresql:17 > Key points: * **`build: flavor: none`** — disables default build behaviors so only your `hooks.build` commands run. * **`relationships`** — exposes `DATABASE_*` environment variables to your app (used by `settings.py`). * **`hooks.build`** — installs Python dependencies during the build phase (no database access yet). * **`hooks.deploy`** — runs `collectstatic` and migrations at deploy time (database is available). * **`mounts`** — declares `static/` as a persistent writable directory for collected static files. * **`web.commands.start`** — starts Gunicorn over a Unix socket (`$SOCKET`), which Upsun Cloud manages automatically. ```bash theme={null} git add .upsun/ git commit -m "Add Upsun Cloud configuration" ``` ## 7. Deploy Push everything to Upsun Cloud: ```bash theme={null} upsun push ``` The first deploy installs dependencies, collects static files, and runs database migrations. It takes a minute or two. Subsequent deploys are faster. Open your app once the deploy completes: ```bash theme={null} upsun url --primary ``` ## Troubleshooting **400 Bad Request on every page** `ALLOWED_HOSTS` is rejecting the request. Check two things: 1. `mysite/settings.py` has `ALLOWED_HOSTS = os.getenv('DJANGO_ALLOWED_HOSTS', 'localhost').split(',')` at the **top level** — not inside the `if` block. 2. `.environment` is committed to Git. **Build fails — `mysqlclient` or `psycopg2` not found** `requirements.txt` is missing the database adapter. Run: ```bash theme={null} pip install gunicorn mysqlclient # or psycopg2-binary pip freeze > requirements.txt git add requirements.txt && git commit -m "Fix missing DB adapter" upsun push ``` **`gunicorn: command not found` in deploy logs** Same cause — `gunicorn` is missing from `requirements.txt`. Apply the same fix above. **Static files return 404** Check that `STATIC_ROOT` in `settings.py` uses `os.path.join(os.getenv('PLATFORM_APP_DIR'), 'static')` and that the mount key in `.upsun/config.yaml` is also `static`. They must match exactly. ## Further resources ### Documentation * [Python documentation](https://developer.upsun.com/docs/languages/python) * [Managing Python dependencies](https://developer.upsun.com/docs/languages/python/dependencies.md) * [Configuring web servers](https://developer.upsun.com/docs/languages/python/server.md) * [Getting started guide](https://developer.upsun.com/docs/get-started/here) ### Blogs * [*Up(sun) and running with Django*](https://upsun.com/blog/setting-up-django-on-upsun/) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.