Create Ticket
Warning Can't synchronize with repository "(default)" (Couldn't open Subversion repository /x1/svn/asf/bloodhound: SubversionException: ("Expected FS format between '1' and '4'; found format '6'", 160043)). Look in the Trac log for more information.
Last modified 5 weeks ago Last modified on Mar 19, 2014 3:47:21 AM

Installing Apache Bloodhound

For more detailled instructions, please see BloodhoundDetailedInstallation.

For common installation errors and misconfiguration issues , please see BloodhoundInstallTroubleshooting

General Prerequisites

As a base for installing Bloodhound, the rest of this document expects that you have the following installed on your system:

There are good guides available for installing each of the above on a number of operating systems including:

Modern linux distributions often already have the required packages available in their repositories:

  • For Debian (>= 5.0), Ubuntu (>= 9.4), Mint (>= 7) and other Debian or Ubuntu based systems, if you have admin access through sudo you can run
    sudo apt-get install python python-virtualenv
    
  • For Fedora (>= 11), Centos (>= 6.4), RHEL (>= 6.4) and other distributions that make use of yum you can try
    sudo yum install python python-virtualenv
    

Many other linux and *BSD distributions will have their own package management systems and repositories containing the appropriate packages.

Databases

Apache Bloodhound also requires a database and it supports the following popular databases: SQLite, PostgreSQL, and MySQL.

Easy Option: SQLite

Installing Apache Bloodhound with SQLite is the easiest option as Python comes with SQLite integrated into it. In addition, there are no special access rights required to create or interact with an SQLite database as it is stored in a local file. For larger production installations, SQLite may not be considered appropriate and lacks the possible advantage of using a separate server for the database.

Recommended Option: PostgreSQL

Installing with PostgreSQL is complicated by having to create users and a database on the server and adjusting permissions to allow access. It also adds the following dependencies:

As before, these are likely to be available on your distribution of Linux:

  sudo apt-get install postgresql python-psycopg2

Otherwise you should be able to download and find installation instructions from the above links. Alternatively it might be possible to install psycopg2 using pip but this can be expected to depend on tools to compile and build the code along with any required libraries.

Next you will need to add a user and database for bloodhound to use, making sure that the created user is able to access the database. For example:

  sudo su - postgres
  createuser --no-superuser --no-createdb --no-createrole --encrypted --pwprompt bloodhound
  createdb --owner=bloodhound --encoding=UTF-8 bloodhound
  logout

Notes for windows users:

  • you may need to specify the path to the createuser and createdb programs. For example with PostgreSQL 9.2 that would be:
    C:\Program Files\PostgreSQL\9.2\bin\createuser --no-superuser --no-createdb --no-createrole --encrypted --pwprompt bloodhound
    C:\Program Files\PostgreSQL\9.2\bin\createdb --owner=bloodhound --encoding=UTF-8 bloodhound
    
  • Both these commands should be expected to ask for the password you set for the postgres user, the first command asking for you to set a password for the new role first.

Permissions for database users on some systems may need to be altered - for example on ubuntu 11.10 you may find you need to do the following:

  sudo vi /etc/postgresql/9.1/main/pg_hba.conf

where you should change the line

  local   all             all                                     peer

to

  local   all             all                                     md5

and after saving, the database will need to be restarted

  sudo /etc/init.d/postgresql restart

If MySQL is your only choice

Note that the Installation Script does not yet allow for installing with a MySQL database.

Although MySQL is supported by Bloodhound, the likelihood of success may be expected to be dependent on the version of MySQL you are trying to use. The MySQL 5.0.x versions are recommended at this point but as this is investigated, further this page will be updated. For MySQL these instructions may work on Ubuntu 11.10 (currently using MySQL 5.1.61):

  sudo apt-get install mysql-client mysql-server
  mysql --user=root --password -e "CREATE DATABASE bloodhound DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;"
  mysql --user=root --password -e "GRANT ALL ON bloodhound.* TO bloodhound@localhost IDENTIFIED BY 'asecurepasswd';"

In the form specified above, the mysql commands will request a password which will be the password set on installing mysql. To change this password, you can run sudo dpkg-reconfigure mysql-server-5.1.

To continue the installation, refer to BloodhoundDetailedInstallation before continuing to the Testing the Server section below.

Installation

