Preparing your environment

Prepare your environment for a Kubernetes deployment by completing the following tasks before you install Jama Connect.

Preparing your database server

Use the following information to connect the application server to the database server.

the 

IMPORTANT: Usernames and passwords for each database schema must match what's entered in the preparation SQL scripts.

Install and configure MySQL

MySQL is the recommended database server. Follow these steps to install and configure it.

Important considerations

• You must have full database admin permissions on the server that hosts the MySQL database.
• For the Jama Connect installation to succeed, you must create three or four database schemas, as described here.

RECOMMENDED SETTINGS AND SAMPLE CONFIG FILE

The following recommended settings require 8 GB of memory allocated to MySQL Server for a typical installation and 16 GB for an enterprise installation.

When creating a database, use the default character set and collation (utf8mb4 and utf8mb4_0900_ai_ci).

These settings can be added to your my.cnf file (Linux) or your my.ini file (Windows).

Here is a sample text config file for an enterprise. You must add the following values for your environment:

bind-address=0.0.0.0
key_buffer_size=16M
max_allowed_packet=1G
thread_stack=192K
thread_cache_size=8
tmp_table_size=2G
max_heap_table_size=2G
table_open_cache=512
innodb_buffer_pool_size=12G
innodb_log_file_size=256M
innodb_log_buffer_size=12M
innodb_thread_concurrency=16
max_connections=351
wait_timeout=259200

To install and configure MySQL:

1. Make sure that the InnoDB engine is enabled.

2. Download and install a supported version of MySQL.

3. On the MySQL database server, create an empty Jama Connect schema/database that uses UTF8: 

CREATE DATABASE jama character set utf8mb4;

4. On the MySQL database server, create two additional database schemas and a user ("jamauser") with the ability to access, create, and update tables within the database: 

CREATE DATABASE saml;
CREATE DATABASE oauth;
CREATE USER 'oauthuser'@'%' IDENTIFIED BY 'password';
CREATE USER 'samluser'@'%' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON jama.* TO 'jamauser'@'%';
GRANT ALL PRIVILEGES ON oauth.* TO 'oauthuser'@'%';
GRANT ALL PRIVILEGES ON saml.* TO 'samluser'@'%';

5. Create a database schema for Quartz to support horizontal scaling of core pods:

CREATE DATABASE quartz;
CREATE USER 'quartzuser'@'%' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON quartz.* TO 'quartzuser'@'%'

6. Restart the database server.

MySQL is now installed and configured on your database server.

Install and configure Microsoft SQL Server

If you are using Microsoft SQL Server for your database, follow these steps to install and configure it.

Important considerations

• You must have full database admin permissions on the server that hosts the SQL Server database.
• Install Microsoft SQL Server 2022 for the database server.
• For the Jama Connect installation to succeed, you must create an empty Jama Connect database and two or three additional database schemas (mentioned below). Otherwise, the system continues to attempt to connect to the databases and produces log failures. After you create the database schemas, you must restart Jama Connect.
• Jama Connect requires that the MSSQL COMPATIBILITY_LEVEL value be 160 or greater.
• The SQL query script in this task is run only for a fresh install and only before installing
• Jama Connect. Don’t run the script on an existing installation.
• When you upgrade Microsoft SQL Server (for example, from Microsoft SQL Server 2017
• to 2019 or 2022), existing databases keep their previous compatibility level by default.
• After the database instance upgrade, the compatibility level must be manually configured.

To confirm the current value:

SELECT compatibility_level FROM sys.databases WHERE name = <DATABASENAM
E>;

To modify the value:

ALTER DATABASE SET COMPATIBILITY_LEVEL = 160; -- SQL Server 2022

For more information on the compatibility level, see Alter Database (Transact-SQL) Compatibility Level.

To install and configure Microsoft SQL Server:

1. Connect to the SQL Server using a SQL management application (such as SQL Server Management Studio).

2. Replace the database passwords in the installation script below.

3. Copy and store the passwords you create here. You will need them later to configure the application.

4. In a new query window, run this SQL query script.

