Step by Step: How to Configure a Linux-Ubuntu Instance to Run with Codebeamer

• This guide describes steps for setting up and configuring a clean Ubuntu 16.04LTS instance and Codebeamer.
• On other Linux distributions the installation steps are similar.
• If Docker is available in your environment you can proceed with Codebeamer's Docker image.

Installing Ubuntu Packages

Updating available packages is recommended.

Updating All Ubuntu Packages

$ sudo apt-get update
$ sudo apt-get upgrade

Installing Java

Codebeamer requires a Java installation to operate. Keep in mind that various Codebeamer versions may require and support different versions of java. Consult release notes and manuals about which JDK version is required for your installation.

Java can be installed with the following command:

$ sudo apt-get install openjdk-8-jdk

Then verify the installation using the following command:

$ java -version
openjdk version "1.8.0_91"
OpenJDK Runtime Environment (build 1.8.0_91-8u91-b14-3ubuntu1~16.04.1-b14)
OpenJDK 64-Bit Server VM (build 25.91-b14, mixed mode)

From Codebeamer 22.04 (Felicity), Java 11.x version is required. To install the required version run the following command:

$ sudo apt-get install openjdk-11-jdk-headless

Verify the installation using the same command as above.

Updating to Java 11.x

Required from Codebeamer 22.04 (Felicity).

To update already installed Java, run the following commands:

$ sudo apt-get update

Then install the required Java package:

$ sudo apt-get install openjdk-11-jdk-headless

Verify the installed Java version by running:

$ java -version

Installing MySQL

Codebeamer requires a database for storing its data. Here we describe how to use MySQL database, but also PostgreSQL and Oracle are supported (for more information, refer to the appropriate Release Notes).

MySQL can be installed with this command:

$ sudo apt-get install mysql-server mysql-client

