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.
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.
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>'
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 = +
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
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:
- Enable the
- Add a new provider
- Authorization endpoint:
- Token endpoint:
- User information endpoint:
- 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"
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
The HTML code for favicons can be edited in the following template file:
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:
The official documentation has an overview of other customization options.
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:
- 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
- On the Tuleap website, navigate to Tuleap → My Account → Shell Account Information and add the public key under
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:
- Create a new project in Tuleap and add a Git repository to it
- On the user's computer, clone or pull the latest repository
- From the cloned workspace, run:
git push --mirror ssh://email@example.com/project-name/RepositoryName.git
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
To enable debug logging:
# nano /etc/tuleap/conf/local.inc $sys_logger_level = 'debug'
Tuleap's log files are stored in:
The Nginx log files are in:
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 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