IMPORTANT: This script must be run before installing Jama Connect, or the installation might fail. Modify the passwords in this script before execution. Passwords must be enclosed in single quotes.

/*
This script must be run prior to Jama Connect installation or installation may fail to complete.
Modify the passwords in this script before execution. Passwords must be enclosed in single quotes.
*/
USE master;
CREATE LOGIN jamauser with password = 'password';
CREATE LOGIN samluser with password = 'password';
CREATE LOGIN oauthuser with password = 'password';
GO
USE master;
CREATE DATABASE jama;
GO
ALTER DATABASE jama SET READ_COMMITTED_SNAPSHOT ON WITH ROLLBACK IMMEDI
ATE
GO
ALTER DATABASE jama CONVERT TO CHARACTER SET latin1 [COLLATE =
'latin1_general_CI_AI'];
GO
USE jama;
EXEC ('CREATE SCHEMA oauth');
EXEC ('CREATE SCHEMA saml');
GO
USE jama;
CREATE USER jamauser for LOGIN jamauser;
CREATE USER samluser for LOGIN samluser with DEFAULT_SCHEMA=saml;
CREATE USER oauthuser for LOGIN oauthuser with DEFAULT_SCHEMA=oauth;
GO
EXEC sp_addrolemember N'db_owner', jamauser;
EXEC sp_addrolemember N'db_owner', samluser;
EXEC sp_addrolemember N'db_owner', oauthuser;

The script creates a new, empty Jama Connect database, adds two empty schemas to the database, and adds two database logins and two database users to support the multi-auth functionality in Jama Connect.

5. Create a database schema for Quartz to support horizontal scaling of core pods:

USE master;
CREATE LOGIN quartzuser with password = 'password';
GO
USE jama;
EXEC ('CREATE SCHEMA quartz');
GO
USE jama;
CREATE USER quartzuser for LOGIN quartzuser with DEFAULT_SCHEMA=quartz;
GO
EXEC

6. Confirm that these actions were successful:

• Script completed — Check the Query Execution results for errors.
• Users created — Run the following SQL script in a new query window. The results include jamauser, samluser, and oauthuser in the "Name" column of the result panes.

USE jama
SELECT * from master.sys.sql_logins
SELECT * from Jama.sys.sysusers

• Users granted the DB_owner role — Run the following SQL script in a new query window. The results show that the db_owner role is granted to jamauser, samluser, and oauthuser.

USE jama
SELECT DP1.name AS DatabaseRoleName,
isnull (DP2.name, 'No members') AS DatabaseUserName
FROM sys.database_role_members AS DRM
RIGHT OUTER JOIN sys.database_principals AS DP1
ON DRM.role_principal_id = DP1.principal_id
LEFT OUTER JOIN sys.database_principals AS DP2
ON DRM.member_principal_id = DP2.principal_id
WHERE DP1.type = 'R'
ORDER BY DP1.name;

7. Keep the database from locking users' accounts while they are logging in or working in Jama Connect (you must have db_owner permissions):

ALTER DATABASE jama SET READ_COMMITTED_SNAPSHOT ON WITH ROLLBACK IMMEDIATE;

8. Make sure the flag was successfully enabled:

SELECT is_read_committed_snapshot_on FROM sys.databases WHERE name='jama';

If the returned value is 1, the flag is on.

Microsoft SQL Server is now installed and configured on your database server.

Prepare custom memory settings for OpenSearch

OpenSearch uses an mmapfs directory by default to store its indices. The default operating system limits on mmap counts are often too low, which can result in out-of-memory exceptions. OpenSearch requires vm.max_map_count ≥ 262144 on each node that runs OpenSearch pods.

IMPORTANT: Execute these steps on each node where OpenSearch is expected to run, unless the Helm chart is already configured to automatically set the virtual memory.

To prepare a custom memory setting for OpenSearch:

• As an admin, run the following script:

echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
sudo sysctl -a | grep max_map_count

The system responds with: vm.max_map_count=262144.

Preparing the Helm chart

