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

• This guide describes steps for setting up and configuring a clean openSUSE Leap 42.1 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 SUSE Packages

Updating available packages is recommended.

Updating all SUSE packages

$ sudo zypper refresh
$ sudo zypper update

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 zypper install java-1_8_0-openjdk

Then verify the installation using the following command:

$ java -version
openjdk version "1.8.0_101"
OpenJDK Runtime Environment (IcedTea 3.1.0) (suse-15.1-x86_64)
OpenJDK 64-Bit Server VM (build 25.101-b13, 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 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 we support Oracle as well. Codebeamer runs also with MariaDB however it is not yet recommended for production use.

MySQL can be installed with this command:

$ sudo zypper install mysql-community-server-client mysql-community-server

Enabling MySql service

$ sudo /sbin/chkconfig --add mysql
$ sudo service mysql start

Completing MySql Installation

$ sudo mysql_secure_installation

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").

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 17
Server version: 5.6.30 openSUSE package

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 |
+--------------------+
3 rows in set (0.00 sec)

mysql> exit
Bye

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 You must login to see this link. Register now, if you have no user account yet. 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 zypper install apache2 apache2-mod_jk

Enabling Apache service

$ sudo /sbin/chkconfig -add apache2
$ sudo service apache2 start

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'

Installing SCM tools

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

Subversion

$ sudo zypper install subversion subversion-server subversion-tools

Then verify the installation using the following command:

$ svn --version

Git

$ sudo zypper install git

Then verify the installation using:

$ git --version

Mercurial

$ sudo zypper install mercurial

Then verify the installation using:

$ hg --version

Sshpass

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

$ sudo zypper 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 install PhantomJS from your distribution:

$ sudo zypper addrepo http://download.opensuse.org/repositories/devel:openQA/openSUSE_Leap_42.1/devel:openQA.repo
$ sudo zypper refresh
$ sudo zypper install phantomjs

Installing Latex

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

$sudo zypper install texlive-latex ImageMagick

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 zypper addrepo http://download.opensuse.org/repositories/LibreOffice:Factory/openSUSE_42.1/LibreOffice:Factory.repo
$ sudo zypper refresh
$ sudo zypper install libreoffice unoconv

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

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 /usr/sbin/useradd -g www -m codebeamer
$ sudo passwd codebeamer

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

Login as "codebeamer"

$ sudo su - codebeamer

The "id" command should return something similar as below:

$ id
uid=1001(codebeamer) gid=8(www) groups=8(www)

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:

For detailed information see: Tomcat Apache mod_jk pages

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/conf.d/mod_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

As "root" edit the file "/etc/sysconfig/apache2" and add " jk" to this line:

APACHE_MODULES=".... jk"

Enable module:

$ sudo a2enmod jk

The command below can be used to restart Apache:

$ service apache2 restart

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

Configuring Apache to serve Managed Subversion repositories

As "root" create/edit the file "/etc/apache2/conf.d/subversion.conf" with this content:

<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>

As "root" edit the file "/etc/sysconfig/apache2" and add " dav dav_svn authz_svn" to this line:

APACHE_MODULES=".... dav dav_svn authz_svn"

The command below can be used to restart Apache:

$ sudo service apache2 restart