• 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. Please keep in mind that various codeBeamer versions may require and support different versions of java, please 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)

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

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

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

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

Is 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 please 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 please 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 comment out the below line

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

Please 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, please 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)

Typically, when linux is booting, the codeBeamer service should start automatically. For this create a new file in /etc/init.d/codebeamer with this content:

#!/bin/bash
#
### BEGIN INIT INFO
# Provides:          codebeamer
# Required-Start:    $remote_fs $syslog $network
# Required-Stop:     $remote_fs $syslog $network
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Start and stop codeBeamer
# Description:       Controls the codeBeamer Server
### END INIT INFO

CB_HOME="/home/codebeamer/CB"
CB_OWNR="codebeamer"

case "$1" in
    start)
        # startup
        echo -n "Starting CodeBeamer: "
        su - $CB_OWNR -c "cd $CB_HOME/bin && $CB_HOME/bin/startup"
        echo "OK"
        ;;
    stop)
        # shutdown
        echo -n "Shutdown CodeBeamer: "
        su - $CB_OWNR -c "cd $CB_HOME/bin && $CB_HOME/bin/stop"
        echo "OK"
        ;;
    reload|restart)
        $0 stop
        $0 start
        ;;
    *)
        echo "Usage: $0 start|stop|restart|reload"
        exit 1
esac
exit 0

If necessary, modify the CB_HOME and CB_OWNR variables at the start of the script. Remember to save it.

Now to activate the service, execute these commands:

$ sudo chmod +x /etc/init.d/codebeamer
$ sudo update-rc.d codebeamer defaults

It must be ensured that codeBeamer is not running before the service can be started/stopped.

codeBeamer can be stopped by the command below:

$ /home/codebeamer/CB/bin/stop

After this, the codeBeamer service is set up, and can be started/stopped using the service commands:

$ sudo service codebeamer start
$ sudo service codebeamer stop

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