Page "BloodhoundInstall" was changed by gjm Diff URL: <https://issues.apache.org/bloodhound/wiki/BloodhoundInstall?action=diff&version=31> Revision 31 Comment: advising on installing as the bloodhound user and other improvements Changes: -------8<------8<------8<------8<------8<------8<------8<------8<-------- Index: BloodhoundInstall ========================================================================= --- BloodhoundInstall (version: 30) +++ BloodhoundInstall (version: 31) @@ -1,19 +1,20 @@ [[PageOutline(2-5,Contents,pullout)]] + = Installing Apache Bloodhound = -For more detailled instructions, please see BloodhoundDetailedInstallation. +For more detailed instructions, please see BloodhoundDetailedInstallation. For common installation errors and misconfiguration issues , please see BloodhoundInstallTroubleshooting -== General Prerequisites == +== Preparation == +=== General Prerequisites === As a base for installing Bloodhound, the rest of this document expects that you have the following installed on your system: * [http://www.python.org/ Python] >= 2.6 and < 3 * [http://www.pip-installer.org/en/latest/installing.html pip] * [http://www.virtualenv.org/en/latest/ virtualenv] - note that if you have this, you should already have pip installed. - There are good guides available for installing each of the above on a number of operating systems including: * [http://python-guide.readthedocs.org/en/latest/starting/install/win/ Installing Python on Windows] - * [http://python-guide.readthedocs.org/en/latest/starting/install/osx/ Installing Python on Mac OS X] +• [http://python-guide.readthedocs.org/en/latest/starting/install/osx/ Installing Python on Mac OS X] 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 @@ -27,25 +28,33 @@ Many other linux and *BSD distributions will have their own package management systems and repositories containing the appropriate packages. -== Databases == +=== Databases === Apache Bloodhound also requires a database and it supports the following popular databases: [http://sqlite.org/ SQLite], [http://www.postgresql.org/ PostgreSQL], and [http://mysql.com/ 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: +==== 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: * [http://www.postgresql.org/ PostgreSQL] * [http://initd.org/psycopg/ psycopg2] (for windows [http://stickpeople.com/projects/python/win-psycopg/ win-psycopg]) -As before, these are likely to be available on your distribution of Linux: - {{{#!sh - 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: +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: + {{{#!sh + sudo apt-get install postgresql python-dev libpq-dev + }}} +and on Fedora, RHEL, CentOS and similar: + {{{#!sh + 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: {{{#!sh sudo su - postgres createuser --no-superuser --no-createdb --no-createrole --encrypted --pwprompt bloodhound @@ -79,7 +88,7 @@ sudo /etc/init.d/postgresql restart }}} -=== If MySQL is your only choice === +==== 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): @@ -93,50 +102,76 @@ 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: + +{{{#!sh + 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: + +{{{#!sh + sudo mkdir -p /opt/bloodhound + sudo chown /opt/bloodhound +}}} + == Installation == -To install Bloodhound, the following steps represent the current recommended method: - - {{{#!sh +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: + {{{#!sh + 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 --system-site-packages bloodhound - source ./bloodhound/bin/activate + virtualenv /opt/bloodhound/bhenv + source /opt/bloodhound/bhenv/bin/activate pip install -r requirements.txt }}} -If you are using PostgreSQL, you also need to run: +If you are installing to PostgreSQL, you also need to run: {{{#!sh pip install -r pgrequirements.txt }}} -If this fails, you might need you to install the python-dev and postgres-dev packages and try again. - -Then run the {{{bloodhound_setup.py}}} script: - {{{#!sh - 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 + +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. + + {{{#!sh + 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 {{{#!sh 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 [http://www.7-zip.org 7-Zip] for such purpose. - -Amongst the other differences you should use + * *.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 [http://www.7-zip.org 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 {{{#!bat - bloodhound\Scripts\activate.bat - }}} -to activate the bloodhound environment then also skip the " source ./bloodhound/bin/activate" step in the installation instructions + 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. If you did not set any advanced options, you should find that you can start bloodhound using: - {{{#!sh - tracd ./bloodhound/environments/main --port=8000 +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: + {{{#!sh + tracd --port=8000 /opt/bloodhound/environments/main }}} and you will be able to access Bloodhound on @@ -144,16 +179,16 @@ 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. +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 - {{{#!sh - source ./bloodhound/bin/activate - trac-admin ./bloodhound/environments/main/ deploy ./bloodhound/site +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: + {{{#!sh + 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 @@ -168,12 +203,12 @@ 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) : +Add to this something like: {{{#!apache <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> + 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 @@ -183,7 +218,7 @@ AuthType Digest AuthName "Bloodhound" AuthDigestDomain /bloodhound - AuthUserFile /path/to/bloodhound/environments/main/bloodhound.htdigest + AuthUserFile /opt/bloodhound/environments/main/bloodhound.htdigest Require valid-user </LocationMatch> </VirtualHost> -------8<------8<------8<------8<------8<------8<------8<------8<--------
-- Page URL: <https://issues.apache.org/bloodhound/wiki/BloodhoundInstall> Apache Bloodhound <https://issues.apache.org/bloodhound/> The Apache Bloodhound issue tracker This is an automated message. Someone added your email address to be notified of changes on 'BloodhoundInstall' page. If it was not you, please report to .
