Deployment

Deployment of a Mezzanine site to production is mostly identical to deploying a regular Django site. For serving static content, Mezzanine makes full use of Django’s staticfiles app. For more information, see the Django docs for deployment and staticfiles.

Fabric

Each Mezzanine project comes bundled with utilities for deploying production Mezzanine sites, using Fabric. The provided fabfile.py contains composable commands that can be used to set up all the system-level requirements on a new Debian based system, manage each of the project-level virtual environments for initial and continuous deployments, and much more.

Server Stack

The deployed stack consists of the following components:

Note

None of the items listed above are required for deploying Mezzanine, they’re simply the components that have been chosen for use in the bundled fabfile.py. Alternatives such as Apache and MySQL will work fine, but you’ll need to take care of setting these up and deploying yourself. Consult the Django documentation for more information on using different web and database servers.

Configuration

Configurable variables are implemented in the project’s local_settings.py module. Here’s an example, that leverages some existing setting names:

FABRIC = {
    "DEPLOY_TOOL": "rsync",  # Deploy with "git", "hg", or "rsync"
    "SSH_USER": "server_user",  # VPS SSH username
    "HOSTS": ["123.123.123.123"],  # The IP address of your VPS
    "DOMAINS": ["example.com"],  # The domain(s) used by your site
    "REQUIREMENTS_PATH": "requirements.txt",  # Project's pip requirements
    "LOCALE": "en_US.UTF-8",  # Should end with ".UTF-8"
    "DB_PASS": "",  # Live database password
    "ADMIN_PASS": "",  # Live admin user password
    "SECRET_KEY": SECRET_KEY,
    "NEVERCACHE_KEY": NEVERCACHE_KEY,
}

Commands

Here’s the list of commands provided in a Mezzanine project’s fabfile.py. Consult the Fabric documentation for more information on working with these:

  • fab all - Installs everything required on a new system and deploy.
  • fab apt - Installs one or more system packages via apt.
  • fab backup - Backs up the project database.
  • fab create - Creates the environment needed to host the project.
  • fab deploy - Deploy latest version of the project.
  • fab install - Installs the base system and Python requirements for the entire server.
  • fab manage - Runs a Django management command.
  • fab pip - Installs one or more Python packages within the virtual environment.
  • fab psql - Runs SQL against the project’s database.
  • fab python - Runs Python code in the project’s virtual environment, with Django loaded.
  • fab remove - Blow away the current project.
  • fab restart - Restart gunicorn worker processes for the project.
  • fab restore - Restores the project database from a previous backup.
  • fab rollback - Reverts project state to the last deploy.
  • fab run - Runs a shell comand on the remote server.
  • fab secure - Minimal security steps for brand new servers.
  • fab sudo - Runs a command as sudo on the remote server.

Tutorial

CASE 1: Deploying to a brand new server

  1. Get your server. Anything that grants you root access works. VPSes like those from Digital Ocean work great and are cheap.
  2. Fill the FABRIC settings in local_settings.py as shown in the Configuration section above. For SSH_USER provide any username you want (not root), and the fabfile will create it for you.
  3. Run fab secure. You simply need to know the root password to your VPS. The new user will be created and you can SSH with that from now on (if needed). For security reasons, root login via SSH is disabled by this task.
  4. Run fab all. It will take a while to install the required environment, but after that, your Mezzanine site will be live.

Notice that not even once you had to manually SSH into your VPS. Note: some server providers (like Digital Ocean) require you to login as root once to change the default password. It should be the only time you are required to SSH into the server.

CASE 2: Deploying to an existing server

If you already have a server, and you already have created a non-root user with sudo privileges:

  1. Fill the FABRIC settings in local_settings.py as shown in the Configuration section above. For SSH_USER provide the user with sudo privileges.
  2. Run fab install to install system-wide requirements.
  3. Run fab deploy to deploy your project.

Deploying more than one site to the server

After you have completed your first deployment, for all subsequent deployments in the same server (either new sites or updates to your existing sites) you only need to run fab deploy.

Fixing bugs pushed by accident to the server

  1. Run fab rollback. This will roll back your project files, database, and static files to how they were in the last (working) deployment.
  2. Work on the fixes in your development machine.
  3. Run fab deploy to push your fixes to production.