Knowledge Base

How to install and configure Mezzanine on a shared hosting account

Mezzanine is a Python-based CMS (content management system) that runs on top of the Django framework. This article demonstrates how to install Mezzanine on a shared hosting account using virtualenv and pip, as well as how to configure and run a Mezzanine project using FastCGI.

Installing Mezzanine

Before you can install Mezzanine, you must first create a virtual environment for Python by using the virtualenv tool. After you activate the virtual environment, you can use the pip installer to install Mezzanine and Django, as well as a database engine.

To install Mezzanine, follow these steps:

  1. Log in to your account using SSH.
  2. To create and activate the virtual environment, type the following commands:
    cd ~
    virtualenv -p /usr/bin/python2.7 mezzenv
    source mezzenv/bin/activate
    
    These commands create a virtual environment named mezzenv, and subsequent commands in this article assume that the environment is named mezzenv. If you use a different environment name, make sure you replace all occurrences of mezzenv with your own environment name.
  3. To install Mezzanine and Paste, type the following command:

    pip install mezzanine==3.1.9 flup paste
    • The mezzanine package also installs Django automatically. Mezzanine 4.0.1 and later versions, however, install Django 1.9, which does not include FastCGI support. Therefore, you must install Mezzanine 3.1.9 on shared hosting servers.
    • The flup and paste packages include several tools for running WSGI (Web Server Gateway Interface) applications.
  4. The SQLite database engine is installed by default. If you want to use the MySQL database engine instead, type the following command:

    pip install MySQL-python
  5. Mezzanine is now installed and ready to be configured.

Configuring Mezzanine

You have installed Mezzanine, but it will not run on your web site until you complete some additional steps. You must create a Mezzanine project, as well as configure FastCGI to run the project. To do this, follow these steps:

  1. To create a Mezzanine project, type the following commands:
    cd ~/public_html
    mezzanine-project mezzcms
    
    These commands create a project named mezzcms, and subsequent commands and settings in this article assume that the project is named mezzcms. If you use a different project name, make sure you replace all occurrences of mezzcms with your own project name.
  2. Type the following command:

    cd ~/public_html/mezzcms
    
  3. Use a text editor to edit the database settings in the /home/username/public_html/mezzcms/settings.py file:

    • Django includes SQLite support by default. To use SQLite, locate the DATABASES section in the settings.py file, and then make the following changes:
      "ENGINE": "django.db.backends.sqlite3",
      "NAME": "mezzcms.db",
    • To use MySQL instead, locate the DATABASES section in the settings.py file, and then make the following changes. Replace the username_databasename, username_dbusername, and user_password values with the correct values for your MySQL database:

      "ENGINE": "django.db.backends.mysql",
      "NAME": "username_databasename",
      "USER": "username_dbusername",
      "PASSWORD": "user_password",
      "HOST": "localhost",
      "PORT": "3306",
  4. In the settings.py file, modify the following setting:

    ROOT_URLCONF = "mezzcms.urls"
    
  5. Save the changes to the settings.py file and exit the editor.
  6. At the command prompt, type the following command:

    python manage.py createdb
    
  7. When you are prompted to create a site record, type your domain name, and then press Enter.
  8. At the Username prompt, type the administrator username, and then press Enter.
  9. At the Email address prompt, type the administrator e-mail address, and then press Enter.
  10. At the Password prompt, type the administrator password, and then press Enter.
  11. To install demonstration pages, type yes and then press Enter.
  12. At the command prompt, type the following command:

    python manage.py collectstatic
    
  13. When you are asked if you want to overwrite existing files, type yes and then press Enter.
  14. Type the following command:

    cd ~/public_html
  15. In the public_html directory, create a file named application.fcgi that contains the following lines. Replace all occurrences of username with your own account username:

    #!/home/username/mezzenv/bin/python
    
    # Set up the virtual environment:
    import os, sys
    os.environ.setdefault('PATH', '/bin:/usr/bin')
    os.environ['PATH'] = '/home/username/mezzenv/bin:' + os.environ['PATH']
    os.environ['VIRTUAL_ENV'] = '/home/username/mezzenv/bin'
    os.environ['PYTHON_EGG_CACHE'] = '/home/username/mezzenv/bin'
    os.chdir('/home/username/public_html/mezzcms')
    
    # Add a custom Python path.
    sys.path.insert(0, "/home/username/public_html/mezzcms")
    
    # Set the DJANGO_SETTINGS_MODULE environment variable to the file in the
    # application directory with the db settings etc.
    os.environ['DJANGO_SETTINGS_MODULE'] = "mezzcms.settings"
    
    from django.core.servers.fastcgi import runfastcgi
    runfastcgi(method="threaded", daemonize="false")
    
    
  16. At the command prompt, type the following command to set the correct file permissions for the application.fcgi file:

    chmod 755 ~/public_html/application.fcgi
  17. Create an .htaccess file in the public_html directory that contains the following lines:

    AddHandler fcgid-script .fcgi
    RewriteEngine on
    # Set up static content redirect:
    RewriteRule static/(.+)$ mezzcms/static/$1
    # The following two lines are for FastCGI:
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^(.*)$ application.fcgi/$1 [QSA,L]
    
  18. Use your browser to go to http://www.example.com, where example.com represents your domain name. You should see the Mezzanine Congratulations home page. To log in to the administration interface, use the superuser credentials that you specified in steps 8 and 10.

    If the web site does not appear in your browser or you receive an error message, try running the application.fcgi file manually. To do this, type the following command:

    python ~/public_html/application.fcgi
    

    You should see a Status: 200 OK message, as well as HTML output. If there are any error messages, check the syntax in the configuration files.

More Information