Molly extends the standard setup.py in order to add additional functionality to make working with Molly easier.
First off, you will need a checkout of Molly. You can either grab a tarball from the Downloads part of Github, and unzip that:
wget --no-check-certificate https://github.com/mollyproject/mollyproject/tarball/master
tar zxvf https://github.com/mollyproject/mollyproject/tarball/master
Or clone the Git repository directly:
git clone git://github.com/mollyproject/mollyproject.git
(note that you may have to install Git for this to work)
The links above will get the latest “unstable” version of Molly, you may wish to select a specific version from the download page, or checkout a specific branch from Git (e.g., git checkout molly1.2).
Molly requires some system library and packages to be installed in order to function correctly. If you are on CentOS 5, Fedora, Ubuntu 10.04 or 10.10, then running ./setup.py sysprep as root will automatically install these dependencies for you.
Warning
CentOS 5 users should be aware that some of these dependencies are not in the default repositories. In order to satisfy these dependencies, Molly will add the EPEL and RPMForge repositories to your system. If this is not what you want, then you must ensure the requirements are satisfied manually.
If your system isn’t one of those supported, then you will need to ensure the following packages, or their equivalent on your platform, are available:
Warning
The following installation instructions are unlikely to be suitable for production databases. Experienced DBAs will want to skip this section.
Molly requires Postgis to be installed into the database in order to work correctly. A convenience script is included in Molly to create such a database on supported platforms (Ubuntu, Fedora and CentOS):
./setup.py dbprep --create-template
This script expects to be able to access the database as a super user. You can either do this by running the script as a user which has superuser access to the database (e.g., the postgres user on many systems), or by specifying a superuser name and password on the command line which will be used to authenticate to Postgres, e.g.,:
./setup.py dbprep --create-template -u admin -p admin
See also
The Django documentation contains information on how to create a spatial database template by hand, if you would like to do it that way.
Warning
The next step will override your existing pg_hba.conf and may break an existing PostgreSQL installation. It is recommended you do this only on a new, blank installation, and when Molly is the only user of the database.
Many Linux distributions’ default configuration for Postgres are not immediately usable by Molly - typically, they are not configured to allow users to connect to the database by password authentication. Molly includes a convenience function to create a pg_hba.conf which includes a default security configuration for Molly to access the database. If you already have a working Postgres database, or want to configure security by hand, then skip this step:
sudo ./setup.py dbprep --configure-security
Note
The function described below is simplistic and experienced DBAs may prefer creating the database and permissions by hand. If you choose to do so, then ensure you create the database for Molly from a Postgis template.
Warning
This will delete any database called molly that already exists and change the password of any user called molly which exists.
As a convenience function, Molly provides a command to automatically create a database user and database for Molly to use:
./setup.py dbcreate
By default, if running as a superuser, this will create a database called molly and a user called molly which has access to this database. A randomly generated password is used, which is shown to you at the end of the script (you will need to enter this into your settings.py, so make a note of it). In order to customise the username, database name or password used, then the following options can be used:
As with the dbprep command, this can also take superuser credentials which are used to run these commands, if the current user doesn’t have credentials.
Molly has the distinction between the core of Molly, and a Molly site. The core of Molly is the upstream Python package and associated data, whereas a site is a Django project which contains your settings for Molly, as well as any media, templates and other customisations to the Molly core. In order to get started with Molly, you will need to create a site.
The sitecreate command will create a template site which you can then go and customise to your exact requirements. This site folder is used as an argument to the deploy command to tell Molly which site to deploy.
This argument takes one option, -s, which specifies the path to create the template in:
./setup.py sitecreate -s /PATH/TO/MY/SITE
Once your site template has been created, the following files are created which are only templates and require you to edit them:
- settings.py - following the configuration guide;
- apache/molly.wsgi - if you are deploying Molly as a WSGI app, then you will need to change the DJANGO_SETTINGS_MODULE setting in this file;
- apache/httpd.conf - this is a sample Apache config file;
- templates/base.html - this is a sample template override - for more information about this, please see the customising guide.
You will also have a compiled_media folder, which should be ignored, and a site_media folder, which is where you should put any overrides for media on your site.
Molly operates from a virtualenv, which allows for specific dependencies to be tracked without interfering with your system-wide Python installation.
Note
If you have virtualenvwrapper installed, Molly will use that to create your virtualenv.
In order to create your virtualenv, the command ./setup.py createvirtualenv can be used. This command takes one compulsory argument, -i PATH, which specifies the path to create the virtualenv in.
Once you have configured your site appropriately and created a Virtualenv for Molly to be installed into, you’re almost ready to deploy your site!
This can be done using the command ./setup.py deploy. This command takes a number of compulsory arguments:
You now have an install of Molly ready to serve to the world. The recommended way of doing this is by using Apache and mod_wsgi. The site template created by the installer consists of a WSGI script and a sample Apache config in the apache/ directory of your site.
The mod_wsgi documentation goes into considerable detail about how to deploy a Django application.
In order to support developing Molly, the following option -d is available on ./setup.py deploy. This will install Molly and your site in a development mode and start Django’s development server. In this mode, changes to your CSS, images and JavaScript will be immediately shown without having to re-run the deploy command, and any time any Python code is changed, this is automatically reloaded.
In this mode, Molly and your site are run from their source locations, not their installed locations, so you can edit them in-place and see the results immediately in the development server. Additionally, verbose logging output is printed to stdout, which allows you to debug an issues that are occurring with Molly.
A number of additional options are available here too: