Most open source issue tracking systems are web-based only. But sometimes it’s nice to have a dedicated client that connects to a server and only does one thing: track issues. WebIssues fits that description; it’s a client/server-based system that allows a desktop client to connect to the server and manage and collaborate on issues.

You will find a version of the client for Linux, Windows, and OS X, and there’s a portable version. The server, on the other hand, is Linux only. The system features:

  • Desktop interface
  • Filtering and searching of issues
  • Tracking new and modified issues
  • Report creation
  • Data export
  • Customizable issue types
  • Simple data organization
  • Security and rights management

System requirements

  • Server: Web server with PHP, database (MySQL, PostgreSQL, SQL Server, or Firebird)
  • Client: The client requirements depend upon the platform it is installed on. Make sure you check out the README file included with the downloaded client file.

Server installation

I will walk through the server installation on the Ubuntu 11.04 platform. Although WebIssues can be found in the repositories, I recommend downloading and installing from source. I first tested the installation from the repositories, and it did not fare well, so here is the process to install from source.

  1. Download the source from the WebIssues download page.
  2. Create the webissues database (using whatever tool you prefer to create a database).
  3. Move the downloaded file to /var/www/.
  4. Unpack the archive (the command to do so will depend upon which flavor of archive you downloaded — either .zip or .bz2).
  5. Rename the archive from webissues-XXX (XXX is the release number) to webissues-server.
  6. Change into the webissues-server/config directory.
  7. Copy the file config-template.inc.php to config.inc.php.
  8. Edit the config.inc.php to fit your needs (more on this soon).
  9. Open your web browser and point it to http://localhost/webissues-server/setup.php.

With the config.inc.php file, look for the following directives to set up:

  • db_engine: The database type used.
  • db_host: The db server address.
  • db_database: The database name.
  • db_user: The username for the database user with admin rights.
  • db_password: The password for the db user.
  • storage_path: The location of storage for system files.

The above are the minimum you need; you will also need to make sure the directory for the storage_path directive is created and writable by the system. You can give this directory 777 permissions with the command sudo chmod 777 /path/to/storage.

Also, make sure to create the directory /var/www/webissues-server/log and give it 777 permissions as well. You can change this path if you want WebIssues to dump its log files in /var/log — just create /var/log/webissues. If you do, make sure to edit the log_ directives in the config.inc.php file.

If needed, you can set up system notifications. This will require a functioning SMTP server in order to send out notification. This is set up in the same file under Notification sending configuration.

Browser-based setup

During the browser-based setup, you will take care of the following:

  • Data Tables
  • Server Name
  • Administrators
  • Issue Types

If your configuration file is set up correctly (which it should be), you will see the first page of the setup (Figure A).
Figure A

This is very typical of many server-based installs.

Click Next, and the tables will be inserted into the database. The next step is to name the Server. In this page, there is one text area where you can give your server a human readable name — enter that name and click Next. The next screen asks for you to set up a password for the user “admin.” You enter the new password, verify the password, and click Next.

The last page informs you that a set of sample issue types will be created. All you can do here is click Next. After those issue types are created, you will be informed to access the WebIssues server with the client.

Client installation

The installation on Ubuntu is quite simple. Open a terminal window and issue the command sudo apt-get install webissues. Allow apt-get to process all dependencies and run the installation. When complete, you can fire up the client from the command line with the command webissues, or from within the Office sub-menu of your desktop’s main menu. All other client installations can be done easily by downloading the client installer for the necessary platform.

Connecting to the server

When you fire up the WebIssues client, you will have to connect the client to the server. Click the New Connection button in the client and fill out the necessary information (Figure B).
Figure B

Remember, that the only credentials you have created are the admin credentials.

You must use the explicit path to the server. So if your server is in the webissues-server directory on 192.168.100.100, you would enter http://192.168.100.100/webissues-server/ for the server URL. You will also use admin as the username and the password you created during the installation.

Once you log in, you will be connected to the admin dashboard (Figure C), where you can start creating projects, users, etc.
Figure C

Click the Dashboard tab to manage the server end of things.

The tool is quite easy to use — just take a moment to set up users and then create Issue types. There is also an outstanding WebIssues Client Manual you can reference for the use of the desktop client tool; you just need to click the WebIssues Manual button in the client to open the manual in your default browser.

Give WebIssues a try and see if it meets your needs for an issue tracking and management tool.