TRAC – Arch Linux Apache/WSGI Installation Guide


The tutorial ia about installing and configuring the TRAC issue tracking web-based application using an Apache and MySQL Arch Linux server. installing TRAC is not a simple process of installing the trac package via pacman and pointing your browser to the appropriate host url.

Because TRAC can be installed in a variety of ways depending on the server and libraries installed this tutorial takes a single path for installing the current the TRAC application (version 1.0.1 at the time of publication) over Apache using WSGI bridge and MySQL (MariaDb in Arch Linux) database backend.

What is Trac

Trac is an open source web-based project management application for issue tracking. Its wiki enhanced. Trac can be integrated with various source control systems (subversion and git being the prime source control system for linux) although this tutorial does not cover source control integration.

Base Arch Linux Server:

As a minimum you will require the base Arch Linux installation and should have installed and configured MySQL and Apache. I recommend you install the complete LAMP stack (a requirement if you want to install MyPhpAdmin to manage your MySQL server. The tutorial was tested on a VirtualBox ArchLinux appliance connecting to a remote MySQL server appliance over the local network (there is no requirement to use a remote MySQL installation to follow this tutorial).

Basic Conventions

Any text enclosed in the square brackets i.e. […], represent variables that should be replaced along with the square brackets with appropriate entries for your installation.

Basic Install Workflow

  1. Install the required python2 packages
    • Create MySQL database and user
    • Configure the Apache wsgi module in httpd.conf
    • Create project directory
  2. Create TRAC environment
    • Deploy TRAC enviroment
    • Configure Apache httpd.conf
  3. configure Admin Authentication
    • Configure admin user in TRACS
    • Create authentication file
    • Configure Apache basic authentication

1. Install Required Python2 Packages

TRAC is implemented in Python 2.x and requires you to install a number of supporting packages. Issue the following pacman command from the commandline from an account with admin privileges (or use the su command).

$ pacman -S python2 python2-genshi python2-setuptools mysql-python trac

Create MySQL database and user

Log into MySQL using the admin account and issue the following SQL statements:

TRAC requires the database tables CHARACTER SET be utf-8

$ CREATE DATABASE [trac_db_name] DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;

For a local MySQL installation

$ GRANT ALL ON [trac_db_name].* TO '[trac_user]'@'localhost' IDENTIFIED BY '[passwd]';

If you have a remote MySQL server replace localhost with the network IP address of the connecting MySqlClient. If the remote server is running on your local network you can replace localhost with 192.168.2.%. 192.168.2.% will permit any specified user to able to connect from any computer connected to the local network.

Configure Apache WSGI module

Add the following line to the LoadModule list in the /etc/httpd/conf/httpd.conf

LoadModule wsgi_module modules/mod_wsgi.so

Restart your apache server.

$ systemctl restart httpd

Create the project directory and web directory

Create the trac projects directory in /var/opt. You can locate the TRAC projects directory in any suitable location in the Arch Linux file hierarchy. For this tutorial we will create the directory in the /var/opt directory.

$ mkdir -p /var/opt/trac/projects/[project]

The -p option creates parent directories if they do not exist.

Change the ownership of the trac, projects and [project] directories: enter the following command at the shell prompt.

$ chown -R http /var/opt/trac

Create a directory in the /srv/http directory which will be where trac-admin deploy command will create a number of files.

$ mkdir /srv/http/[site]

2. Create the TRAC Environment

We now issue the following trac_admin command to create the initial project environment

$ trac_admin /var/opt/trac/projects/[project] initenv

You will be asked for the project name and then have to supply the database connection string which has the form.

$ mysql://[trac_user]:[passwd]@[server]:[port]/[trac_database_name]

The [trac_user] and [passwd] should match those you set in the GRANT sql statement above. If you are running SQL locally you can replace [server]:[port] with localhost. For a remote MySQl server you replace [server] with the servers name or ip address and replace [port] with the port number the remote server is listening on. MySQL standard port number is 3306.

Replace the [trac_database_name] with name of the database you specified in the CREATE DATABASE sql statement above.

A number of directories will created in the [project_name] folder.

Deploying the TRAC environment

$ trac-admin /var/opt/trac/projects/[project] deploy /srv/http/[site]

set the ownership of /srv/http/[site] to the account of the httpd server (this will be httpd in archlinux) and make the files is /srv/http/[site]/cgi-bin/ executable.

$ chown -R httpd /srv/http/[site]
$ chmod +x -R /srv/http/[site]/cgi-bin

Configure Apache httpd.conf

Add the following to your /etc/httpd/conf/httpd.conf

WSGIScriptAlias /[alias] /srv/http/[site]/cgi-bin/trac.wsgi
srv/http/[site]/cgi-bin>
    WSGIApplicationGroup %{GLOBAL}
    <Version < 2.3>
      Order allow, deny
      Allow from all
    </Version>
    <Version >= 2.3>
     Require all granted
    </Version>
</Location>

Restart your httpd server

$ systemctl restart httpd

Test your installation is functioning with your browsers with the following url. I use links text browser on my server to quickly test whether a site is working locally.

$ links http://localhost/[alias]

And you should see something similar to the image below

links_trac

In firefox you will get the following

graphics-trec

You notice their is no ‘admin’ tab and if you attempt to login you get the following page

trac-login-error

in order for you to login as the TRAC site admistrator you are required to setup authentication which we shall do via apache in order for TRAC to allow you to log into the site as admin and access the administration functions.

Configure TRAC Admin Authentification

A TRAC installation can use a variety of authentication methods – for this tutorial will use Apache’s built in basic authentication mechanism to allow you to login as the site administrator and configure various aspects of your TRAC installation.

Create the htpasswd file using the htpasswd command with the -c (create) option.

$ htpasswd -c [location]/[name].passwd [username]
 New Password: 
 Re-type new password: <type password>
 Adding password for user

Insure that the [location]/[name].passwd file is accessible to your apache server. When creating additional users you do not need to ¡nclude the -c option.

Now you need to grant administration rights to the named users above, [username], permissions in TARC by issuing the following command

$ trac-admin /var/opt/trac/projects/[project] permission add [username] TRAC_ADMIN

Now you need to enable apache to to authenticate against the password file by adding the following to the /etc/httpd/conf/httpd.conf file.

<Location /[alias]/login>
    AuthType Basic
    AuthName "TRAC"
    AuthUserFile [location]/[name].passwd
    Require valid-user
</Location>

Restart your apache server to reload the http.conf file and navigate to your trac installation url. you will be presented with the login screen.

trac-login

Once you are authenticated you will see the Admin table displayed.

trac-admin-tab

You now have access to the administration features of TRAC.

In the next installment we will add a couple of modules: one for user administration and one for having TRAC hosting multiple project.

As a treat for finishing this post I’ll be listening to “shar-lar-lar

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s