Installing Molly ================ Preparing your system --------------------- .. warning:: CentOS 5 users should be aware that some of these dependencies are not in the default repositories. These dependencies live in the the `EPEL `_ and `RPMforge `_ third-party repositories, which you may need to install to satisfy these dependencies. In order to install Molly, there are several non-Python dependencies which are needed for Molly and its dependencies first. Fedora """""" .. code-block:: none su -c 'yum install python-pip libxml-devel libxslt-devel python-devel postgresql-devel openldap-devel openssl-devel gdal-python proj geos libjpeg-devel imagemagick gcc make git libyaml' CentOS """""" .. code-block:: none su -c 'yum install python-pip python26 python-setuptools python26-devel binutils libxslt-devel cyrus-sasl-devel openldap-devel ImageMagick proj proj-devel postgresql-devel postgresql-contrib geos-3.1.0 geos-devel-3.1.0 gdal libjpeg-devel make gcc openssl-devel libyaml-devel' Ubuntu/Debian """"""""""""" .. note:: Different versions of Ubuntu and Debian may include different versions of libgeos, libgdal and postgresql which changes the package name. The version below are for Ubuntu 10.04. .. code-block:: none sudo apt-get install python-pip build-essential python-gdal proj libgeos-3.1.0 binutils libgdal1-1.6.0 postgresql-server-dev-8.4 python-setuptools python-dev libxslt-dev libldap2-dev libsasl2-dev libjpeg-dev imagemagick libyaml .. note:: Versions below are for Ubuntu 10.11 .. code-block:: none sudo apt-get install python-pip build-essential python-gdal proj libgeos-3.2.2 binutils libgdal1-1.7.0 postgresql-server-dev-8.4 python-setuptools python-dev libxslt1-dev libldap2-dev libsasl2-dev libjpeg62-dev imagemagick python-yaml If your system isn't one of those listed above, then you will need to ensure the following packages, or their equivalent on your platform, are available: * libxml-devel * libxslt-devel * python-devel * postgresql-devel * openldap-devel * openssl-devel * gdal-python * proj * geos * libjpeg-devel * imagemagick * gcc * make Installing Molly ---------------- .. note:: When installing using pip or Git it is possible to install Molly in an isolated environment called a virtualenv, where Molly and its dependencies can be installed seperately from the system-wide Python packages. To do this, you simply need to install the virtualenv tool (``pip install virtualenv``) and then run ``virtualenv molly``, followed by ``source molly/bin/activate``. Once the virtualenv is activated, then you can install Molly using the directions below. Please note that Molly will only appear installed when the virtualenv is activated by running the activate script as indicated above. .. warning:: Please note that the Python 2.6 binary on CentOS 5 is called 'python26'. On CentOS, it is therefore recommended that you work in a virtualenv as detailed above. The virtualenv can be set to use Python 2.6 by creating it as ``virtualenv --python=/usr/bin/python26 molly``. Once the virtualenv is activated, ``python`` refers to version 2.6. Using pip or easy_install """"""""""""""""""""""""" .. note:: On Fedora, pip is called 'pip-python' to avoid a clash with Perl's pip You can install Molly directly from the Python Package Index (PyPI) using the pip or easy_install commands:: pip install molly From Git (latest development version) """"""""""""""""""""""""""""""""""""" To install the bleeding edge version of Molly, you can obtain Molly from our Git repository at git://github.com/mollyproject/mollyproject.git:: git clone git://github.com/mollyproject/mollyproject.git This will create a clone (local copy) of the full Molly source code repository in the folder called 'mollyproject' in the directory where you ran the command. To install Molly, you can now use the setup.py script inside the newly created 'mollyproject' directory:: python setup.py install If you intend on doing development work with Molly, you may prefer to use the development install facility which will allow you to work from your Molly repository without having to re-install after every code change:: python setup.py develop Setting up your database ------------------------ .. warning:: This is only intended as a quick introduction to configuring Postgres and may not be suitable for production environments. Molly recommends the use of the PostgreSQL database with the PostGIS extensions as a database backend. Installing Postgres """"""""""""""""""" On Ubuntu and Debian:: sudo apt-get install postgresql-8.4 postgresql-8.4-postgis On Fedora and CentOS:: su -c 'yum install postgresql postgresql-server postgresql-devel postgresql-contrib postgis' You may then need to start your new Postgres database, this can be done with:: sudo service postgresql start Once Postgres is created you must create a template database which can then be used to create the Molly database. This can be done by following the Creating a Spatial Database Template for PostGIS section in `the Geodjango documentation `_. Creating your database user """"""""""""""""""""""""""" .. warning:: This section assumes a default distribution install of Postgres, if you have changed the default security settings of Postgres, you may need to specify the ``-U username -W password`` options on the ``createuser`` command to authenticate as a superuser. In default installs of Postgres, database usernames must match local usernames in order to authenticate, therefore, the user created on the database should match the username of the user that Molly runs as. On most default installs, the 'postgres' user is a superuser on the database, and the ``createuser`` command should be run as this superuser:: sudo -u postgres createuser Please enter your local username when creating this user, and the user does not need to be a superuser or able to create new users (roles) or databases. If you have configured Postgres to require password authentication, the ``-P`` option should be specified:: sudo -u postgres createuser -P In this case, the username may not necessarily be the same as the local user. Creating your database for Molly """""""""""""""""""""""""""""""" .. warning:: This section assumes a default distribution install of Postgres, if you have changed the default security settings of Postgres, you may need to specify the ``-U username -W password`` options on the ``createdb`` and ``psql`` commands to authenticate as a superuser. As with the ``createuser`` command, the 'postgres' user is considered a superuser and commands should be run as this user. To create the database, assuming the PostGIS template was installed as ``template_postgis`` you can use:: sudo -u postgres createdb -T template_postgis Replacing with your database name. More information on postgis templates can be found in the `PostGIS documentation `_. And then you can give your user access to this new database:: sudo -u postgres psql -c "GRANT ALL ON DATABASE TO ;" Replacing and with your database and username respectively. 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 ``molly-admin createsite`` command will create a template site which you can then go and customise to your exact requirements:: This argument takes one argument which specifies the path to create the template in:: molly-admin createsite /PATH/TO/MY/SITE .. warning:: Don't call your site `site`. It will mess up Djangos with settings finder. 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. Running Celery -------------- .. versionadded:: 1.4 Molly now runs it's periodic tasks (e.g. importing map data from OpenStreetMap) by using the popular Distributed Task Queue, `Celery `_. Celery requires us to install a *message broker*, the most popular choice here is `RabbitMQ `_. There are other brokers available, as always we recommend reviewing the excellent Celery documentation to learn more. Molly's installation will have setup the celery worker, ``celeryd`` and task scheduler ``celerybeat`` for us. We just have to start them:: python manage.py celeryd python manage.py celerybeat .. seealso:: `Daemonizing Celery `_ -- Celery doesn't daemonize itself so you'll want to either run it as an init script or deploy it with some process management like `supervisor `_. Deploying Molly --------------- Once you have configured your site appropriately, you're almost ready to deploy your site! This can be done using the command:: python manage.py deploy 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. Starting a development server for Molly """"""""""""""""""""""""""""""""""""""" This can be done by adding the ``--develop`` command to the deploy command above:: python manage.py deploy --develop .. note:: Starting a development server also skips the updating Wurfl step, in order to speed up development Updating Molly -------------- To update Molly, you simply need to rerun the ``./setup.py install` command in the new Molly folder. This will recognise that the installation already exists and will update as appropriate.