In this part two types of installation will be covered: the standard one aimed for production and the development one, which target audience is the developer community.
After these steps you should have a PEER instance up and running but please note that many configuration defaults will not be good for your installation. It is recommended to read the Configuration chapter right after this one.
The minimum version of Python needed to run PEER is 2.6.
In the process of installing PEER, both in the standard installation and the development installation, it is necessary that some libraries already exist on your system. It is also needed the basic compiler chaintool and the development version of those libraries since the installation process compiles a couple of Python modules.
# Fedora example:
$ yum install python-devel libxml2-devel libxml2 libxslt-devel libxslt xmlsec1 xmlsec1-openssl postgresql-devel
$ yum groupinstall "Development Tools"
# Debian/Ubuntu example:
$ apt-get install build-essential python-dev libxml2-dev libxml2 libxslt1-dev libxslt1.1 xmlsec1 libxmlsec1-openssl libpq-dev
The standard installation is recommended for having a glimpse at the PEER application and also for real production deployment.
When installing a python application from the source you may put it in your system python site-packages directory running the standard python setup.py install dance but that is not recommended since it will pollute your system Python and make upgrades unnecessarily difficult. If the python application have some dependencies, as the PEER application has, things will become worse since you may have conflicts between the dependencies versions needed by the application and the versions installed on your system and needed by other applications.
Note
You should always install software using your Linux distribution packages. Python applications are not a exception to this rule. This documentation assumes that there is no PEER package yet in your Linux distribution or it is very out of date.
For all these reasons it is highly recommended to install the PEER application (any as a general rule, any Python application) in its own isolated environment. To do so there are a number of tools available. We will use virtualenv in this section and buildout in the Development installation section.
So first we will install virtualenv:
# Fedora example:
$ yum install python-virtualenv
# Debian/Ubuntu example:
$ apt-get install python-virtualenv
Check your distribution documentation if you do not use neither Fedora nor Ubuntu.
Now a new command called virtualenv is available on your system and we will use it to create a new virtual environment where we will install PEER.
$ virtualenv /var/www/peer --no-site-packages
The –no-site-packages option tells virtualenv to not depend on any system package. For example, even if you already have Django installed on your system it will install another copy inside this virtualenv. This improves the reliability by making sure you have the same versions of the dependencies that the developers have tested.
Note
We are using the system python and not a custom compiled one, which would improve the system isolation, because we are going to deploy the application with Apache and mod_wsgi and they depend on the system python.
In this step the PEER software and all its depenencies will get installed into the virtualenv that was just created in the previous step.
We first need to activate the virtualenv:
$ source /var/www/peer/bin/activate
This will change the PATH and some other environment variables so this will take precedence over your regular system python.
Now we can install the PEER software:
$ easy_install peer
After a while you will have a bunch of new packages inside /var/www/peer/lib/python2.6/site-packages/
The PEER application uses two types of storage:
PEER creates the repository where it stores the entities metadata automatically so you do not need to setup anything. However the relational database needs to be created and configured manually.
Being a Django project, the PEER application support several different types of SQL databases such as Postgresql, Mysql, Sqlite, Oracle, etc.
In this documentation we will cover the installation with a Postgresql database because it is the RDMS we recommend. Check the Django documentation to learn how to configure other database backends.
The first step is to install database server. It is recommended to use the packages for your Linux distribution:
# Fedora example:
$ yum install postgresql postgresql-server postgresql-libs
# Debian/Ubuntu example:
$ apt-get install postgresql postgresql-client
Check your distribution documentation if you do not use neither Fedora nor Ubuntu.
Now a database user and the database itself must be created. The easiest way to do this is to login as the postgres system user and creating the user with that account:
$ su - postgres
$ createuser peer --no-createrole --no-createdb --no-superuser -P
Enter password for new role: *****
Enter it again: *****
$ createdb -E UTF8 --owner=peer peer
With the previous commands we have created a database called peer and a user, which owns the database, called also peer. When creating the user the createuser command ask for a password. You should remember this password in a later stage of the installation/configuration process.
Now we need to configure Postgresql to accept database connections from the peer user into the peer database. To do so, we need to add the following directive in the pg_hba.conf file:
# TYPE DATABASE USER CIDR-ADDRESS METHOD
local peer peer md5
And restart the Postgresql server to reload its configuration:
$ service postgresql restart
Note
The location of the pg_hba.conf file depends on your Linux distribution. On Fedora it is located at /var/lib/pgsql/data/pg_hba.conf but in Ubuntu it is located at /etc/postgresql/8.1/main/pg_hba.conf being 8.1 the version of Postgresql you have installed.
To check that everything is correct you should try to connect to the peer database using the peer user and the password you assigned to it:
$ psql -U peer -W peer
Password for user peer:
psql (9.0.4)
Type "help" for help.
peer=#
Note
We have deliberately keep this postgresql installation super simple since we want to focus in the PEER software. If you are serious about puting this into production you may consider checking other Postgresql configuration settings to improve its performance and security.
Now we have to create the database tables needed by PEER but before we need to configure it to tell the database parameters needed to connect to the database. This will be described with more deails in the Configuration chapter.
Add the following information into the /var/www/peer/lib/python2.6/site-packages/peer-X.Y.Z-py2.6.egg/peer/local_settings.py file:
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql_psycopg2',
'NAME': 'peer',
'USER': 'peer',
'PASSWORD': 'secret',
'HOST': '',
'PORT': '',
}
}
Fill this dictionary with the appropiate values for your database installation, as performed in the previous step.
Note
The location of the local_settings.py file depends on the PEER version that you have. The path fragment peer-X.Y.Z-py2.6 is ficticious and will be something like peer-0.11.0-py2.6 in real life.
Then, activate the virtualenv:
$ source /var/www/peer/bin/activate
And run the Django syncdb command to create the database schema:
$ django-admin.py syncdb --settings=peer.settings --migrate
Note
The syncdb Django command will ask you if you want to create an admin user. You should answer yes to that question and write this admin’s username and password down. You will need them later. This administrator’s name should be admin because there are fixtures that depends on this name. You can create more administrators in the future with other names.
In this step you will collect all necessary static resources needed by PEER and put them in a single directory so you can serve them directly through your web server increasing the efficiency of the whole system.
The nice thing is that you don’t have to do this manually. There is a Django command just for that:
$ django-admin.py collectstatic --settings=peer.settings
You have requested to collect static files at the destination
location as specified in your settings file.
This will overwrite existing files.
Are you sure you want to do this?
Type 'yes' to continue, or 'no' to cancel: yes
The recommended way to serve a PEER site is with a real web server that supports the WSGI (Web Server Gateway Interface) protocol. This is no surprise since the same applies to Django.
If you use the Apache web server all you need to do is write the following configuration into your specific virtual host section:
WSGIScriptAlias / /var/www/peer/lib/python2.6/site-packages/peer-X.Y.Z-py2.6.egg/peer/peer.wsgi
Alias /static/ /var/www/peer/lib/python2.6/site-packages/peer-X.Y.Z-py2.6.egg/peer/static/
Note
Bear in mind that the exact path may be different in your case, specially the Python and PEER version numbers. The path fragment peer-X.Y.Z-py2.6 is ficticious and will be something like peer-0.11.0-py2.6 in real life.
The packages needed for installing Apache and wsgi support are:
# Fedora example:
$ yum install httpd mod_wsgi
# Debian/Ubuntu example:
$ apt-get install apache2 libapache2-mod-wsgi
Note
If you use someting different from Apache, please check the documentation of your web server about how to integrate it with a WSGI application.
Finally, you need to make sure that the user that the Apache run as has write access to the MEDIA directory of your PEER site. That directory is where the Git repository for the entities’ metadata is created and maintained.
# Fedora example:
$ chown apache:apache /var/www/peer/lib/python2.6/site-packages/peer-X.Y.Z-py2.6.egg/peer/media
# Debian/Ubuntu example:
$ chown www-data:www-data /var/www/peer/lib/python2.6/site-packages/peer-X.Y.Z-py2.6.egg/peer/media
Note
As mentioned before, the exact path may be different in your case, specially the Python and PEER version numbers. The path fragment peer-X.Y.Z-py2.6 is ficticious and will be something like peer-0.11.0-py2.6 in real life.
You can start by cloning the PEER repository, substituting <username> with your Github username:
$ git clone https://<username>@github.com/Yaco-Sistemas/peer.git
As in the standard installation we will create a virtualenv to isolate the system from the packages that the installation process is going to add.
You can read more about this in the Creating a virtualenv section. Just install virtualenv if you haven’t already done it:
# Fedora example:
$ yum install python-virtualenv
# Debian/Ubuntu example:
$ apt-get install python-virtualenv
And create the virtualenv in the same directory where you cloned the PEER repository:
$ cd peer
$ virtualenv . --no-site-packages
$ source bin/activate # don't forget to activate the virtualenv
Now we will create a buildout using the bootstrap script.
$ python bootstrap.py
$ bin/buildout
Note
Buildout is a Python package which purpose is to collect all the dependencies and configuration needed to run a software. It is not specific to Python software but obviously it is a good fit in those cases.
The bin/buildout command will take a while so you can create your database in the meantime. Check the Creating the database section of the standard installation to learn how to do it. By default the PEER software is expecting the database to be called peer and a user called peer to access that database with a password equal to peer. But of course you can configure PEER to use anything else.
As soon as you have the database created and the buildout command has finished you can populate the database to create the schema:
$ bin/django syncdb --migrate
And now you are ready to run the embedded Django server, which is perfectly fine for development purposes.:
$ bin/django runserver
Note
All traditional django-admin.py commands or manage.py commands are available in the builoudt as bin/django commands.
It is also recommended that you activate DEBUG mode in your configuration file. We will see how to do that in the next chapter, Configuration.