Jama Connect is configured through a standard Helm values file.

BEST PRACTICE: Use the example Helm values in this GitHub repository.

For lists of the required and optional values for the Helm values file, see Appendix: Configuring the Helm chart.

Preparing the ingress controller

If you are providing your own ingress controller and/or load balancer, consider adjusting the following settings on them:

• Maximum request body size — Set this value high enough to support the largest files you expect to upload.
• Idle timeout — We recommend setting this to 30 minutes to support long-running Jama Connect operations.

Helm values related to ingress can be found in “Configure ingress” in Appendix: Configuring the Helm chart.

If you use our bundled ingress controller, it is automatically configured with our recommended settings. See Traefik ingress controller in the Optional configuration section.

Preparing zone labels

You must create a topology.kubernetes.io/zone label for your Kubernetes nodes.

If your deployment requires a different scheduling strategy, you can override the default

topologySpreadConstraints with Helm values. See Preparing a dataset.

EXAMPLE

This example assumes you have three nodes, each in a different zone.

Run these commands to add the label, replacing <node1-name>, <node2-name>, <node3-name>, <zone1>, <zone2> and <zone3> accordingly.

kubectl label nodes <node1-name-> topology.kubernetes.io/zone=<zone1>
kubectl label nodes <node2-name> topology.kubernetes.io/zone=<zone2>
kubectl label nodes <node3-name> topology.kubernetes.io/zone=<zone3>

NOTE: If running OpenShift, run these commands, replacing kubectl with oc.

Create a namespace

For safer deployments and resource separation, install each Jama Connect instance in its own namespace.

To create a namespace:

1. Run the following command to create a namespace called jama-connect:

kubectl create namespace jama-connect

2. If running OpenShift, run this command:

oc new-project jama-connect

Commands in the next tasks assume that this namespace already exists.

IMPORTANT: This task is only required if your cluster runs OpenShift.

Jama Connect uses the following users to run containers and access the persistent volumes: 91, 481, 1000, and 1001. In addition, the Hazelcast component requires the NET_RAW capability to start. Before you install Jama Connect, verify that your cluster allows these users and this capability.

EXAMPLE

In OpenShift, a SecurityContextConstraints resource like the following can be saved to a file called scc-jama-connect.yml. 

apiVersion: security.openshift.io/v1
kind: SecurityContextConstraints
metadata:
name: jama-connect
allowedCapabilities:
- NET_RAW # Hazelcast
requiredDropCapabilities:
- ALL
allowPrivilegeEscalation: false
runAsUser:
type: RunAsAny
seLinuxContext:
type: MustRunAs
fsGroup:
type: MustRunAs
ranges:
- min: 91 # tomcat
max: 91
- min: 481 # opensearch
max: 481
- min: 1000 # saml
max: 1001 # others
18Jama Connect: Kubernetes-Native Deployment
supplementalGroups:
type: RunAsAny
volumes:
- configMap
- csi
- downwardAPI
- emptyDir
- ephemeral
- persistentVolumeClaim
- projected
- secret

To create security context constraints:

1. Create the resource

oc apply -f scc-jama-connect.yml

2. Link the SecurityContextConstraints resource with the service accounts from the jama-connect namespace:

oc adm policy add-scc-to-group jama-connect system:serviceaccounts:jama-connect

3. Add the following to your values.yaml file:

core:
  hazelcast:
    application:
      env:
        HZ_NETWORK_FAILUREDETECTOR_ICMP_ENABLED: 'false'
    securityContext:
      capabilities:
        add:
          - NET_RAW

The security context restraints are configured so that your cluster allows the users and capabilities to run containers and access the persistent volumes.

Prepare artifacts for airgap installation

Airgap installations must download the airgap bundle for the chosen Jama Connect version and make its content available to the cluster.

A bundle is a compressed tar file that contains:

• A jama-connect-<version>.tgz file. This is a Helm chart.
• An images folder with all the container images in tar format required by the Helm chart.

For example:

To prepare artifacts:

