Upsun User Documentation

Deploy Django on Upsun

Sign up

Get your free trial by clicking the link below.

Get your Upsun free trial

For Django to successfully deploy and operate, after completing the Getting started guide, you still need to make a few changes to your Upsun configuration.

Before you begin Anchor to this heading

You need:

  • Git. Git is the primary tool to manage everything your app needs to run. Push commits to deploy changes and control configuration through YAML files. These files describe your infrastructure, making it transparent and version-controlled.
  • A Upsun account. If you don’t already have one, register for a trial account. You can sign up with an email address or an existing GitHub, Bitbucket, or Google account. If you choose one of these accounts, you can set a password for your Upsun account later.
  • The Upsun CLI. This lets you interact with your project from the command line. You can also do most things through the Web Console.

1. Leverage environment variables Anchor to this heading

Your file may allow for environment variables to be set for common pieces of configuration. In this case, add and commit a .environment file that includes those details.

export DJANGO_SETTINGS_MODULE=config.settings.production

2. Configure ALLOWED_HOSTS Anchor to this heading

Your file may not allow you to use an environment variable like DJANGO_ALLOWED_HOSTS. If so, to configure allowed hosts, update your file to include

Appending to ALLOWED_HOSTS allows for all URLs generated for Upsun preview environments.

3. Upsun-specific settings Anchor to this heading

Near the bottom of your file, define a block that:

  • Detects when Django is running on an Upsun environment
  • Override previous settings

If your configuration is split into a file for production settings, place it there instead.
# Production/Upsun settings.
if (os.getenv('PLATFORM_APPLICATION_NAME') is not None):
    DEBUG = False

    # Static dir.
    if (os.getenv('PLATFORM_APP_DIR') is not None):
        STATIC_ROOT = os.path.join(os.getenv('PLATFORM_APP_DIR'), 'static')

    # Secret Key.
    if (os.getenv('PLATFORM_PROJECT_ENTROPY') is not None):

    # Production database configuration.
    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'),
            'sqlite': {
                'ENGINE': 'django.db.backends.sqlite3',
                'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),

This update includes a few important changes:

  1. Overwrites. If the PLATFORM_APPLICATION_NAME Upsun built-in variable is found (that is, Django is running on an Upsun environment), override your previous settings. No matter what environment type we run on Upsun, this file uses production settings for Upsun (i.e. DEBUG = False).

  2. Static. STATIC_ROOT, and the static files path is updated relative to the application root on Upsun.

  3. Secret key. All Upsun projects come with a unique hash environment variable PLATFORM_PROJECT_ENTROPY that can be used to update your SECRET_KEY.

  4. Databases. When Django is running on an Upsun enviroment at runtime, it has access to service containers like databases and caches. Every service container you configure in .upsun/config.yaml has a unique relationship name (applications:<APP_NAME>:relationships:<RELATIONSHIPNAME>). Upsun automatically uses this relationship name to expose connection credentials through environment variables (for example, via RELATIONSHIPNAME_HOST).
    Update according to the example above (which configures a PostgreSQL service), where the relationship database results in environment variables that are leveraged to update the DATABASES setting for your application.
    You can use the exact same logic to configure CACHES from the rediscache relationship using the exposed REDISCACHE_ environment variables to setup django_redis.cache.RedisCache.

4. Start the app Anchor to this heading

In your app configuration, locate the web:commands:start section and update it as follows:

                start: "gunicorn -b unix:$SOCKET config.wsgi"
                socket_family: unix

Note that if your Django instance requires a different web server, Upsun also supports several other options.

5. Configure static assets Anchor to this heading

To access Django’s static assets, you need to add a second location to the web:locations section of your app configuration. Locate the web:locations section and add a location for /static:

                    "passthru": true
                    "allow": true
                    "expires": "1h"
                    "root": "static"

6. Install dependencies and builds Anchor to this heading

Instruct Upsun to install your Python and Node (if needed) dependencies. Locate the hooks:build section and update it as follows:

        build: |
            set -eux

            pip install --upgrade pip
            pip install -r requirements.txt
            npm install
            npm run build            

Remove the npm steps if not required for your app’s assets. Note that if your project uses a different package manager, Upsun also supports several other options.

7. Configure the deploy phase Anchor to this heading

In your app configuration, locate the deploy section and update it as follows:

        deploy: |
            set -eux

            python collectstatic --noinput
            python migrate            

8. Allow write access where needed Anchor to this heading

Since Django can require a writable locations at runtime, you need to set up writable mounts. To do so, locate the mounts section (currently commented), and update it as follows:

                source: "local"
                source_path: "static_assets"

You can now commit all of the above changes and push to Upsun.

git add .
git commit -m "Add changes to complete my Upsun configuration"
git push

Further resources Anchor to this heading

Documentation Anchor to this heading

Community content Anchor to this heading

Blogs Anchor to this heading

Is this page helpful?