How to install Akvo RSR
From Akvo Labs
Contents |
Notes before you start using this document
We are working on this to make it up to date and easy to use. But we know it isn't ready yet. For example, you need initial data in the database for groups and permissions to work correctly. We haven't provided this, but we will Any Time Soon Now (tm). Further more, static_project_structure.py is essential that it is set up correctly, but it is not really documented properly how to do this. This will come as well soon.
That said, please don't hesitate to Contact us to get help with any questions you may have.
About this document
This document describes how to install the dependencies of the component of the Akvo platform on a Debian-based Linux system.
This document is open, anyone can edit it, so please help us improve it if you can.
Akvo RSR system requirements
The reference platform is Ubuntu Hardy (8.04), however it will also work on Debian systems as from Lenny (5.0). We have only tried this on Intel x86 architecture.
Installing Ubuntu Server
We recommend using the Ubuntu Server Guide to install Ubuntu on the server you are going to use for Akvo RSR. When you are installing the server you probably want to select the pre-packaged LAMP server, Mail server and SSH server.
System components
Although Django, the Python web framework used to build Akvo RSR, supports several SQL database engines, Akvo RSR requires that we use MySQL since other components of the Akvo platform only work with MySQL.
The components we recommend are:
- Ubuntu Hardy (8.04)
- Apache 2.0
- Memcached
- Python 2.4 or higher
- Django 1.2.3
Installation of required components
To install the required components you need root or sudo access to the server which will be running Akvo RSR.
Installing Apache web server
We use Apache as the web server and mod_python to handle running the Python code.
The following commands install both Apache and MySQL and their respective Python bindings:
$ sudo apt-get install apache2 libapache2-mod-python $ sudo apt-get install mysql-server python-mysqldb
Installing memcached
Akvo RSR uses memcached for caching purposes. This also needs to be installed.
$ sudo apt-get install memcached
The Python bindings for memcached, python-memcached, are fetched and installed automatically by the pip-requirements.txt file described later in this document.
Installing Python modules
Python itself is probably already installed on your system. Akvo RSR requires Python 2.4 or higher. Ubuntu 8.04 LTS (Hardy Heron) will show something like the following output:
$ python Python 2.5.2 (r252:60911, Jul 22 2009, 15:33:10) [GCC 4.2.4 (Ubuntu 4.2.4-1ubuntu3)] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>>
Although Akvo RSR itself is run from within a virtual Python environment, or virtualenv, several required Python modules are best installed system-wide or are simply easier to install this way. Some of the latter can be installed using apt-get, however others are best installed using the easy_install command, part of the python-setuptools package on Debian systems, which may not be installed on your system.
Note that when using easy_install, it is perhaps advisable to install into the /usr/local filesystem hierarchy in order to cleanly separate system- and user-installed software. This is, however, merely a convention.
$ sudo apt-get install python-setuptools $ sudo apt-get install python-imaging $ sudo easy_install -U --prefix=/usr/local pip virtualenv
Installing Git and Mercurial
The Git and Mercurial SCMs are used to fetch several Python modules during the setup of the Akvo RSR virtualenv. Git is used to fetch the Akvo RSR source code itself.
$ sudo apt-get install git-core $ sudo apt-get install build-essential $ sudo easy_install -U --prefix=/usr/local Mercurial
The Akvo RSR virtual environment
First of all decide where you'd like the isolated Python environment to live and what you would like to call it. In the following command sequence, we create a virtualenv called akvo within the directory /var/django.
Akvo will have provided you with a file called pip-requirements.txt which contains installation directives for all the Python modules required to run Akvo RSR. Save this somewhere on your server, for example /var/django/pip-requirements.txt
$ sudo mkdir /var/django $ cd /var/django $ virtualenv akvo $ pip install -E akvo -r pip-requirements.txt
QUESTION XXX: When to get Akvo RSR from github? We refer to Akvo RSR as if we have installed it already here, but it isn't actually downloaded until the section Deploying below. Bjelkeman 11:59, 2 September 2010 (CEST)
Currently pip-requirements.txt looks like this (Akvo RSR 0.9.19):
# Django Django==1.2.3 # Django Apps django-paypal -e git+git://github.com/peeb/django-mollie-ideal.git#egg=mollie -e hg+http://bitbucket.org/ubernostrum/django-registration/#egg=django-registration django-rosetta sorl-thumbnail template_utils django-piston django-counter # Other Python Modules BeautifulSoup Cython FeedParser python-memcached PIL lxml MySQL-python
NOTE: It is important to manually create the akvo virtualenv before running the pip command. The final command above would technically, by itself, create a new akvo virtualenv if none already existed, however, it would not link in the Python site packages already installed on the system, some of which are required to run Akvo RSR. Running the virtualenv command without options creates a new virtual environment which does have access to the system's site packages.
Because the final pip command above relies on being able to fetch various Python packages from around the Internet, it is possible, if there are any connectivity problems, that it may fail. If so, simply run it again until it completes successfully. pip is designed in such a way that it will not attempt to install any packages until all packages have been successfully downloaded.
Configuring Apache
Because Akvo RSR is run from a virtual Python environment, we need to do a little bit of extra work to tell mod_python how to handle this.
Go to the bin directory of the newly-created virtual environment and create a new file called akvo_modpython.py as follows:
$ cd /var/django/akvo/bin $ touch akvo_modpython.py
Now open this file with the editor of your choice and copy and paste in the following Python code:
import os activate_this = os.path.join(os.path.dirname(__file__), 'activate_this.py') execfile(activate_this, dict(__file__=activate_this)) from django.core.handlers.modpython import handler
This essentially acts as a wrapper around the system mod_python and simply allows us to point Apache to our virtualenv instead of the system Python.
Now we are ready to write a configuration directive for Apache. The finer points of Apache configuration are far beyond the scope of this document and, indeed, how you choose to integrate Akvo RSR into your existing web platform and domain namespace is also entirely up to you.
Akvo RSR requires a Location stanza such as the following in your Apache configuration file:
<LocationMatch ^/$>
SetHandler python-program
PythonPath "['/var/django/akvo/bin', '/var/django/rsr'] + sys.path"
PythonHandler akvo_modpython
SetEnv DJANGO_SETTINGS_MODULE akvo.settings
PythonDebug On
</LocationMatch>
<Location /rsr>
SetHandler python-program
PythonPath "['/var/django/akvo/bin', '/var/django/rsr'] + sys.path"
PythonHandler akvo_modpython
SetEnv DJANGO_SETTINGS_MODULE akvo.settings
PythonDebug On
</Location>
Alias /rsr/media /var/www/rsr/akvo/mediaroot/
<Directory /var/www/rsr/akvo/mediaroot/>
Options Indexes FollowSymLinks MultiViews
AllowOverride None
Order Allow,Deny
Allow from All
</Directory>
<Location "/rsr/media">
SetHandler None
</Location>
Note that in this example we are using the akvo_modpython.py handler in the /var/django/akvo virtualenv we created earlier.
The path /var/django/rsr refers to where we will make a checkout of the actual Akvo RSR codebase. This should remain separate from the virtual Python environment used to run it. We will revisit this and cover the configuration of Akvo RSR in the next section "Deploying Akvo RSR".
Deploying Akvo RSR
A complete Akvo platform site is built using four components: Akvo RSR itself, a Django project; the Akvopedia run on Mediawiki; the blog, run on Wordpress; and finally the content management system Drupal for general text based content.
The system has been tested to run on Ubuntu or Debian linux. Other versions of linux should work too, but may need modification of the set-up from the following.
Mediawiki
to be added
Wordpress
Download Wordpress (http://wordpress.org/download/) and set it up in /news (see http://codex.wordpress.org/Installing_WordPress). To get the Akvo theme for Wordpress clone from github like so:
git clone git://github.com/pvw/pvw-wp.git pvw
while standing in the themes directory of Wordpress (wordpress/wp-content/themes)
Drupal
Download Drupal and install following the instructions on the Drupal site. Get a clone of the Akvo theme for Drupal:
git clone git://github.com/pvw/pvw-pal.git pvw
Place it in the Drupal themes directory (drupal/themes).
For the PvW installation we have provided a "skeleton" structure for Drupal that can be found XXX here TBD XXX. When Drupal has been set up, drop all tables in the DB and run the SQL script to set it up.
Akvo RSR
Akvo RSR is also cloned from github:
git clone git://github.com/akvo/akvo-rsr.git /var/django/rsr
This puts it in the directory specified in the apache config above. Change as needed.
static_project_structure.py
When Akvo RSR has been checked out some configuring is needed. Find rsr/scripts/deployment/static_project_structure.py.template. Edit the paths to conform to your setup and save in the same dir as static_project_structure.py. Example following setup above:
# Akvo RSR is covered by the GNU Affero General Public License. # See more details in the license.txt file located at the root folder of the Akvo RSR module. # For additional details on the GNU license please see < http://www.gnu.org/licenses/agpl.html >. # The following values describe the static project structure for RSR import django, os PROJECT_ROOT_DIR = os.path.realpath(os.path.join(os.path.dirname(__file__), '..', '..')) PROJECT_ROOT_DIR_NAME = PROJECT_ROOT_DIR.split(os.sep)[-1] STATIC_DIR = os.path.realpath(os.path.join(PROJECT_ROOT_DIR, '../static')) MEDIAROOT_DIR = os.path.join(PROJECT_ROOT_DIR, 'akvo/mediaroot') # Configurable paths for the static directory STATIC_AKVO_DESTINATION = os.path.join('..', PROJECT_ROOT_DIR_NAME, 'rsr') STATIC_AKVO_VIRTUALENV_DESTINATION = '/var/django/rsr' STATIC_DB_DIR_IS_LINK = True STATIC_DB_DESTINATION = '/var/www/rsr/db' STATIC_DJANGO_DESTINATION = os.path.join(django.__path__[0]) # Configurable paths for the mediaroot directory and settings.py file SETTINGS_FILE_DESTINATION = '../../static/settings.py' STATIC_DIR_RELATIVE_TO_MEDIAROOT = '../../../static' MEDIAROOT_ADMIN_DESTINATION = os.path.join(STATIC_DJANGO_DESTINATION, 'contrib/admin/media') MEDIAROOT_DB_DESTINATION = os.path.join(STATIC_DIR_RELATIVE_TO_MEDIAROOT, 'db') # Configurable paths for the akvo web directory WEB_DIR = '/var/www/rsr' WEB_DB_DIR = os.path.join(WEB_DIR, 'db') WEB_MEDIAROOT_DESTINATION = os.path.join(STATIC_DIR, 'akvo/mediaroot')
STATIC_DB_DESTINATION points to the root of the upload directory structure. All images uploaded to projects etc are stored here and may be served independently from the Akvo RSR code.
When static_project_structure.py is saved with your configuration needs it is run with
verify_static_project_structure.py static_project_structure.py
This sets up the symlinks Akvo RSR needs.
settings.py
Next find and edit rsr/scripts/deployment/settings.py.template. You only need to edit the top part of it. When done save it as settings.py to the static folder.
# Akvo RSR is covered by the GNU Affero General Public License. # See more details in the license.txt file located at the root folder of the Akvo RSR module. # For additional details on the GNU license please see < http://www.gnu.org/licenses/agpl.html >. # Django settings for akvo project. # The main part of settings is in settings_base.py that is loaded here # In settings.py we keep server-specific settings from settings_base import * DATABASE_ENGINE = 'mysql' # 'postgresql_psycopg2', 'postgresql', 'mysql', 'sqlite3' or 'oracle'. DATABASE_NAME = 'rsrdb' # Or path to database file if using sqlite3. DATABASE_USER = 'rsruser' # Not used with sqlite3. DATABASE_PASSWORD = 'set-a-good-pwd' # Not used with sqlite3. DATABASE_HOST = # Set to empty string for localhost. Not used with sqlite3. DATABASE_PORT = # Set to empty string for default. Not used with sqlite3. #TEST_RUNNER = 'test_runner.run_tests' DEBUG = False SITE_ID = 1 LIVE_EARTH_ENABLED = False LIVE_EARTH_ID = 143 DOMAIN_NAME = 'www.domain.org' DEFAULT_FROM_EMAIL = 'noreply@%s' % DOMAIN_NAME # Absolute path to the directory that holds media. # Example: "/home/media/media.lawrence.com/" MEDIA_ROOT = '/var/www/rsr/akvo/mediaroot/' WORDPRESS_NEWS_CATEGORY = 3
See the Django documentation for common settings values. LIVE_EARTH_* are currently only for use with Akvo-RSR. Set WORDPRESS_NEWS_CATEGORY to the category number in Wordpress that you want to be displayed on the home page News banner.