During the installation the MySQL-server package will ask for a password for the "root" mysql user. Enter whatever you like (I'm using "cbpassword").

ALTER USER 'root'@'localhost' IDENTIFIED WITH caching_sha2_password BY '<secure_root_password>';
FLUSH PRIVILEGES;

mysql -h 127.0.0.1 -p

Then verify the installation using the following command:

$ mysql -u root -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 4
Server version: 5.7.15-0ubuntu0.16.04.1 (Ubuntu)

Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql> show databases;
+--------------------+
| Database           |
+--------------------+
| information_schema |
| mysql              |
| performance_schema |
| sys                |
+--------------------+
4 rows in set (0.00 sec)

mysql> exit
Bye

Post-Installation Configuration of MySQL Database

After successful installation, the following configuration has to be executed: Preparing MySQL Database for Installation - v10 and Later.

Moving MySQL to a Different Directory

By default, MySQL uses the "/var/lib/mysql" directory to store data on Ubuntu servers. This might not be suitable because it is typically on a small partition, and therefore it is advisable to move the MySQL data directory to some other location. If necessary, follow the instructions described here http://www.ubuntugeek.com/how-to-change-the-mysql-data-default-directory.html

Tuning MySQL Server

Refer to MySQL server tuning on how to optimize MySQL Server.

Installing Apache

Codebeamer does not require Apache, however, to access Managed Subversion repositories via http and/or https protocols, Apache must be installed.

Apache and related packages can be installed with the command below:

sudo apt-get install apache2 libapache2-mod-jk

Locale Settings

Codebeamer requires locale en_US.UTF-8.

With the command below it can be checked whether this locale is available:

$ locale -a | grep -i 'en_US.UTF.*8'

If the command above does not return anything the commands below can create locale en_US.UTF-8:

$ sudo locale-gen en_US.UTF-8
$ sudo update-locale en_US.UTF-8

Installing SCM Tools

Only those SCM (Source Code Management) tools should be installed that you are planning to use.

Subversion

$ sudo apt-get install subversion subversion-tools libapache2-svn

Then verify the installation using the following command:

$ svn --version

Git

$ sudo apt-get install git-core

Then verify the installation using:

$ git --version

Mercurial

$ sudo apt-get install mercurial

Then verify the installation using:

$ hg --version

Sshpass

To access remote repositories via ssh installing Sshpass can be useful.

$ sudo apt-get install sshpass

Then verify the installation using:

$ sshpass -V

Installing PhantomJS

PhantomJS is used to export charts to MS-Word and can be installed with the command below:

It is strongly recommended installing the latest version of PhantomJS available at http://phantomjs.org/download.html.

The command below installs PhantomJS from your distribution:

$ sudo apt-get install phantomjs

deb package maintainer has released PhantomJS 2.1.1 which version will not work on headless environment.

To remedy this error, follow the below instructions:

1. Download and install PhantomJS binary

wget https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-2.1.1-linux-x86_64.tar.bz2
bzip2 -d phantomjs-2.1.1-linux-x86_64.tar.bz2
tar -xvf phantomjs-2.1.1-linux-x86_64.tar
cp phantomjs-2.1.1-linux-x86_64/bin/phantomjs /usr/local/bin/phantomjs

This will overwrite the existing installation of PhantomJS.

2. If you wish to keep the package maintained version, copy the new file to another location:

cp phantomjs-2.1.1-linux-x86_64/bin/phantomjs /usr/local/bin/phantomjs

and make sure to update your system PATH so that /usr/local/bin/ is found first.

3. also update the startup script ~/CB/bin/cb and add the line below (if not present):

export QT_QPA_PLATFORM=offscreen

4. restart Codebeamer.

Installing Latex

Some Wiki plugins use external programs for rendering documents. These programs can be installed with the command below:

$ sudo apt-get install texlive-latex-base imagemagick

Optional Ubuntu Cleanup

It is recommended to keep your Ubuntu clean, and you should only run those OS services on the server that are really needed. Any service, like an ftp server or smtp/mail server, is potentially a risk to be attacked by hackers, especially on public sites, and just a waste of resources if not needed.

Therefore, we recommend removing such services. As an example, the Exim4 smtp server can be removed by executing:

$ sudo apt-get remove exim4 exim4-base exim4-config exim4-daemon-light

Installing LibreOffice for Importing from MS-Word

Codebeamer uses LibreOffice/OpenOffice to import some image formats from MS-Word documents, however, it is not required to install LibreOffice/OpenOffice

LibreOffice can be installed with the command below:

$ sudo apt install libreoffice unoconv

Ensure that "soffice.bin" is on PATH and runnable by the system user of Codebeamer.

If you already have OpenOffice installed that should be removed before installing the LibreOffice using this command:

$ sudo apt-get remove openoffice*

Installing Codebeamer

Create Linux User to Run Codebeamer

It is recommended that a special login account is created for running Codebeamer. In this guide "codebeamer" will be used. User can be created as:

$ sudo adduser --ingroup www-data codebeamer
Adding user `codebeamer' ...
Adding new group `codebeamer' (1002) ...
Adding new user `codebeamer' (1002) with group `codebeamer' ...
Creating home directory `/home/codebeamer' ...
Copying files from `/etc/skel' ...
Enter new UNIX password:
Retype new UNIX password:
passwd: password updated successfully
Changing the user information for codebeamer
Enter the new value, or press ENTER for the default
	Full Name []:
	Room Number []:
	Work Phone []:
	Home Phone []:
	Other []:
Is the information correct? [Y/n] y

The options --ingroup www-data ensure that "codebeamer" account belongs to the group Apache. This is important if Managed Subversion repositories need to be supported via http/https protocols.

The command below can be used to grant the "codebeamer" user the ability to execute the sudo command.

It is not required that "codebeamer" be granted the use of sudo, however, this guide assumes that.

$ sudo usermod -a -G sudo codebeamer

Downloading and Installing Codebeamer

• Login as "codebeamer" user.
  

  $ su - codebeamer

  
  
• Download Codebeamer.
• Execute sh "./CB-...-linux.bin" to start installation and follow the instructions.

If something failed, the log files can be found under /install_dir/tomcat/logs directory.

Completing Installation

After the installation script is finished, start your browser with the URL provided at the end of the installation (e.g http://localhost:8080).

In the browser, a step by step wizard will navigate you to complete the entire installation.

Codebeamer Installation Path

Codebeamer installation script uses Codebeamer version in the default installation directory (e.g. /home/codebeamer/CB-8.0.0), which is also recommended.

Other configuration files (e.g. Apache) use Codebeamer configuration files with full path. It is a good praxis to create a path independent of a Codebeamer path to make configuration files less Codebeamer-installation-directory-path-dependent to avoid modification of those files after a Codebeamer upgrade. Linux supports soft links that help with using Codebeamer version independent paths. Such a soft link can be created with the command below:

$ ln -s /home/codebeamer/CB-8.0.0 /home/codebeamer/CB

In scripts and in the configuration path /home/codebeamer/CB can now be used as the Codebeamer installation directory. After a Codebeamer upgrade, only this soft link must be redefined.

Adding Codebeamer Service (Auto Startup)

See here: Adding Codebeamer Service (Auto Startup)

Configuring Apache to Serve Codebeamer Requests

It is recommended to put an Apache server in front of Codebeamer to serve the http requests. To configure, follow these steps:

Edit $CB_HOME/tomcat/conf/server.xml, and enable AJP (Apache connector) by activating this section:

    <Connector port="8009" protocol="AJP/1.3" redirectPort="8443"
              URIEncoding="UTF-8"
                  acceptCount="200"
                  maxPostSize="-1"
          enableLookups="false"
          connectionTimeout="80000"
          executor="tomcatThreadPool"
    ></Connector>

As "root" user, create the "/etc/apache2/workers.properties" file with this content (see: Tomcat workers):

worker.list=ajp13
worker.ajp13.port=8009
worker.ajp13.host=localhost
worker.ajp13.type=ajp13
worker.ajp13.socket_keepalive=true
worker.ajp13.lbfactor=1
worker.ajp13.connection_pool_size=30
worker.ajp13.connect_timeout=5000
worker.ajp13.prepost_timeout=5000

As "root", create/overwrite the file "/etc/apache2/mods-available/jk.conf" with this content:

JkWorkersFile     /etc/apache2/workers.properties

JkLogFile     /var/log/apache2/mod_jk.log

JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "

# for correct URI encoding
JkOptions +ForwardURICompatUnparsed

JkMount /cb ajp13
JkMount /cb/* ajp13

Enable mod_jk:

$ sudo a2enmod jk

For detailed information see: Tomcat Apache mod_jk pages

Ensure that default Apache site does not exist:

$ sudo a2dissite 000-default

For detailed information see: Tomcat Apache mod_jk pages

mod_evasive Apache module must be disabled (if enabled) to ensure that remote-api and webdav work properly.

$ sudo rm /etc/apache2/mods-enabled/mod-evasive.load

The command below can be used to start Apache:

$ sudo service apache2 start

Now Codebeamer should be accesible via apache eg. http://hostname/cb.

Configuring Apache to Serve Managed Subversion Repositories

As "root", create/overwrite the file "/etc/apache2/mods-available/cb_svn.load" with the content below:

LoadModule dav_svn_module modules/mod_dav_svn.so

# It might be necessary that you have to add the line below to "/etc/sysconfig/apache2"
#APACHE_SERVER_FLAGS="  -D SVN_AUTHZ"
LoadModule authz_svn_module modules/mod_authz_svn.so
#Use the line below if apache cannot load modules/mod_authz_svn.so.
#LoadModule authz_svn_module /usr/lib/apache2/modules/mod_authz_svn.so

# You can find mysql_auth_module at: http://modauthmysql.sourceforge.net
# or http://www.gknw.net/development/apache/httpd-2.0/win32/modules/
# Warning: Comment this line OUT if you would like to use mysql_auth_module!
# LoadModule mysql_auth_module modules/mod_auth_mysql.so

# These modules are necessary to use basic authentication from a file
# managed by Codebeamer
LoadModule authn_file_module modules/mod_authn_file.so
LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule authz_user_module modules/mod_authz_user.so

As "root", create/overwrite the file "/etc/apache2/mods-available/cb_svn.conf" with the content below:

<Location /svn>
	DAV svn

	AuthUserFile "/home/codebeamer/CB/repository/.htaccess"
	SVNParentPath "/home/codebeamer/CB/repository/svn/"

#	AuthBasicAuthoritative Off # http://httpd.apache.org/docs/2.2/mod/mod_auth_basic.html

#	SVNListParentPath on

	AuthzSVNAccessFile "/home/codebeamer/CB/repository/acl.svn"
#	SVNPathAuthz off

	AuthType Basic
	AuthName "Subversion Repository"

	Require valid-user
</Location>

The command below can be used to activate the configuration:

$ sudo a2enmod cb_svn

Apache should be restarted via the command below:

$ sudo service apache2 restart