Reference

Installing Tuleap on CentOS 7

My projects have outgrown Gogs, so I searched for and found another great self-hosted GitHub alternative. This is how I set it up.

Tags: centos tuleap

Overview

Last year I posted about setting up Gogs for a self-hosted alternative to GitHub. While this worked great for personal projects, I recently started to look for a more powerful solution that would allow me to develop, distribute, and support commercial and open source software projects.

I reviewed and tried a number systems of which Phacility and Tuleap were the final contenders. The former is developed by Facebook and offers a host of interesting features, but it is also a major resource hog with terrible performance and one of the worst user experiences that I have seen.

And so I settled for the latter, Tuleap, which has been a joy to use and met all my requirements in a nice package. Installation and configuration are a bit more involved, which is why I decided to share the steps here.

Prerequisites

The rest of this article assumes that Tuleap will be running on CentOS. The latest versions at the time of this writing are CentOS 7.7 and Tuleap 11.8.

To get started with the installation on a fresh system, a few packages and Remi's package repository are needed:

# yum install -y epel-release nano
# yum install centos-release-scl
# yum install https://rpms.remirepo.net/enterprise/remi-release-7.rpm

Next, set up the Tuleap package repository:

# nano /etc/yum.repos.d/Tuleap.repo

[Tuleap]
name=Tuleap
baseurl=https://ci.tuleap.net/yum/tuleap/rhel/7/dev/$basearch
enabled=1
gpgcheck=1
gpgkey=https://ci.tuleap.net/yum/tuleap/gpg.key

The server is now ready for the installation.

Installation

Tuleap uses MySQL as its database and is split into a number of packages for plug-ins and themes. The basic foundation can be installed with:

# yum install -y rh-mysql57-mysql-server tuleap tuleap-plugin-agiledashboard tuleap-plugin-graphontrackers tuleap-theme-burningparrot tuleap-theme-flamingparrot tuleap-plugin-git tuleap-plugin-pullrequest

The official documentation has a list of available plug-ins that can be added. Both SVN and Git are supported for version control. I'm personally using Git, and I also installed support for pull requests, as well as OpenID and WebDAV clients:

# yum install tuleap-plugin-git tuleap-plugin-gitlfs tuleap-plugin-pullrequest tuleap-plugin-openidconnectclient tuleap-plugin-webdav

Now that the base packages are installed, the database must be configured:

# nano /etc/opt/rh/rh-mysql57/my.cnf.d/rh-mysql57-mysql-server.cnf

[mysqld]
...
sql-mode=NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION

Then enable and start the database service:

# systemctl enable rh-mysql57-mysqld
# systemctl start rh-mysql57-mysqld

Don't forget to set a database root password:

# scl enable rh-mysql57 "mysqladmin -u root password"

New password: <mysql_root_password>

And finalize the server setup using Tuleap's setup script:

# /usr/share/tuleap/tools/setup.el7.sh --configure --server-name=yourdomain.com --mysql-server=localhost --mysql-password='<mysql_root_password>'

Configuration

Mail

To enable email notifications, uncomment and fill in the following lines:

# nano /etc/postfix/main.cf

myhostname = tuleap.yourdomain.com
alias_maps = hash:/etc/aliases,hash:/etc/aliases.codendi
alias_database = hash:/etc/aliases,hash:/etc/aliases.codendi
recipient_delimiter = +

Let's Encrypt

Websites should use encrypted connections, especially if they are exposed on the internet. Tuleap is using Nginx under the hood, which makes it easy to add free Let's Encrypt SSL certificates and update them automatically.

First install CertBot:

# yum install certbot python2-certbot-nginx

Then get a new certificate:

# certbot --nginx

Test the auto renewal process:

# certbot renew --dry-run

And if that succeeds, add a cron job:

# nano /etc/crontab

...
0 0,12 * * * python -c 'import random; import time; time.sleep(random.random() * 3600)' && certbot renew

Downloaded certificates will be stored in /etc/letsencrypt/live/tuleap.yourdomain.com/

Authentication

Tuleap has built-in user account management and authentication. However, it is also possible to tie into existing external identity providers via a number of protocols, which comes in handy if you would like to integrate Tuleap with other applications.

For my own purposes, I reviewed several identity and authentication providers, including KeyCloak, Shibboleth, WSO2, Gluu, FreeIPA, and FusionAuth. Most of these suffer from insane levels of complexity and outrageous hardware requirements.

I personally liked FreeIPA and FusionAuth the best - the latter having the smallest memory footprint and great technical support via the developer's Slack channel. I'll use them to explain the setup for OpenID and LDAP.

FusionAuth - OpenID

Assuming that FusionAuth is already up and running (I used the Fast Path method, which can also be used to upgrade FusionAuth) and configured with token and authorization endpoints for your Tuleap application, integration with Tuleap is a breeze.

In the Tuleap administrative interface:

  1. Enable the OpenID Connect plugin
  2. Add a new provider
    • Name: Your Company
    • Authorization endpoint: https://fusionauth.yourdomain.com/oauth2/authorize
    • Token endpoint: https://fusionauth.yourdomain.com/oauth2/token
    • User information endpoint: https://fusionauth.yourdomain.com/oauth2/userinfo
    • Client ID: <get this value from FusionAuth>
    • Client secret: <get this value from FusionAuth>

FreeIPA - LDAP

Integration with LDAP is more involved due to the more complex nature of the protocol and back-end database. The Tuleap service is running under the tuleap Linux user account by default.

On the FreeIPA server, create a service account for it:

# ldapmodify -x -D 'cn=Directory Manager' -W

