Installing Molly ================ Getting the Code ---------------- 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). Preparing your system --------------------- 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: * python-virtualenv * python-pip * libxml-devel * libxslt-devel * python-devel * postgresql-devel * openldap-devel * openssl-devel * postgis * gdal-python * proj * postgresql-server * geos * httpd * libjpeg-devel * imagemagick * gcc * make * git Configuring PostgreSQL ---------------------- .. 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 .. seealso:: `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 Creating your database ---------------------- .. 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 .. info:: This assumes that the Postgis template is called ``template_postgis``, which is the default and recommended value. 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: * ``-c``: Specifies the name of the created database user * ``-d``: Specifies the name of the database to create * ``-w``: Specifies the name of the password to use for the created database user 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. Creating a site template ------------------------ 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. Creating a Virtualenv for Molly ------------------------------- 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. Deploying Molly --------------- 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: * ``-s PATH``: The path to the site to deploy (i.e., the one created using the sitestart command above) * ``-i PATH``: The path of the virtualenv to install into. 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. Developing Molly ---------------- 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: * ``-p PORT``: The port which the development server should start on (defaults to 8000) * ``-x``: This indicates the development server should start on a port which is externally visible (for testing purposes only) Updating Molly -------------- To update Molly, you simply need to rerun the ``./setup.py deploy` command in the new Molly folder. This will recognise that the installation already exists and will update as appropriate.