Self-Hosted Installation Checklist

By Decoteau posted 10-23-2020 12:01

  

Self-Hosted Installation Checklist

1. Preparation

  1. DNS record for the Jama Connect server
  2. Email/ Collaboration
    1. SMTPrelay connection info
    2. IMAPmailbox connection info
  3. SSL/TLS certificate
    1. Must be in PEM format (base64 encoded x.509)
Private Key
Primary certificate 
    • Make sure to include all SANs
    • Not the full chainPrimary certificate
CA Chain
    • All intermediate and Root CA certificates
    • Not full chain
  1. Database
    1. Database type
    2. Routable server name or IP address
    3. Database name
      • Name must be lowercase
      • No hyphens in name
    4. Database Owner
      • SQL authentication; NTLM not supported
      • Grant all privileges on "*.*" to "jamauser"@"%"
    5. User Authentication
      1. Basic
      2. Crowd
      3. AD/LDAP
        • Need an account for the Bind DN
        • Will map user attributes
      4. SAML IDP Metadata URL, or metadata
      5. Internet access (APIs), domains to be accessible to the Jama Connect server
        1. Used to upgrade Docker, Replicated, and Jama Connect

2. Server Resource Sizing

See Server sizing in the user guide

Jama Connect supports any Linux distribution that supports the installation of the Docker engine service. We test with and support Docker-CE. Docker Enterprise works but we do not test on it, so we do not suggest it. See our Supported Software list for the version you are installing to see what we regression test against.

As for Filesystem volumes, we require four individual volumes. This ensures that the root or any other OS volume does not fill, causing an outage. (This can be expanded without downtime.) The Docker and Replicated volumes store data that can be replaced whereas the data in the data and logs volumes cannot. At a minimum, you must back up the /data volume.

Operating System (including version):

 

Number of CPUs:

 

Memory (GB):

 

Additional Software Required: Yes/No

 

Sudoers:

 

Data partitions:

 

It is not recommended to put everything on a single volume

Filesystem Type Size Mounted on

/ ext4200G / (Not recommended)

OR

/dev/mapper/vg_jama-lv_docker xfs30G /var/lib/docker

/dev/mapper/vg_jama-lv_replicated ext4 20G /var/lib/replicated

/dev/mapper/vg_jama-lv_logs ext4 10G /logs

AND

nfs_server:/jama/data nfs4 40G /data

OR

/dev/mapper/vg_jama-lv-data ext440G /data


3. Installation Tasks Order of Operation

  1. Configure custom memory settings for Elasticsearch
  2. Install and configure Docker
  3. Install and configure Replicated
  4. Routable hostname
  5. Configure TLS key and primary certificate
  6. Configure Certificate Trust if using a private CA
  7. Configure snapshots and statsd data to be saved under

/data
volume

  1. Provision (install) Jama Connect to database
  2. New installation, or
  3. Restore from backup (*.jama or *.xml)

4. Post installation tasks

  1. Configure email and collaboration settings as root user
  2. Configure user authentication method as root user
  3. Create an admin user for testing (use Organization Admin group)
  4. Test user authentication via selected authentication method
  5. Test @-mention collaboration (Stream) and notification feature 

5. Notes

The following information is frequently needed for troubleshooting issues on self-hosted installations. Keep note as you install and upgrade components of your environment. 

Docker version

 

Replicated version

 

Jama Connect version

 

Jama Connect URL, for user access

 

Admin Console URL for admin access

 

Application server Operating System version

 

Total CPUs

 

Total Memory

 

Local or exported filesystem for /data directory?

 

Database type and version

 

Database server name

 

Database name

 

Database owner credentials

 

SMTP Relay connection info

 

SMTP Relay credentials (If applicable)

 

IMAP user mailbox connection info

 

IMAP user credentials (if applicable)

 

Jama Connect user authentication method

 

Jama Connect AD/LDAP Bind account credentials

 


6. Standard (non-airgap) installations

Please reference the "Notes for Administrators" section in the published Release notes for the version which you intend to upgrade. There may be additional steps or information.

  1. Ensure Replicated and Docker are the version supported in the release notes
    1. $ curl -sSL "https://get.jamasoftware.com/docker?replicated_tag=[RELEASE_VERSION]" | bash -s no-auto

is the standard command; see release notes for version-specific command.

  1. The installer will prompt you to upgrade Docker, if required, and install the latest supported version automatically for you.

Appendix

7. Elasticsearch memory setting

Elasticsearch requires the "vm.max_map_count" settings to be set. The following two commands set this up correctly. At server boot time the setting is read from the "/etc/sysctl.conf" file. The second command loads the setting into memory immediately, therefore no reboot is required.

# echo "vm.max_map_count = 262144" >> /etc/sysctl.conf
# sysctl -w vm.max_map_count=262144

8. Docker service configuration

Note that this is out of scope for Jama Support, but is helpful information to know.

Setting these docker options will improve the performance of the Docker service, set the SAN's docker deployment benchmark critical configurations, and enforce the "overlay2" storage driver. Using the "overlay2" storage driver, your server can self-heal when encountering "Dead" containers. Overlay2 requires the docker volume to be xfs storage with ftype=1​. The SAN's Security settings are the two options set for "log-level" and "icc".  Note that your kernel must be supported according to https://docs.docker.com/storage/storagedriver/select-storage-driver/

# cat /etc/docker/daemon.json

{

"storage-driver": "overlay2",

"log-level": "info",

"icc": false,

"log-driver": "json-file",

"log-opts": {

"max-size": "100m",

"max-file": "3"

},

"debug": false

}

 Optionally, you can change the bridge IP address for the docker0 interface, if conflicting with a routable network. You can also configure DNS severs for docker to set in the containers, if different from the application hosts resolver configuration. 

# cat /etc/docker/daemon.json

{

"storage-driver": "overlay2",

"log-level": "info",

"icc": false,

"bip": "169.254.0.1/24",

"dns": ["8.8.8.8", "8.8.4.4", "1.1.1.1"],

"log-driver": "json-file",

"log-opts": {

"max-size": "100m",

"max-file": "3"

},

"debug": false

}

9. Exporting and importing the Admin Console settings configuration

You can export the Admin Console settings. This allows for importing them after reinstalling the application. These settings are used by Jama Connect to connect to the data or state.

Export:

replicatedctl app-config export > /data/app-config.export

Import:

replicatedctl app-config import < /data/app-config.export

10. Backup and Disaster Recovery notes

  • Do not clone one Jama Connect server and create a different stage environment from it.
    • Only use a clone/snapshot to restore itself.
  • The Jama Connect application is ephemeral and stateless. The database information for the server is in the database.
    • Use the Backup/ Export options in the application for creating additional staged environments or to refresh a staged environment with data from the production instance.
  • Do not use native database tooling as it requires manual changes to the database before the application can connect to it. The Jama Connect backup feature uses automation when being restored on another staged environment.
    • With the /data volume being on an exported filesystem, the entire application server can be replaced without any data loss. The data is in the database and in the /data directory. 

Self-Hosted_Installation_Checklist_-_Jama_Software.pdf


#Self-Hosted
#installation
1 comment
53 views

Comments

12-15-2020 13:48

Hello, just fyi the docker link you referenced for kernel support is broken:  https://docs.docker.com/storage/storagedriver/select-storage-driver/​