1. Download the bundle using one of these methods:

   From Artifactory:

   a. Go to https://registry.jamasoftware.net.

   b. Log in using the credentials provided by Jama Software.

   c. On the left side menu, navigate to Artifactory > Artifacts.

   d. Expand the airgap repository.

   e. Inside the jama-connect folder, navigate to and select the compressed file corresponding to the chosen version.

   f. Select Download.

   Using curl:

   * In a terminal with internet access, run the following command, replacing <username>, <password> and <version>:

curl -u <username>:<password> -L -O "https://registry.jamasoftware.net/artifactory/airgap/jama-connect/<version>.tar.gz"

2. Extract the bundle with the following command, replacing <version>:

tar -xzf <version>.tar.gz

3. Move the Helm chart from the bundle to a location accessible by Helm CLI.

4. Push all images from the bundle to a registry reachable by the cluster where Jama Connect will be installed.

Go to https://github.com/JamaSoftware/kubernetes-customer-toolkit/tree/main/airgap for an example script using Docker.

Preparing a dataset

This information is only applicable if you are provisioning a specific dataset. By default, Jama Connect automatically provisions a basic dataset.

BEST PRACTICE: Use a dataset created from an instance running Jama Connect 9.35.2 or later.

There are two primary approaches to provisioning a dataset:

• Use a pre-populated database (Recommended) — Connect a new Jama Connect instance to a pre-populated database restored from a backup.
• For large datasets, using a pre-populated database is generally faster and more reliable. For that reason, we recommend the pre-populated database approach for most environments.

• Use a .jama backup file — Restore from a .jama backup file.

While .jama backups are a valid option, they typically require additional storage for file staging and extraction, and they often take longer to complete end-to-end.

Use a pre-populated database to configure a dataset

This recommended method for preparing a dataset involves connecting a new Jama Connect instance to a pre-populated database restored from a backup.

Use the official backup tools provided by your database vendor to complete this task.

IMPORTANT: Once the new instance is up and running, you must perform additional steps to finish the instance setup. See Complete your installation for the dataset with a pre-populated database in Installing and upgrading.

The following example includes parameters that must be added to your Helm values:

core:
  application:
    storage:
      sharedVolume:
        request: 50Gi
  search:
    opensearch:
      application:
        storage:
          request: 30Gi

To prepare a dataset:

1. Create a backup of the database used by your current Jama Connect instance.

2. Create a new database instance from the database backup.

3. From the existing Jama Connect instance:

a. Set an environment variable with your tenant name, which is used by subsequent commands.

export TENANT_NAME=jama

b. Save the tenant assets. If you want to reduce the backup size, exclude the tempreports directory.

kubectl get pods -l app.kubernetes.io/name=core -o name | head -n 1
| \
xargs -I{} sh -c 'kubectl exec -c core {} -- tar -zcvf - -C /home/co
ntour/tenant/${TENANT_NAME} \
avatars attachments diagrams reports equations tempreports > ./asset
s.tar.gz'

          The assets.tar.gz file is generated.

c. Determine the amount of storage used by OpenSearch or Elasticsearch. If you run multiple OpenSearch/Elasticsearch pods, use the largest amount among them as your baseline.

• For OpenSearch pods:

kubectl get pods -l app.kubernetes.io/name=opensearch -o name | xarg
s -I{} sh -c 'echo "=== {} ==="; \
kubectl exec -c opensearch {} -- du -sh --apparent-size /usr/share/o
pensearch/data'

• For Elasticsearch pods:

kubectl get pods -l app.kubernetes.io/name=elasticsearch -o name | x
args -I{} sh -c 'echo "=== {} ==="; \
kubectl exec -c elasticsearch {} -- du -sh --apparent-size /usr/shar
e/opensearch/data'

4. In the Helm values of the new instance:

a. Set the following to the size for OpenSearch and an additional buffer for future growth:

core.search.opensearch.application.storage.request

b. Set core.application.storage.sharedVolume.request to the uncompressed size of the tenant assets, plus an additional buffer for future growth.

c. Set the configuration for your new database. See Configure database in Appendix A: Configuring the Helm chart.

