Django Environment#

CodeRed provides a fully managed Django environment for your website. With just a few settings file modifications, your existing app can take advantage of CodeRed’s built-in features and security enhancements.

This page provides technical reference as to how Django works “under the hood” on CodeRed Cloud. All new apps launched on CodeRed Cloud are configured using the recommended settings by default.

Django Project Name#

By default CodeRed Cloud assumes that your Django project name is the same as the handle of your webapp, with dashes replaced with underscores (e.g. the handle of my-app.codered.cloud would be my-app with Django project my_app). If this is not the case (e.g. you imported your project from a different host) you can set your project name in the settings tab of the dashboard.

The cr check command will offer to set the correct Django project name if it detects a different one when run on your local project.

Django Settings File#

CodeRed Cloud looks for specific Django settings files when your app runs:

  • projectname/settings/prod.py for the Production environment.

  • projectname/settings/staging.py for the Staging environment.

We recommend that you create a projectname/settings/base.py file containing all of your main settings, and then override any environment-specific settings in prod.py or staging.py.

The cr check command will automatically scan and offer to fix your settings files when run on your local project.

Environment Variables#

To work with CodeRed Cloud, your Django settings file should load a few important settings from environment variables. The CodeRed-provided environment variables are:

  • DB_HOST - Your database host.

  • DB_NAME - Your database name.

  • DB_USER - The username used to connect to your database.

  • DB_PASSWORD - A secure randomly generated password used to connect to your database.

  • DJANGO_SETTINGS_MODULE - This is a standard Django environment variable that tells Django which settings file to use.

  • RANDOM_SECRET_KEY - A secure randomly generated secret key that can be used with Django.

    Note

    RANDOM_SECRET_KEY is re-generated every time your app is re-deployed, which will cause users of your app to be logged out. If you want to avoid this behavior, hard-code the secret key instead of using this random key.

  • VIRTUAL_HOST - The full domain of your website (e.g. www.example.com).

A recommended settings file would start with this:

from .base import *  # noqa

# -- Recommended CodeRed Cloud settings ---------------------------------------

import os

ALLOWED_HOSTS = [os.environ['VIRTUAL_HOST']]

SECRET_KEY = os.environ['RANDOM_SECRET_KEY']

Note

Custom environment variables for staging and production can be added in the website’s Settings tab in the CodeRed Cloud dashboard.

Database#

Each website on CodeRed includes a MySQL or PostgreSQL database hosted in the same region as your website. You may also use SQLite directly on the filesystem with no additional configuration required.

In addition to the recommended settings above, add the respective database settings below to your settings file.

Note

For enhanced security, your database password and permissions are reset automatically every time your app restarts. It is therefore impossible to hard-code those in your settings without using environment variables.

MySQL Settings#

Your MySQL database requires SSL to connect, and is configured to use utf8mb4 character set and utf8mb4_0900_ai_ci collation by default. You should therefore also set the charset in your Django settings to avoid any potential issues when working with Unicode characters, including emoji.

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'HOST': os.environ['DB_HOST'],
        'NAME': os.environ['DB_NAME'],
        'USER': os.environ['DB_USER'],
        'PASSWORD': os.environ['DB_PASSWORD'],
        'OPTIONS': {
            'ssl': {},
            'charset': 'utf8mb4',
        },
    }
}

PostgreSQL Settings#

Your PostgreSQL database requires SSL to connect, and is set to use UTF8 character set.

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql_psycopg2',
        'HOST': os.environ['DB_HOST'],
        'NAME': os.environ['DB_NAME'],
        'USER': os.environ['DB_USER'],
        'PASSWORD': os.environ['DB_PASSWORD'],
        'OPTIONS': {'sslmode': 'require'},
    }
}

SQLite Settings#

Since your app’s filesystem is backed by persistent high-speed solid state storage, the recommended way to use SQLite is directly on the filesystem.

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
    }
}

Static & Media Files#

Static and media files in your Django app will “just work” — there is no additional configuration required. However, you must be sure to set STATIC_URL and STATIC_ROOT, and MEDIA_URL and MEDIA_ROOT in your Django settings.

Typical settings would look like:

STATIC_URL = '/static/'
STATIC_ROOT = os.path.join(BASE_DIR, 'static')
MEDIA_URL = '/media/'
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')

How it works under the hood: Whenever your app is deployed or re-started, CodeRed Cloud actually loads these values from your Django instance and wires up a separate threaded HTTP server process to efficiently serve these files. Static and media files are stored on fast solid-state drives, and the URLs are cached in memory to further speed up requests. This process does not count against the number of workers in your hosting plan.

Note

Static and media files are served with a cache time-to-live of access time plus 7 days. If you are experiencing trouble due to this cache, contact our support for help.

Custom MIME Types#

If your static or media files require a custom MIME type to be served correctly, you can create a file in your www directory named mime.types. Thousands of common files extensions are already configured. However, unknown files are treated as text, which may cause rendering or download issues in the browser.

For example, to ensure that static or media files with the extension .custom are served as binary file downloads, create the following file named mime.types in the root of your Django or Wagtail project. Then deploy the project as normal for the change to take effect.

# Lines begining with # are comments.
# Serve files with extension `.custom` as binary octect streams.
application/octet-stream    custom

Sending Emails#

Most websites need to send emails, usually for password resets, admin notifications, etc. CodeRed provides a basic built-in email service for these purposes, using sendmail.

To use the CodeRed email service, set the EMAIL_BACKEND in your settings:

# Built-in email sending service provided by CodeRed Cloud.
# Change this to a different backend or SMTP server to use your own.
EMAIL_BACKEND = 'django_sendmail_backend.backends.EmailBackend'

Aside from convenience, another advantage to the CodeRed email sending service is that it logs every outgoing message, to help you troubleshoot and audit your website. Outgoing messages can be viewed via SFTP in the /log/cr-sendmail/ directory.

Review the email technical reference to learn how the CodeRed email sending service works under the hood.

Logging#

By default, WSGI request and error logs are located in the logs/wsgi/ directory (when accessed via SFTP).

If you would like to enable Django logging, or create custom logs, write those to file in /var/log/.

For details see Logging on CodeRed Cloud.