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).
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
- Install the required python2 packages
- Create MySQL database and user
- Configure the Apache wsgi module in httpd.conf
- Create project directory
- Create TRAC environment
- Deploy TRAC enviroment
- Configure Apache httpd.conf
- 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.
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
<Version < 2.3>
Order allow, deny
Allow from all
<Version >= 2.3>
Require all granted
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
In firefox you will get the following
You notice their is no ‘admin’ tab and if you attempt to login you get the following page
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]
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.
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.
Once you are authenticated you will see the Admin table displayed.
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“