How to Setup and Configure a Basic Codebeamer Cluster

Introduction

If users prefer using a non-dockerized version of the application, codebeamer and all required dependencies need to be installed. This page collects all wiki pages helping to set up a codebeamer instance, and configure it as a clustered version.

References

• Cluster component
• Cluster architecture
• Software requirements
• Hardware requirements
• Network requirements
• Database requirements
• License requirements:
  • You must login to see this link. Register now, if you have no user account yet.
  • Managing Licenses
• Supported browsers

Installation and Configuation

Installation overview: Installation Guide

Database

All the cluster nodes must be connected to the same database instance and database using the same parameters:

• connection url (host:port) to the database instance
• username
• password
• database

CB_database_JDBC_Username=cbadmin
CB_database_JDBC_Password=cbpasswd123
CB_database_JDBC_Driver=mysql
CB_database_JDBC_ConnectionURL=jdbc:mysql://dbhost:3306/codebeamer?autoReconnect=true&zeroDateTimeBehavior=convertToNull&emulateLocators=true&characterEncoding=UTF-8&useSSL=false

For more information about supported databases and installation, see: Database Installation and Configuration

Shared Data (NFSv4) Server

To set up a Network File System (NFS) protocol on servers, follow the applicable instructions provided:

• On Windows: https://docs.microsoft.com/en-us/windows-server/storage/nfs/deploy-nfs
• On Linux: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/deploying_different_types_of_servers/exporting-nfs-shares_deploying-different-types-of-servers
• Recommended settings: Step by step: How to configure codeBeamer as active-active cluster

LoadBalancer

User requests should be distributed among running codebeamer, both hardware or software loadbalancer could work. "Non-sticky session" settings are recommended.

Basic Apache-2.4 LoadBalancer config example:

ServerName codeBeamer
Listen 0.0.0.0:8080

<VirtualHost *:8080>

   ProxyHCExpr ok234 {%{REQUEST_STATUS} =~ /^[234]/}

   <Proxy balancer://codebeamercluster>
      BalancerMember http://codebeamer-app-server1:8080 hcmethod=GET hcuri=/hc/cluster/ping.spr hcexpr=ok234 hcinterval=10 hcpasses=2 hcfails=2
      BalancerMember http://codebeamer-app-server2:8080 hcmethod=GET hcuri=/hc/cluster/ping.spr hcexpr=ok234 hcinterval=10 hcpasses=2 hcfails=2
      ProxySet lbmethod=byrequests
   </Proxy>

   <Location /balancer-manager>
        SetHandler balancer-manager
        Order allow,deny
        allow from all
   </Location>

   ProxyPass /balancer-manager !

   ProxyPass / balancer://codebeamercluster/
   ProxyPassReverse / balancer://codebeamercluster/


   #WebSocket loadbalancer
   <Proxy balancer://wsBalancer>
      BalancerMember ws://codebeamer-app-server1:8080
      BalancerMember ws://codebeamer-app-server2:8080
      ProxySet lbmethod=byrequests stickysession=JSESSIONID
   </Proxy>

   <LocationMatch "/ws/notification/.*/.*/websocket">
      ProxyPass "balancer://wsBalancer/" stickysession=JSESSIONID
   </LocationMatch>

</VirtualHost>

Please note that there are two options for loadbalancing:

SSL Passtrhough

In this case LoadBalancer doesn't have TLS, but all the cluster nodes have and serve the requests on their TLS ports. For this the following is needed:

• wildcard certificate on all of the nodes
• configuring nodes to use TLS, see: How to set up SSL for codebeamer
• setting the ports in the loadbalancer config to 8090
• if needed, change the web socket protocol to secure websocket protocol (WSS)

SSL Offload

In this case LoadBalancer has the certificate and passing the traffic non-encrypted to the backend servers. For this cluster nodes need to be configured without TLS. This setting is suggested.

Increase LoadBalancer timeout configuration to 1 hour.

Codebeamer Cluster

All codebeamer servers must be installed on all the cluster nodes first: Installing codebeamer

Environment must be specified for all the cluster nodes in the similar way. The easiest way to achieve this is to use the systemd service file that is provided here: Adding codeBeamer service (auto startup)

To set up the cluster with different environments (like with containers), create a similar environent file:

#XMX setting
CB_MAXHEAPSIZE=1500

#Configure timezone properly
TZ=Europe/Berlin

## Cluster
CB_CLUSTER_ENABLED=true
CB_ping_testingEnabled=true

## CACHE settings
# the fqdn of the current node
CB_RMI_CACHE_HOSTNAME=<the-local-node-fqdn>

# the list of cluster nodes
CB_RMI_CACHE_INSTANCES=<the-local-node-fqdn>,<other-cluster-node-fqdn>,...
CB_RMI_REPLICATION_CACHE_PORT=4001
CB_RMI_INVALIDATION_CACHE_PORT=4002
CB_RMI_CACHE_SOCKET_TIMEOUT_MILLIS=12000
CB_RMI_CACHE_REMOTE_OBJECT_PORT=9000

## JGROUP settings
CB_JGROUPS_CHANNEL_TCP_PING_ADDRESSES=<the-local-node-fqdn>,<other-cluster-node-fqdn>,...
CB_JGROUPS_CHANNEL_TCP_PING_PORT=9998
CB_JGROUPS_TEST_CHANNEL_TCP_PING_PORT=8998

## Scheduler settings
CB_SCHEDULER_FACTORY_THREAD_COUNT_INSTANCE=3
CB_SCHEDULER_FACTORY_THREAD_COUNT_CONCURRENT=3
CB_SCHEDULER_FACTORY_THREAD_COUNT_REPORT=3
CB_SCHEDULER_FACTORY_THREAD_COUNT_REMOTE_JIRA_SYNC=3
CB_SCHEDULER_FACTORY_THREAD_COUNT_REMOTE_DOORS_SYNC=3

## TLS for in case of SSL Passthrough
#TOMCAT_CONNECTOR_KEYSTORE_FILE=<keystore-file-location>
#TOMCAT_CONNECTOR_KEYSTORE_PASS=<keystore-password>
#JVM_OPTIONS= -Djdk.tls.ephemeralDHKeySize=2048

## Database access settings
CB_database_JDBC_Username=<database-user>
CB_database_JDBC_Password=<database-password>
CB_database_JDBC_Driver=<jdbc-driver-class>
CB_database_JDBC_ConnectionURL=jdbc:<db-type>://<database-hot-and-port>/<database>?autoReconnect=true&zeroDateTimeBehavior=convertToNull&emulateLocators=true&characterEncoding=UTF-8&useSSL=false

After creating the environment file at an optional location, create a systemd service override.

1. Create directory /etc/systemd/system/codebeamer.service.d
2. Add override.conf into that directory with the following content:
   

   [Service]
   EnvironmentFile=<location-of-the-environment-file>
   

After executing these steps, all codebeamer instances - on all nodes - can be started using the following command:

 systemctl start codebeamer.service 

Dedicating Servers Exclusively for API Calls

With the development of this function, it is possible to dedicate one or more nodes of a cluster solely for API calls, preventing the related nodes from being overloaded by blocking the execution of other background processes that might cause performance issues.

To dedicate a node as an API server, the following environment parameter needs to be set:

CB_CLUSTER_API_SERVER=true

See also:Cluster architecture, REST API (v1)

API Mode

Nodes in Codebeamer can be started as API servers. When a node is running in API mode, only System Admins are allowed to log in.

Normal users cannot log in, however, they can still send API requests. With this, the load is moved from the end-user servers to a dedicated API server.