Migrating a Django Website to CodeRed Cloud#

This guide applies to any Django-based website, including Wagtail.

Before beginning, follow the pre-migration checklist.

Migrating from one host to another can sometimes be a tedious process — remember, CodeRed provides free migrations to all customers on the Professional plan and higher. If you’d like us to handle your migration for you, contact our support.

Step 1: Modify your Django settings for CodeRed#

Django apps on CodeRed cloud expect two specific settings files:

  • projectname/settings/prod.py for production settings.

  • projectname/settings/staging.py for staging site settings.

These two files must be at exact paths (replacing projectname with the folder containing your Django project — this folder will also contain a wsgi.py file).

The cr command line tool can automatically fix your current Django settings to work with CodeRed Cloud. Replace WEBAPP with your webapp’s handle:

$ cr check WEBAPP

After the command completes, you can skip to Step 2.

Alternatively, you can follow the steps below to manually adjust your settings file.

In the event that the project name of your Django Project does not match the handle of your webapp, you will need to set the custom name of your Django Project through your dashboard in the settings tab (e.g. the handle of my-app.codered.cloud would be my-app).

Normally we recommend creating a projectname/settings/base.py file which has common settings, and your staging.py and prod.py files will only contain a few specific settings.

An example prod.py and staging.py file might look like this, with the most basic required settings for CodeRed Cloud

import os
from .base import *  # noqa

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

DEBUG = False

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

SECRET_KEY = os.environ['RANDOM_SECRET_KEY']

# Add the STATIC_* and MEDIA_* lines below if not already defined in base.py.
# You may also change STATIC_* and MEDIA_* settings to some custom value, just
# make sure they are set for CodeRed cloud to serve them properly.
BASE_DIR = os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
STATIC_URL = '/static/'
STATIC_ROOT = os.path.join(BASE_DIR, 'static')
MEDIA_URL = '/media/'
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')

# 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'

# If using MySQL...
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',
        },
    }
}

# If using PostgreSQL...
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'},
    }
}

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

More detail on these settings can be found in our Django Environment documentation.

Step 2: Copy code and files to CodeRed#

Using the cr command line tool, upload your code to CodeRed Cloud:

$ cr upload WEBAPP

If you are migrating media files, and your media files were not included in the upload command above, you can also upload those by specifying the local and remote paths. The local path (--path) should be the media folder on your computer. The remote path (--remote) should be the directory referenced by MEDIA_ROOT in your Django settings (usually this will corredpond to /www/media/).

$ cr upload --path ./media/ --remote /www/media/ WEBAPP

Note that if you are uploading several gigabytes of media files, this may take a few hours to complete.

Alternatively, you can upload files manually using the SFTP instructions below.

Using SFTP, connect to your destination website on CodeRed Cloud and copy your code into the /www/ folder on the server. The www/ folder should mirror the appearance of your Django project code on your computer.

During the copy, you can omit some files that are unnecessary:

  • The .git/ folder on your computer.

  • Any __pycache__ folders on your computer.

  • Additional files used for development tooling, such as travis, tox, pytest, mypy, coverage, setup.cfg or pyproject.toml, etc.

There is no harm in copying any of these files, but they are ignored by CodeRed Cloud and are not needed on the server.

Note

Don’t forget to copy your requirements.txt file to the server! Without this file CodeRed will not recognize your app, and will instead create a new starter Django/Wagtail app.

Refer to our SFTP Guide for instructions on how to copy files using SFTP.

If you are uploading several gigabytes of media files, it may take several hours to finish uploading via SFTP. It is recommended to upload code and static files first (which usually takes under a minute), then upload media files last. You can continue this guide while the media files are uploading in the background.

Step 3: Obtain a database dump#

For this you will require database connection credentials for your current web host, and either the mysql/mysqldump or psql/pg_dump command line tools.

With the connection info, run the following commands to produce a text-based SQL dump of your database that is compatible with CodeRed’s database service.

$ mysqldump -p --user <user> --host <host> --hex-blob --result-file datadump.sql <database_name>

The MySQL and PostgreSQL commands above will output a file in the current directory named datadump.sql. This file is probably very large as it contains your entire database contents.

Step 4: Reset your CodeRed database#

Before loading in your existing database, your CodeRed database must first be wiped clean to start in an empty state.

Reset your website’s database by clicking the Database tab > Reset Production Database in the CodeRed dashboard.

Warning

This will totally destroy your entire database hosted on CodeRed and all data in it. Normally this is fine if you have not yet migrated your live site to CodeRed, but if you have any important data, be sure to back it up first.

Step 5: Import database dump to CodeRed#

Next you will load your datadump.sql file into your destination website.

Follow our Connect to Your CodeRed Database guide to connect to your CodeRed database.

$ cat datadump.sql | mysql -h <host> -user <user> -p <database_name>

Note

For MySQL: CodeRed only supports InnoDB engine. You may need to find/replace ENGINE=... with ENGINE=InnoDB in your SQL dump file before loading it into CodeRed. Older versions of MySQL/MariaDB used to default to ENGINE=MyISAM.

Step 6: Deploy#

Now that your code and database have both been loaded into the server, you are ready to deploy. This deploy action will create a fresh Python environment, and perform normal Django deployment tasks such as installing requirements.txt, running collectstatic, running migrate, and other tasks such as setting up your static and media file hosting.

To deploy from the command line, you can add the --no-upload option since we already uploaded the code in Step 2.

$ cr deploy --no-upload WEBAPP

Alternatively, you can deploy from the dashboard. In the CodeRed dashboard, click Deployment tab > Deploy Production. This process might take a few minutes the first time, however you will receive an email when the deployment is complete.

At this point, you may need to test and evaluate your website, to make sure the migration did not produce any errors. Common errors might be a result of a bad data dump/import, or a problem with the settings or requirements files.

Repeat the steps above to resolve any errors as necessary. Once you’re ready to “flip the switch” and fully move your live website over to CodeRed, proceed to step 7 below.

Step 7: DNS Update#

The final step is to make a DNS update to point your custom domain to your new CodeRed website. First ensure your website is running correctly and without errors at http://WEBAPP.codered.cloud/. If your site is running as expected, follow our Use a Custom Domain Name guide to connect your domain.