Create Ticket
Warning Can't synchronize with repository "(default)" (Couldn't open Subversion repository /x1/svn/asf/bloodhound: SubversionException: 13 - Can't open file '/x1/svn/asf/bloodhound/format': Permission denied). Look in the Trac log for more information.
Last modified 6 months ago Last modified on Feb 9, 2015 6:28:16 PM

Installing Apache Bloodhound

For more detailed instructions, please see BloodhoundDetailedInstallation.

For common installation errors and misconfiguration issues , please see BloodhoundInstallTroubleshooting

Preparation

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, as SQLite stores the database as a local file, there is no special configuration that is required.

The SQLite backend is therefore particularly suited to basic evaluation of Apache Bloodhound and perhaps for smaller production deployments. Note in particular that as a serverless database you will not be able to run this database on a separate server.

Recommended Option: PostgreSQL

Using PostgreSQL as the DB backed adds the following dependencies:

Prior to the main installation, of these we only expect PostgreSQL itself to be installed and psycopg2 will be installed with pip which builds psycopg2 from source.

For Debian, Ubuntu and similar you should install:

  sudo apt-get install postgresql python-dev libpq-dev

and on Fedora, RHEL, CentOS and similar:

  sudo yum install postgresql python-devel libpqxx-devel

Otherwise you should be able to download and find installation instructions from the above links.

Next you should create a database user and the bloodhound 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

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.

Users and file locations

Finally we will create a user who we will use to install and subsequently run Bloodhound with:

  sudo useradd --system -m bloodhound

The rest of the installation instructions will assume that this user exists. It is perfectly possible to run Bloodhound under a normal user account. There should be no need to run as the root user.

Also note that we will be using the /opt/bloodhound directory as a place for much of the installation so we'll create that:

  sudo mkdir -p /opt/bloodhound
  sudo chown bloodhound:bloodhound /opt/bloodhound

Installation

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

First download Bloodhound by finding the source package from this link: http://www.apache.org/dyn/closer.cgi/bloodhound/. Move this to somewhere that the bloodhound user has access, set the ownership to bloodhound and prepare to extract:

  sudo mv apache-bloodhound-<version number>.tar.gz /home/bloodhound
  sudo chown bloodhound:bloodhound /home/bloodhound/apache-bloodhound-<version number>.tar.gz
  
  sudo su bloodhound -
  cd /home/bloodhound

Extract the file, change to the installer directory, create the python virtualenv, activate it and install the python packages (if you are using MS Windows check the notes below)

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

If you are installing to PostgreSQL, you also need to run:

  pip install -r pgrequirements.txt

Then run the bloodhound setup script. You may wish to specify a different value for the default-product-prefix to make it meaningful for your projects.

  python bloodhound_setup.py --environments_directory=/opt/bloodhound/environments --default-product-prefix=DEF

This will take you through a few basic questions about your choice of database, the db username and password if you didn't choose SQLite, and lastly an admin username and password to use to login to the website once everything is up and running.

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, change the 'project' directory under the environments directory and various other things. 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.
  • to do the equivalent of creating and activating your virtualenv you will need to Amongst the other differences you should use something like
      virtualenv C:\path\to\bhenv
      C:\path\to\bhenv\Scripts\activate.bat
    

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. For the options specified above, this should be:

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

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 change to the bloodhound user and activate the bhenv virtualenv first. Also note that when running tracd, 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. Again, as the bloodhound user:

  source /opt/bloodhound/bhenv/bin/activate
  trac-admin /opt/bloodhound/environments/main/ deploy /opt/bloodhound/environments/main/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:

 <VirtualHost *:8080>
   WSGIDaemonProcess bh_tracker user=bloodhound python-path=/opt/bloodhound/bhenv/lib/python2.7/site-packages
   WSGIScriptAlias /bloodhound /opt/bloodhound/environments/main/site/cgi-bin/trac.wsgi
   <Directory /opt/bloodhound/environments/main/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 /opt/bloodhound/environments/main/bloodhound.htdigest
     Require valid-user
   </LocationMatch>
 </VirtualHost>

Probably you have to add the following line to the file /etc/apache2/ports.conf:

Listen 8080

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