Continue with the installation steps described in the Installing and Upgrading section and the Post-Installation Setup section for this method.

Use a .jama backup file to configure a dataset

Restoring from a .jama backup file is supported only during initial installation, before the database has been populated with any other dataset.

IMPORTANT: Once the new instance is up and running, you must perform additional steps to finish the instance setup. See Complete your installation for the dataset with a .jama backup file in Installing and upgrading.

The following example includes parameters that must be added to your Helm values:

global:
  core:
    enableHorizontalScaling: false
core:
  replicaCounts:
    jobs: 1
  nodeSelector: {}
  application:
    storage:
      core:
        path: '/data/restore'
      sharedVolume:
        request: 50Gi
tenant-manager:
  application:
    env:
      RESTORE_BACKUP_FILE: '/data/restore/mybackup.jama'
search:
  opensearch:
    application:
      storage:
        request: 30Gi

To prepare a dataset:

1. Make sure the database for the new Jama Connect instance is at least as large as the existing database.

2. From the existing Jama Connect instance:

a. Generate a .jama backup. See Appendix B: Backup to .jama or XML file for more details.

b. Retrieve the backup file. See FAQ for details.

c. Determine the amount of storage used by OpenSearch. If you run multiple OpenSearch/Elasticsearch pods, use the largest amount among them as your baseline. You can use the following commands as a reference to estimate the size.

• For OpenSearch pods:

kubectl get pods -l app.kubernetes.io/name=opensearch -o name | xarg
s -I{} sh -c 'echo "=== {} ==="; \
kubectl exec -c opensearch {} -- du -sh --apparent-size /usr/share/o
pensearch/data'

• For Elasticsearch pods:

kubectl get pods -l app.kubernetes.io/name=elasticsearch -o name | x
args -I{} sh -c 'echo "=== {} ==="; \
kubectl exec -c elasticsearch {} -- du -sh --apparent-size /usr/shar
e/opensearch/data'

3. Copy the backup file to the nodes where the new Jama Connect instance will be installed.

By default, the restore process looks for backup files in /data/restore, which is mounted into the core pods using a hostPath volume. You can customize this location in your Helm values. If needed, set core.application.storage.core.path to the directory you want to use.

To move the backup file to a single node:

a. Disable horizontal scaling for core pods in your Helm values so only one core pod runs:

global.core.enableHorizontalScaling: false.

b. Set core.nodeSelector in your Helm values so the core pod is scheduled on a specific node.

4. If setting global.core.enableHorizontalScaling: true, set core.replicaCounts.jobs: 1 because only one core-jobs pod is supported when restoring a .jama backup file.

5. Make sure the backup file is readable by all users. For example:

chmod 644 /data/restore/mybackup.jama

6. Determine the amount of storage required to restore your .jama backup file. Use the formula 2C + U + B, where

    C = size of the .jama file (compressed).

    U = total uncompressed size of the .jama contents.

    B = additional buffer for safety.

For example, if your .jama file is 4Gi compressed, 30Gi uncompressed and uses 4Gi of buffer, the result is 2 × 4 + 30 + 4 = 42Gi.

7. In the Helm values that the new instance will use:

a. Set core.tenant-manager.application.env.RESTORE_BACKUP_FILE to the backup file’s absolute path.

b. Set core.application.storage.sharedVolume.request to the size calculated to restore the backup file.

c. If installing Jama Connect 9.35.x or later, set core.search.opensearch.application.storage.request to the size identified for OpenSearch, plus an additional buffer for future growth.

Continue with the installation steps described in the Installing and Upgrading section and the Post-Installation Setup section for this method.

In This Section

• Overview
• Planning your installation
• Preparing your environment
• Installing and upgrading
• FAQ
• Appendix A: Configuring the Helm chart
• Appendix B: Back up to .jama or XML file
• Appendix C: Mapping KOTS configuration to Helm values

• Prepare artifacts for airgap installation_example.png300 KB
• Use a .jama backup file.png300 KB
• Use a pre-populated database (Recommended).png300 KB