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

Installation Guide > Codebeamer Installation Guide > Codebeamer Installation > 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 instance and Codebeamer.

◦ Consult the PTC Release Advisor to know which Ubuntu version is supported for your Codebeamer version.

• 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 the PTC Release Advisor to know which JDK version is required for your installation. For JDK installation, refer to the guidelines of the specific JDK vendor.

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 resolve this issue, 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. Update the startup script ~/CB/bin/cband 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

1. Login as codebeamer user.

$ su - codebeamer

2. Download Codebeamer.

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

To list the installation options, you can run the installer with the --help parameter.

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 (For example: 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 (For example:. /home/codebeamer/CB-8.0.0), which is also recommended.

Other configuration files (For example:. 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)

For more information ,see: 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 Tomcat 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, for example:. 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

Was this helpful?