The Fabricator

The open source world offers many project management tools. The classic bug trackers such as Mantis and Trac offer numerous additional features, as well, but they are often outdated. A modern alternative to these programs is Phabricator [1].

Originally developed by Facebook employee Evan Priestley, Phabricator is written in PHP and under active development; in addition to the bug tracker, it provides project management, a wiki, chat, a code review tool, and software repositories with Git, Mercurial, and Subversion, among other services. The focus is on software development, but Phabricator also can be used with other IT projects and be tailored to the specific purposes of a project thanks to its modular structure. Prominent users of Phabricator, in addition to Facebook, include Wikimedia, FreeBSD, and the KDE desktop project.

Flexible Installation

I recommend installing the usual LAMP stack, consisting of Linux, Apache, MySQL (or MariaDB), and PHP. Of course, the individual letters do not necessarily have to be taken literally: Instead of the L (Linux) of LAMP, another Unix system like FreeBSD would work, and Nginx can replace the A (Apache web server). Installing in a subdirectory is not supported; instead, you need to make a separate virtual host available for Phabricator. This vhost also requires a host name with a complete domain.

If you use Red Hat-related Linux distributions or Ubuntu, you can use one of the scripts linked to the installation guide, but they do nothing other than what is described here. In addition to MySQL and the web server, PHP and a number of PHP modules must be available on the server (i.e., the php5, php5-mysql, php5-gd, php5-dev, php5-curl, php-apc, php5- cli, and php5-json packages under Ubuntu). For better performance, install the alternative PHP cache APC, although this is not a mandatory step. At present, Phabricator is not yet compatible with PHP 7 (see the "PHP 5 on Ubuntu 16.04" box).

Installing from Source

To install Phabricator from source, you first need to check it out of the GitHub repository in three parts; however, first, create the /var/www/phabricator directory:

$ mkdir /var/www/phabricator && cd $_
$ git clone https://github.com/phacility/libphutil.git
$ git clone https://github.com/phacility/arcanist.git
$ git clone https://github.com/phacility/phabricator.git

The files may also reside outside the webroot directory. However, you have to specify the Phabricator webroot during configuration of the vhost to ensure that the PHP files are found (Listing 1).

<VirtualHost >
      ServerName phabricator.supersecret.org
      DocumentRoot /var/www/phabricator/phabricator/webroot
      RewriteEngine on
      RewriteRule ^/rsrc/(.*)     -                       [L,QSA]
      RewriteRule ^/favicon.ico   -                       [L,QSA]
      RewriteRule ^(.*)$          /index.php?__path__=$1  [B,L,QSA]
      <Directory "/var/www/phabricator/phabricator/webroot">
           DirectoryIndex index.php
           Options FollowSymLinks
           AllowOverride All
           Require all granted
      </Directory>
</VirtualHost>

Once the web server is configured, you can call the Phabricator page under the selected URL. If necessary, Phabricator provides useful information on problem solving – e.g., whether PHP packages (Figure 1) or MySQL credentials are missing. Enter the MySQL credentials directly into the JSON phabricator/conf/local/local.json configuration file, or use the configuration tool supplied with Phabricator for this purpose:

$ cd /var/www/phabricator/phabricator
$ ./bin/config set mysql.user root
$ ./bin/config set mysql.user root

Next, install the (approximately 60!) databases by using the storage tool:

./bin/storage upgrade

In this step, you need to confirm the application of schema changes twice; otherwise, the whole process should work without any problems. If you now call the Phabricator installation URL, you will see an input box, in which you can create the first user, who will also be the administrator.

In some installations in our lab, the input box did not appear, and it was thus impossible to create an account or log in. I am still missing an Authentication Provider and user accounts. To create a normal local account, you use the ac command and then enable it for a one-off login (Figure 2):

$ ./bin/accountadmin
$ ./bin/auth recover oliver

If you now log on under the Phabricator URL, you will finally find yourself in the Phabricator GUI, which indicates the pending installation problems in the menubar at the top (Figure 2). It is best to work through each problem individually and apply fixes according to the instructions given by Phabricator. You can also configure many other settings in this area, either for the global Phabricator installation (database, clustering, etc.) or the various applications the software provides.

Background Processes

Phabricator also provides a collection of daemons for various tasks that you launch at the command line. It is best to automate this with the init system of your Linux distribution. You can manually run the phd command, which you will find in the bin directory. The following lines provide an overview of the existing daemon processes, launch all the available processes, and select individual daemons, respectively:

$ ./bin/phd list
$ ./bin/phd start
$ ./bin/phd launch

For chat and notifications to work, you still need to configure and start the supplied notification server. Listing 2 shows an example of the configuration section that you insert into phabricator/conf/local/local.json. One of the two host sections is for connecting with the client; the other is for connecting with Phabricator and therefore needs to use localhost as the hostname. On your firewall, you need to allow port 22280 for the client connection.

"notification.servers": [
{
   "type": "client",
   "host": "phabricator.supersecret.org",
   "port": 22280,
   "protocol": "http"
},
{
   "type": "admin",
   "host": "localhost",
   "port": 22281,
   "protocol": "http"
}
]

Install the server itself in the support/aphlict/server/ directory using npm install ws, for which Node.js must be installed (provided by the NPM package manager). Launch the server using:

$ bin/aphlict start

If you run the Phabricator over SSL, which is recommended, you also need to configure the WebSocket server correspondingly. The Phabricator documentation explains how this is done.

Phabricator has too many options rather than too few. Each application can be configured in detail; the application itself can be configured in a variety of ways, such as in terms of user management. Authentication using OAuth on various sites like GitHub, Twitter, or Google is possible, as is LDAP integration.

Phabricator can also connect to multiple sites for different purposes, such as for sending email with Mailgun or SendGrid. The options are numerous. Additionally, Phabricator provides an API that lets you integrate the software with your own services.

Unusual Updates

Phabricator does not publish releases but follows a rolling release model that maintains ongoing changes in its source code repository. For updates, the developers recommend updating the source code from this repository regularly (e.g., on a weekly basis). A changelog published weekly should be read to keep up-to-date with the latest changes.

This method is unusual and time-consuming compared with the usual release cycles of other software. Perhaps the updates can be automated via cron jobs, but then you have to ensure that everything works after the update. If everything is running smoothly, you simply have no reason to update weekly. The old admin adage applies here: "Never change a running system."

In the update documentation, the Phabricator developers recommend the following procedure: Stop the web server, stop the Phabricator daemons, update the three source code directories, update the database, and then restart all production processes. In practice, I dispensed with restarting the web server (after all, other websites are still running on the server), and everything worked perfectly.

Conclusions

Phabricator is project management software with many features, from chat, to trouble and bug tickets, to a wiki. The web-based tools are easy to use and serve their purpose perfectly. Only the update process takes a bit of getting used to. With a rolling release that requires an update from the source code repository, the question is: When should you update? A conventional release model would be easier to understand. If that's all too complicated, consider the commercially hosted version dubbed Phacility [2].