dn: uid=tuleap,cn=sysaccounts,cn=etc,dc=yourdomain,dc=com
changetype: add
objectclass: account
objectclass: simplesecurityobject
uid: tuleap
userPassword: password123
passwordExpirationTime: 20380119031407Z
nsIdleTimeout: 0
<empty line>
Ctrl+D

Then you must set up the server as an IPA client. Someone else has already written a detailed tutorial, so I won't go into that here.

Now switch to the Tuleap server. First, install the Tuleap LDAP plug-in:

# yum install tuleap-plugin-ldap
# /usr/share/tuleap/tools/utils/php72/run.php --module=nginx

Then copy the configuration template:

# cp /etc/tuleap/plugins/ldap/etc/OpenLDAP.inc /etc/tuleap/plugins/ldap/etc/ldap.inc

Then edit the configuration:

# nano /etc/tuleap/plugins/ldap/etc/ldap.inc

$sys_ldap_server = 'ldaps://ldap.yourdomain.com'
$sys_ldap_server_type = 'OpenLDAP';
$sys_ldap_dn = 'dc=yourdomain,dc=com';
$sys_ldap_bind_dn = 'uid=tuleap,cn=sysaccounts,cn=etc,dc=yourdomain,dc=com';
$sys_ldap_bind_passwd = 'password123';
$sys_ldap_uid = 'uid';
$sys_ldap_eduid = 'ipaUniqueID';
$sys_ldap_cn = 'cn';
$sys_ldap_mail = 'mail';
$sys_ldap_people_dn = 'cn=users,cn=accounts,dc=yourdomain,dc=com';
$sys_ldap_grp_dn = 'cn=groups,dc=accounts,dc=yourdomain,dc=com';
$sys_ldap_grp_cn = 'cn';
$sys_ldap_grp_member = 'member';
$sys_ldap_grp_oc = 'groupofnames';

Now you can enable the LDAP plug-in in the Tuleap administration interface.

Then enable LDAP authentication:

# nano /etc/tuleap/conf/local.inc

$sys_auth_type = "ldap"

Customization

The look and feel of Tuleap can be changed in various ways. Not everything is customizable in the web interface yet and may require a bit of surgery.

The first thing you'll probably want to do is to replace the site logo. This can be done by replacing the files in /etc/tuleap/themes/common/images/:

  • organization_logo.png (200x45px)
  • organization_logo_small.png (45x45px)

The HTML code for favicons can be edited in the following template file: /usr/share/tuleap/src/www/themes/BurningParrot/templates/header.mustache.

If you don't want visitors to be able to create new projects, the Create New Project option can be removed by editing the system configuration file:

# /etc/tuleap/conf/local.inc

sys_use_project_registration = 0;

Other important configuration settings are in:

  • Database: /etc/tuleap/conf/database.inc
  • Plugins: /etc/tuleap/plugins/

The official documentation has an overview of other customization options.

Usage

Tuleap's comprehensive user guide covers all aspects of how to use the software. Here are a few notes for Git server usage specifically...

To access Tuleap's Git repositories as a user:

  1. Generate an SSH key pair on the user's computer, for example via GitBash on Windows, or a terminal on Linux: 
    ssh-keygen -t rsa

    The generated public key is in C:/Users/username/.ssh/id_rsa.pub on Windows, and in ~/.ssh/id_rsa.pub on Linux

  2. On the Tuleap website, navigate to Tuleap → My Account → Shell Account Information and add the public key under Add Keys.

Migrating old Git or GitHub repositories to Tuleap

While there are scripts to automate the migration process, I found it easiest to simply clone and mirror existing Git repositories into Tuleap:

  1. Create a new project in Tuleap and add a Git repository to it
  2. On the user's computer, clone or pull the latest repository
  3. From the cloned workspace, run: 
    git push --mirror ssh://gitolite@tuleap.yourdomain.com/project-name/RepositoryName.git

Maintenance

Additional Plug-ins

The installation of additional plug-ins in the future is a two step process.

First install the plug-in package:

# yum install tuleap-plugin-awesomestuff

Then run the update script to update the configuration:

# /usr/share/tuleap/tools/utils/php72/run.php --module=nginx
# systemctl reload nginx
# systemctl restart tuleap-php-fpm

Diagnostics

To enable debug logging:

# nano /etc/tuleap/conf/local.inc

$sys_logger_level = 'debug'

Tuleap's log files are stored in:

  • /var/log/tuleap/codendi_syslog
  • /var/log/tuleap/ldap_syslog

The Nginx log files are in:

  • /var/log/nginx/access.log
  • /var/log/nginx/error.log

Git SSH Keys

Tuleap uses gitolite for managing the Git server under the hood.

The SSH keys of authorized gitolite users are in:

# cat /var/lib/gitolite/.ssh/authorized_keys

Gitolite's own SSH public key is in:

# cat /var/lib/tuleap/gitolite/admin/keydir/id_rsa_gl-adm.pub

Upgrading

Upgrading Tuleap requires some care as there may be special steps required to migrate the server to a newer version.

To check whether updates are available, run:

# yum check-update tuleap\*

The general upgrade process is as follows. First, stop the system services:

# systemctl stop tuleap
# systemctl stop nginx
# systemctl stop httpd

Then update the packages:

# yum update

Then apply data upgrades and regenerate the configuration:

# /usr/lib/forgeupgrade/bin/forgeupgrade --config=/etc/tuleap/forgeupgrade/config.ini update
# /usr/share/tuleap/tools/utils/php73/run.php --module=nginx

Finally, restart the services:

# systemctl start httpd
# systemctl start nginx
# systemctl start tuleap

Related Resources