To install Bloodhound, the following steps represent the current recommended method:

  tar xvzf apache-bloodhound-<version number>.tar.gz
  cd apache-bloodhound-<version number>/installer
  virtualenv --system-site-packages bloodhound
  source ./bloodhound/bin/activate
  pip install -r requirements.txt

Then run the bloodhound_setup.py script:

  python bloodhound_setup.py

and answer the questions based on whether you chose to use SQLite or PostgreSQL. If you choose an SQLite installation, you should only have to specify a username and password to login to Bloodhound with once it is running. For PostgreSQL, the only extra questions will be to specify the database name, database user and the associated password.

In fact it is possible to specify all these details on the command line which also allows you to set additional options like the host for the PostgreSQL database and provide a different location for the installation. For more information on these options, run

  python bloodhound_setup.py --help

Notes for Windows users

*.tar.gz format is not natively supported by Windows. You have to use external utilities to extract apache-bloodhound-<version number>.tar.gz file. For example, you can use free utility 7-Zip for such purpose.

Amongst the other differences you should use

  bloodhound\Scripts\activate.bat

to activate the bloodhound environment then also skip the " source ./bloodhound/bin/activate" step in the installation instructions

Testing the Server

If the bloodhound_setup.py script completed successfully, you will be informed of the appropriate command to run the test server and the appropriate url to check. If you did not set any advanced options, you should find that you can start bloodhound using:

  tracd ./bloodhound/environments/main --port=8000

and you will be able to access Bloodhound on

  http://localhost:8000/main/

Remember that if you run tracd from a fresh shell, you will need to activate the virtual environment first and you should ensure that the path to the directory containing the environment is correct. An incorrect path to the environment will result in an "Environment not found" message, as will specifying the wrong environment name in the url.

Web Server

If you have managed to prove that you can run the system with the standalone tracd, you should now also be able to run through a web server. Here we provide details about how to use the Apache webserver. It is currently recommended to use Apache with mod_wsgi (libapache2-mod-wsgi) to serve Bloodhound. The following instructions require apache to be installed along with the wsgi and auth_digest modules.

It is possible to get the trac-admin command to reduce some of the work of creating the wsgi file

  source ./bloodhound/bin/activate
  trac-admin ./bloodhound/environments/main/ deploy ./bloodhound/site

You should also make sure that the appropriate modules are enabled for wsgi and htdigest authentication. On ubuntu this would be

  sudo a2enmod wsgi
  sudo a2enmod auth_digest

You will then need to create a site configuation for Apache. In ubuntu this can be done like this:

  sudo vi /etc/apache2/sites-available/bloodhound

Add to this something like (Note that /path/to/bloodhound means /path/to/apache-bloodhound-<version number>/installer/bloodhound) :

 <VirtualHost *:8080>
   WSGIDaemonProcess bh_tracker user=bloodhound python-path=/path/to/bloodhound/lib/python2.7/site-packages
   WSGIScriptAlias /bloodhound /path/to/bloodhound/site/cgi-bin/trac.wsgi
   <Directory /path/to/bloodhound/site/cgi-bin>
     WSGIProcessGroup bh_tracker
     WSGIApplicationGroup %{GLOBAL}
     Order deny,allow
     Allow from all
   </Directory>
   <LocationMatch "/bloodhound/[^/]+/login">
     AuthType Digest
     AuthName "Bloodhound"
     AuthDigestDomain /bloodhound
     AuthUserFile /path/to/bloodhound/environments/main/bloodhound.htdigest
     Require valid-user
   </LocationMatch>
 </VirtualHost>

The user referred to in the WSGIDaemonProcess should be the user that you wish bloodhound to be run as and so that user must have the appropriate set of permissions to access the Bloodhound installation. Running with any special system level privileges should not be required and is not recommended.

Then enable the new site, check the apache configuration and restart apache

  sudo a2ensite bloodhound
  sudo apachectl configtest
  sudo apachectl graceful

If that all worked, you will now be able to see Apache Bloodhound running on http://localhost:8080/bloodhound/

VC Repositories

Subversion

The python-subversion bindings are a pre-requisite. Note that the python-svn binding will not work. On Debian or Ubuntu based systems,

  sudo apt-get install python-subversion

On Fedora or Redhat based systems,

  sudo yum install python-subversion

Next, the SubversionConnector component must be enabled. This can be done through the web administration page, or by editing trac.ini:

  [components]
  tracopt.versioncontrol.svn.svn_fs.* = enabled

It should now be possible to add and synchronize repositories as described on the TracRepositoryAdmin page.

Git