Deploy Django on Upsun

This guide walks you through deploying a Django application on Upsun step by step — from a blank project to a live URL. If you have read the Getting started guide, this page adds Django-specific detail that the generic guide skips. If you haven’t, no problem — this guide is self-contained. 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:

mkdir djangotutorial && cd djangotutorial
python -m venv venv
source venv/bin/activate
pip install Django

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:

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:

git init && git branch -M main
git add .
git commit -m "Initial Django project"

2. Add production dependencies

Upsun runs your Django app using Gunicorn, a production-grade WSGI server. You also need a database adapter that matches your chosen database.

MariaDB
PostgreSQL

pip install gunicorn mysqlclient

pip install gunicorn psycopg2-binary

Save the dependency list so Upsun can install it at build time:

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 sources this file automatically before starting your app, on every environment (production, preview branches, etc.).

.environment

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 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.

Commit .environment to Git

This file contains no secrets — the values are resolved at runtime from Upsun variables. It must be committed so Upsun can source it on every deploy.

git add .environment
git commit -m "Add Upsun 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:

mysite/settings.py

import os

Replace the ALLOWED_HOSTS line. The default [] rejects all requests when DEBUG = False. Use the environment variable set in the previous step:

mysite/settings.py

ALLOWED_HOSTS = os.getenv('DJANGO_ALLOWED_HOSTS', 'localhost').split(',')

Add the Upsun production block at the very bottom of the file. It only activates when PLATFORM_APPLICATION_NAME is present — a variable Upsun injects automatically at runtime. Your local development settings are untouched.

MariaDB
PostgreSQL

mysite/settings.py

# Upsun 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'),
            }
        }

mysite/settings.py

# Upsun 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.

git add mysite/settings.py
git commit -m "Add Upsun production settings"

5. Create your Upsun project

If you don’t have an Upsun project yet, create one with the CLI:

upsun project:create

The CLI asks for a project name and region, then automatically links your local repository to the new project.

Already have a project?

If you created a project from the Upsun Console, link your local repository to it:

upsun project:set-remote <PROJECT_ID>

Find your project ID in the console or by running upsun project:list.

6. Configure Upsun

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. 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 manages automatically.

git add .upsun/
git commit -m "Add Upsun configuration"

7. Deploy

Push everything to Upsun:

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:

upsun url --primary

Troubleshooting

400 Bad Request on every page ALLOWED_HOSTS is rejecting the request. Check two things:

mysite/settings.py has ALLOWED_HOSTS = os.getenv('DJANGO_ALLOWED_HOSTS', 'localhost').split(',') at the top level — not inside the if block.
.environment is committed to Git.

Build fails — mysqlclient or psycopg2 not found requirements.txt is missing the database adapter. Run:

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

Blogs

Up(sun) and running with Django

Get Started

Core Concepts

Configure Apps & Services

Build, Deploy & Run

Manage Projects

Manage Environments

Manage Resources

Observability & Metrics

Integrations

Troubleshooting

Resources

1. Create a Django project

Windows

2. Add production dependencies

3. Set environment variables

Commit .environment to Git

4. Update `settings.py`

5. Create your Upsun project

Already have a project?

6. Configure Upsun

7. Deploy

Troubleshooting

Further resources

Documentation

Blogs

​1. Create a Django project

Windows

​2. Add production dependencies

​3. Set environment variables

Commit .environment to Git

​4. Update settings.py

​5. Create your Upsun project

Already have a project?

​6. Configure Upsun

​7. Deploy

​Troubleshooting

​Further resources

​Documentation

​Blogs

1. Create a Django project

2. Add production dependencies

3. Set environment variables

4. Update `settings.py`

5. Create your Upsun project

6. Configure Upsun

7. Deploy

Troubleshooting

Further resources

Documentation

Blogs