HipTest on-premises - Installation guide

Transcription

1 HipTest on-premises - Installation guide Owner: HipTest Version: Released: Author: HipTest Contributors: Module: HipTest enterprise ID: Link: Summary This guide details the installation and administration of HipTest Enterprise solution for a single server installation with internet access. It applies to HipTest Enterprise and beyond HipTest Created by DocGen on 18/02/2019 at 16:30:00.

2 Table of Contents Table of Contents Overview Requirements Hardware Operating system Network configuration License file (.rli) Easy Installation with Internet Access Install the on-premises solution Access the on-premises administration console Provide a hostname and an SSL certificate Upload your HipTest license Secure the administration console Preflight checks Configure your HipTest instance Hostname User Management Account managed by HipTest Account managed by Crowd Server Settings Advanced settings Boot HipTest Open HipTest Airgap Installation without Internet Access Prepare the environment Install Replicated Download HipTest Airgap Package Access the on-premises administration console Provide a hostname and an SSL certificate Use airgap package and upload your HipTest license Secure the administration console Preflight checks Configure your HipTest instance Hostname User Management Account managed by HipTest Account managed by Crowd Server Settings Advanced settings Boot HipTest Open HipTest Automated installation Configure Replicated automatically /etc/replicated.conf Configure HipTest settings automatically /tmp/settings.conf Generate HipTest settings from an existing installation Licensing View License information Synchronizing license with Internet access Synchronizing license without Internet access (airgap) Configuration SSL certificates Browser warning about SSL certificates Certificates during installation Certificates and private keys format HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 2 of 74

3 Modify the certificate of the administration console Self-signed (generated) Server path Upload files Save Modify the certificate of the HipTest application Use same certificate as the console Use custom certificate Linking JIRA to HipTest Enterprise JIRA Server JIRA Cloud Make JIRA accept HipTest self-signed certificate Configuring database Embedded database External database Migrating data from embedded database to external database Operations Restarting HipTest on-premises Stopping, starting and getting status Updating server IP address 1. Stop all replicated services 2. Change IP address in config files 3. Start all replicated services 4. Check that IP address changed in web administration console 5. Update IP address of HipTest service in settings Update HTTP Proxy / set HTTP Proxy after install Upgrade Upgrading Replicated Which Replicated version do I use? Upgrade to latest Replicated v2.x Online version Airgap version Upgrading HipTest application Upgrading to latest HipTest application version Airgap Upgrade Download the airgap package Copy the airgap package onto the server Set the path to the airgap package Perform the upgrade Backup & Restore Backup Backup strategy Automatic snapshots Starting a snapshot List snapshots Restore Migrating from HipTest Cloud Troubleshooting I lost the password of the HipTest on-premises administration console It hangs when creating a new snapshot. I restored from a snapshot but I lost my data. One user lost his/her password I want to set the password of one user The.rli license file can not be uploaded Release notes [ ] HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 3 of 74

4 Changed [ ] [ ] [ ] Changed [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 4 of 74

5 [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] Updated [ ] Removed [ ] [ ] [ ] [ ] [ ] HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 5 of 74

6 [ ] Removed [ ] [ ] [ ] [ ] Changed [ ] Changed [ ] Changed [ ] HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 6 of 74

7 Overview This guide details the installation and administration of HipTest Enterprise solution for a single server installation with or without internet access. It applies to HipTest Enterprise and beyond. An installation without internet connectivity is called airgap installation. It covers: Installation of HipTest Enterprise, Upgrade to newer versions of HipTest Enterprise, Backup & Restore of HipTest Enterprise data, Configuration and troubleshooting, Release notes of HipTest Enterprise. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 7 of 74

8 Requirements Hardware The recommended minimum resources of the linux server are: 4 cores with minimum 2,4 GHz per core 8 GiB of RAM Primary disk with minimum 50 GiB with 30 GiB free on /var Operating system The Linux server must run a 64-bits distribution able to run Docker engine in the range ce (with ce being the recommended version). The minimum kernel version is Well supported distributions include, but are not limited to: Debian 7.7+ Ubuntu / / Red Hat Enterprise Linux 6.5+ CentOS 6+ Amazon AMI / / / / / / / / / 2.0 Oracle Linux 6.5+ Network configuration Firewall/Security settings must allow: Inbound traffic for the following TCP ports: 80 HipTest app interface access, redirects to HTTPS 443 HipTest app interface access over SSL 8800 Administration console access Inbound/Outbound traffic from docker0 interface to the host interface for the following TCP ports: container orchestration and administration console API Non-airgap installation requires outbound HTTP/HTTPS Internet access to these domains and subdomains: replicated.com for license validation and release update checks docker.io for pulling containers from the Docker hub registry Installation also require following elements: DNS hostname where your instance of HipTest can be reached by your organization. Typically your hostname will look something like hiptest.yourcompany.com. SSL certificate matching the chosen DNS hostname. Either provide a PEM encoded certificate file and private key file, or use the provided selfsigned certificate. The self-signed certificate is not recommended as browsers will display a security warning. SMTP server settings. This includes the type of authentication, the server name and credentials. License file (.rli) This license file will be provided by a HipTest representative prior to installation. If you need a HipTest license, please contact us at contact@hiptest.net. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 8 of 74

9 Easy Installation with Internet Access Install the on-premises solution 1. Create a server instance from a supported OS with the resources recommended above. 2. Open an SSH session and login into your new server. 3. Run the following command to download and install the application with an easy installation wizard: curl -ssl sudo bash If you are installing HipTest behind a proxy, modify the install commands to export http_proxy environment variable as below: export http_proxy= curl -ssl sudo -E bash You will be prompted for simple questions through out the installation process if it cannot guess the settings automatically. It will ask for the networking interface to use and the proxy settings. It will then start downloading and installing the administration console application. Then it asks for the service IP address and prompts you to go to the administration console web interface. Access the on-premises administration console Open a browser and navigate to the administration console at where <server_address> is the name or IP address of the newly created HipTest server. The browser will display a security warning because HipTest on-premises initially uses a self-signed certificate. Proceed past the HTTPS connection security warning. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 9 of 74

10 Provide a hostname and an SSL certificate On the presented screen, supply the hostname and a custom SSL certificate for the administration console. You can choose 'Use Self-Signed Cert' and use the generated self-signed certificate or select 'Upload and Continue' after supplying your own SSL certificate. The certificate and key files must be PEM encoded. Upload your HipTest license The HipTest license file (.rli) has been provided by a HipTest representative prior to installation. Once uploaded, the license will be validated. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 10 of 74

11 Secure the administration console After the license validation is complete, secure the administration console access using a local password, an LDAP user account, or anonymous access (insecure). Local password or LDAP user account is highly recommended. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 11 of 74

12 Preflight checks The installer will perform some checks to ensure that HipTest on-premises can be run on this server. Once completed, proceed to next screen by clicking 'Continue'. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 12 of 74

13 Configure your HipTest instance Fill in required settings parameters in the Settings panel. Provide the requested information requested and click "Save" to continue. Hostname You can use the same hostname and certificate as the administration console, or use a custom one. User Management This section allows to choose the type of user management: accounts managed by HipTest Crowd Single-Sign-On Account managed by HipTest The default account will be the first account created on HipTest. You will use this account the first time you login to HipTest. Next, from HipTest, you will be able to add other users. Account managed by Crowd By choosing this option, you activate the Single sign on with Crowd. To do so, you have to configure the Crowd server, create an HipTest app on Crowd and configure the Crowd server in the User Management section. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 13 of 74

14 Crowd should be able to connect with HipTest. You have to create an application on your Crowd server The application will need your HipTest Entreprise URL HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 14 of 74

15 Server Settings This section allows to configure the server. If you skip this step, the users won't receive notifications and invitation by . HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 15 of 74

16 Advanced settings If you check the box "Display internal settings", you will be able to modify the internal settings. You may only need to change them for troubleshooting. Be sure to know what you are doing. You can change: Frontend HTTP port Frontend HTTPS port Database port You can also disable SSL. By default, HipTest will always enforce SSL and https usage, but the SSL handling can be offloaded to your own SSL terminator proxy. The proxy must be in front of HipTest, handle the SSL connections and forward them to HipTest. To use this configuration, uncheck this setting so that HipTest only listens for connections on its frontend http port and does not listen on https port. In this case, be sure to have HTTP header "X-Forwarded-Proto: https" in forwarded HTTP requests. By default, HipTest binds http and https to all interfaces of the server. When adding a reverse proxy in front of HipTest, you might want to bind these ports on the docker0 interface so they can only be reached locally. Next, click "Save" to continue. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 16 of 74

17 Boot HipTest Once settings are saved, click "Start Now" to boot HipTest. You will be taken to the dashboard of the HipTest Management Interface while the instance boots up. While booting, containers must be downloaded and it can take some time to complete depending on your connection speed. Please be patient. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 17 of 74

18 Open HipTest Once the instance has finished booting, an "open" link will appear on the far left side. Click "open" to launch HipTest in a new browser window. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 18 of 74

19 Airgap Installation without Internet Access Prepare the environment Create a server instance from a supported OS with the resources recommended above. Install a supported version of Docker. Installing a supported version of Docker on a server that does not have any internet access is a simple process, but it can require you to install a few dependencies. Most airgapped environments will still have access to yum and apt, but they will be pointing to local mirrors. The supported Docker versions range from to ce. We recommend that you use the latest version of Docker available in this range for your operating system. Locate and download the desired package of Docker from one of the official repositories: OS CentOS / RedHat Enterprise Linux Debian / Ubuntu Fedora Repository location Once the correct package has been downloaded and transferred to the airgapped machine you need to install it using one of the following commands: rpm: # CentOS / RHEL / Fedora $ sudo rpm -ivh <package_name>.rpm dpkg: # Debian / Ubuntu $ sudo dpkg --install <package_name>.deb Different versions of Docker require different dependencies that may have to be manually downloaded/transferred/installed to the airgapped machine. You will have to follow the same procedure for each one of those dependencies. Install Replicated HipTest on-premises is provided through Replicated technology. Replicated software must be downloaded and installed on the server. Download latest Replicated release from and run the following commands: tar xzvf replicated.tar.gz cat./install.sh sudo bash -s airgap Installer will ask if the machine requires a proxy to access the internet. You can safely ignore the question and press Enter. The installer will proceed and prompt you to visit the address We will download the HipTest airgap package first, and then go back to this URL to go on with installation. Download HipTest Airgap Package You have been provided a download link and a password to access HipTest airgap packages. Use the download link to access a password protected page. Enter the provided password to see a page listing HipTest releases. Choose the latest release and click its download icon to download it. Package size is around 1.5 GiB. Copy this package on your server, it will be needed in further steps. Access the on-premises administration console Open a browser and navigate to the administration console at where <server_address> is the name or IP address of the newly created HipTest server. The browser will display a security warning because HipTest on-premises initially uses a self-signed certificate. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 19 of 74

20 Proceed past the HTTPS connection security warning. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 20 of 74

21 Provide a hostname and an SSL certificate On the presented screen, supply the hostname and a custom SSL certificate for the administration console. You can choose 'Use Self-Signed Cert' and use the generated self-signed certificate or select 'Upload and Continue' after supplying your own SSL certificate. The certificate and key files must be PEM encoded. Use airgap package and upload your HipTest license On next screen, you are prompted to upload your license file. Once uploaded, the license will be validated and you will be able to choose between an online installation or an airgapped installation. The online installation is possible only if the server has access to the internet. The airgapped installer allows for offline installation of the app. An airgapped package archive is required for this installation type. Proceed with airgapped installation. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 21 of 74

22 You will be prompted to specify the absolute path to the airgap package you saved on this server earlier. The airgap package must end with.airgap extension. Supply the requested information and click 'Continue'. The airgap package will be extracted and validated. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 22 of 74

23 Secure the administration console After the airgap package validation completes, secure the administration console access using a local password, an LDAP user account, or anonymous access (insecure). Local password or LDAP user account is highly recommended. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 23 of 74

24 Preflight checks The installer will perform some checks to ensure that HipTest on-premises can be run on this server. Once completed, proceed to next screen by clicking 'Continue'. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 24 of 74

25 Configure your HipTest instance Fill in required settings parameters in the Settings panel. Provide the requested information requested and click "Save" to continue. Hostname You can use the same hostname and certificate as the administration console, or use a custom one. Provide the requested information requested and click "Save" to continue. User Management HipTest users can be created and managed inside HipTest, or outside HipTest by using Atlassian Crowd. Account managed by HipTest If you choose to manage users with HipTest, a primary user must be created. This is the default user. You will use this account the first time you login to HipTest, and use it to invite other people to join HipTest. The and password you provide will be used to created this primary user. Once the primary user has been created, modifying the or password from the Settings tab will not have any effect. Account managed by Crowd By choosing this option, you activate the Single sign on with Crowd. To do so, you have to configure the Crowd server, create an HipTest app on Crowd, and configure the Crowd server settings in HipTest using the credentials you submitted to Crowd. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 25 of 74

26 To enable HipTest to connect to Crowd, you have to create an application on your Crowd server Crowd will need your HipTest Entreprise URL. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 26 of 74

27 Server Settings This section allows to configure the server. If you skip this step, the users won't receive notifications and invitation by . HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 27 of 74

28 Advanced settings If you check the box "Display internal settings", you will be able to modify the internal settings. You may only need to change them for troubleshooting. Be sure to know what you are doing. You can change: Frontend HTTP port Frontend HTTPS port Database port You can also disable SSL. By default, HipTest will always enforce SSL and https usage, but the SSL handling can be offloaded to your own SSL terminator proxy. The proxy must be in front of HipTest, handle the SSL connections and forward them to HipTest. To use this configuration, uncheck this setting so that HipTest only listens for connections on its frontend http port and does not listen on https port. In this case, be sure to have HTTP header "X-Forwarded-Proto: https" in forwarded HTTP requests. By default, HipTest binds http and https to all interfaces of the server. When adding a reverse proxy in front of HipTest, you might want to bind these ports on the docker0 interface so they can only be reached locally. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 28 of 74

29 Boot HipTest Once settings are saved, click "Start Now" to boot HipTest. You will be taken to the dashboard of the HipTest Management Interface while the instance boots up. Note that features to check for HipTest updates or to synchronize license are inoperant as this is an airgap installation. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 29 of 74

30 Open HipTest Once the instance has finished booting, an "open" link will appear on the far left side. Click "open" to launch HipTest in a new browser window. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 30 of 74

31 Automated installation Configure Replicated automatically During installation, Replicated will create a config file in /etc/replicated.conf. If this file exists, the installer will not overwrite it. To configure Replicated, create this file using any or all of the following options: /etc/replicated.conf { "BypassPreflightChecks": true, "DaemonAuthenticationType": "password", "DaemonAuthenticationPassword": "this-is-a-secret", "ImportSettingsFrom": "/tmp/settings.conf", "LicenseFileLocation": "/tmp/license.rli", // Required if is an airgap install "LicenseBootstrapAirgapPackagePath": "/tmp/bundle.airgap", "LicenseBootstrapChannelID": "4331c5fa27ad e1bd234ded", // End "LogLevel": "debug", // Pins the application to a particular release if needed "ReleaseSequence": 123, // End "TlsBootstrapType": "server-path", "TlsBootstrapHostname": "hiptest.company.com", "TlsBootstrapCert": "/etc/server.crt", "TlsBootstrapKey": "/etc/server.key" } You can find more about Replicated settings on the following page Configure HipTest settings automatically You can configure required options automatically by setting the ImportSettingsFrom field in /etc/replicated.conf /tmp/settings.conf HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 31 of 74

32 { } "bind_to_docker0": { "value": "0" }, "configurable_global_values_visible": { "value": "1" }, "db_location": { "value": "db_location_is_embedded" }, "default_account_ ": { "value": "user@company.com" }, "default_account_password": { "value": "this-is-a-secret" }, "external_mongodb_database_name": {}, "external_mongodb_password": {}, "external_mongodb_port": {}, "external_mongodb_url": {}, "external_mongodb_username": {}, "external_postgresql_db_name": {}, "external_postgresql_hostname": {}, "external_postgresql_password": {}, "external_postgresql_port": { "value": "5432" }, "external_postgresql_username": {}, "frontend_http_port": { "value": "80" }, "frontend_https_port": { "value": "443" }, "hostname": { "value": "hiptest.company.com" }, "jenkins_root_certificate": {}, "jira_root_certificate": {}, "mongodb_db_location": { "value": "mongodb_db_location_is_embedded" }, "override_embedded_db_port": { "value": "0" }, "postgresql_port": { "value": "5432" }, "rails_secret_key_base": { "value": "2c86eaa727d200ec2331cefdfcb592d1885cee29529b783115cdd39fbcc310ce2bcf686f73e625e03303ba aca bbc91f3babcc3 }, "smtp_auth_type": { "value": "CRAM-MD5" }, "smtp_from_address": { "value": "hiptest@company.com" }, "smtp_host_address_and_port": { "value": "smtp.company.com:587" }, "smtp_password": { "value": "this-is-a-secret" }, "smtp_starttls": { "value": "1" }, "smtp_username": { "value": "hiptest" }, "ssl_cert_file": {}, "ssl_certificates": { "value": "ssl_certificates_use_same" }, "ssl_enabled": { "value": "1" }, "ssl_key_file": {}, "stmp_configuration_visible": { "value": "1" }, "terms_and_conditions_agreed": { "value": "1" } Setting Acceptable Values Description bind_to_docker0 "0" or "1" Bind frontend ports to docker0 interface db_location "db_location_is_embedded" or "db_location_is_external" Use embedded database or an external one default_account_ administrator The organization administrator default_account_password administrator password The organization administrator password external_mongodb_database_name String MongoDB database name HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 32 of 74

33 external_mongodb_password String MongoDB database password external_mongodb_port String MongoDB database port number external_mongodb_url String MongoDB database hostname external_mongodb_username String MongoDB database username external_postgresql_db_name String PostgreSQL database name external_postgresql_hostname String PostgreSQL database hostname external_postgresql_password String PostgreSQL database password external_postgresql_port String PostgreSQL database port external_postgresql_username String PostgreSQL database username frontend_http_port String default to "80" frontend_https_port hostname mongodb_db_location String String override_embedded_db_port "0" or "1" postgresql_port rails_secret_key_base "mongodb_db_location_is_embedded" or "mongodb_db_location_is_external" String String The port used by HipTest to serve HTTP requests. Defaults to 80. Change it if it conflicts with other services installed on the server. The port used by HipTest to serve HTTPS requests using SSL. Defaults to 443. Change it if it conflicts with other services installed on the server. Configure how users will access HipTest. A proper domain name with the corresponding SSL certificate gives the best experience. Choose if you want to use an embedded database or an external one Change embedded PostreSQL database exposed port PostgreSQL Database port (only apply if override_embedded_db_port == "1") Must be a 128 hexadecimal characters string. You can generate one with the command openssl rand -hex 64. smtp_auth_type None or CRAM-MD5 or Login or Plain SMTP Authentication Type smtp_from_address Setting Acceptable Values Description String smtp_password String smtp password that HipTest will use to send outgoing s smtp_starttls "0" or "1" Whether use starttls or not smtp_username String smtp username ssl_enabled "0" or "1" Whether enable ssl or not terms_and_conditions_agreed "0" or "1" Agree to HipTest Terms and Conditions. Application will not start if the value is not set to "1" Generate HipTest settings from an existing installation You can generate the settings from an existing application by using the following commands: Get the HipTest app id replicated apps then export the settings: replicated app <app_id> settings HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 33 of 74

34 Licensing The license for HipTest on-premises usage is automatically synchronized online on a regular basis. This is set to synchronize every 10 hours by default. This can be changed in the console settings: View License information You can view license information from the cog menu, under the "View License" menu item. The license defines the maximum number of users you can have on HipTest, and also the period of validity of the license. When the license expires, the service stops and can not be restarted. The administration console is still available. After a payment, the license gets updated and you can start HipTest again. Synchronizing license with Internet access To update your license information immediately, you can click the "Sync License" button. It will connect to our backend and retrieve the license information defined for you. A message is displayed once the license is updated. Synchronizing license without Internet access (airgap) HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 34 of 74

35 In airgap mode, accessing Internet is not allowed and the updated license can not be fetched from our servers. In this situation, the license is sent to the customer after payment and has to be copied on the HipTest Enterprise server on a special location. When triggering the license synchronization, the license file is read to update licensing information. Here are the detailed steps: 1. Download the license file and copy it to your server on a known location. 2. From the administration console, open the Console Settings from the cog menu 3. In the Airgapped Settings section, set the "License File" field to the path where the license file was copied On the screenshot above, the license file is configured to read /home/cbliard/downloads/hiptest-stable-airgap-dev-lab.rli. 5. Once the license file path is set, save your changes using the button at the bottom of the page. 6. From the cog menu, select "View License" 7. Click the "Sync License" button to update your license. The license file specified earlier in the airgapped settings is read to update your HipTest Enterprise license information. A message is displayed once the license information is updated. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 35 of 74

36 Configuration SSL certificates SSL certificates are used to secure the connection when accessing to the administration console or the HipTest application. Browser warning about SSL certificates In the case of web http servers, SSL Certificates are small data files that binds a cryptographic key to one or multiple hostnames. It enables the use of the https protocol and allow secure connections. These certificates are signed by a certificate authority (CA) that guarantees the link between the issued certificate, the owner of the certificate and the hostname. Each CA has its own certificate which can be signed by another CA certificate. The top-most CA is cald the Root CA. The certificate of a Root CA is self-signed. All browsers have a list of trusted certificate authorities and they will trust the information contained in any certificate issued by these trusted certificate authorities. In the case of self-signed certificates, there is no CA to be trusted, so the browser displays a warning because it can't trust the connection. Also if the hostname from the certificate does not match the hostname the browser is connecting to, the browser will display a warning too. So to prevent browser warnings, you must use a certificate issued by a certificate authority trusted by your browser and having a hostname that matches your server hostname. Certificates during installation At installation, a local certificate authority is created and a certificate signed by this authority is issued. This self-signed certificate is valid for the public IP address prompted on the console during installation. Then this certificate is used on the first web console page: On this screen, you can choose to use your own certificate or generate a self- signed one. The hostname must be entered and must resolve to the same IP address you are using to access the administration console. This hostname must also be routable on your network. If you click "Use Self-Signed Cert", then a new certificate will be issued from the local certificate authority with the given hostname and the browser page will be refreshed to use this new certificate. Note: if your use the IP address as hostname, then no new certificate will be issued. You can also provide your own certificate and key pair. They can be uploaded to the server or you can specify the full path if they are already stored on the server. In any case, the CN of the uploaded certificate must match the hostname specified. Click "Upload & Continue" button and the browser page will be refreshed to use the provided certificate. Certificates and private keys format HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 36 of 74

37 The format used must be PEM. This is a Base64-encoded structure starting and ending with a header, like so: -----BEGIN CERTIFICATE----- MIIFmzCCA4OgAwIBAgIJAMprPVN0fZbHMA0GCSqGSIb3DQEBCwUAMGQxCzAJBgNV BAYTAkZSMQ8wDQYDVQQIDAZGcmFuY2UxETAPBgNVBAcMCEJlc2FuY29uMRAwDgYD [...] +89xL5jL/WctokA9TLqQlrr68U2erk6PYZMFnDI+CqKEPp9CChHxIA6yrTo3Fwo2 r2wnbstgrqnqk5fnt7plaaeech8fke41klrntufgho35ys4msfdztqw87+7vkhy= -----END CERTIFICATE----- The header is -----BEGIN CERTIFICATE----- for a certificate, and -----BEGIN PRIVATE KEY----- for a private key. The certificate file should also contain the CA certificate chain used to sign the certificate. The server certificate should come first, followed by the issuing CA certificate until the last certificate issued by a Root CA. The private key file must not be protected with a passphrase. A passphrase would prevent the web server to load it. Modify the certificate of the administration console The certificate used when accessing the administration console can be changed in the console settings, in "TLS Key & Cert" section. Three options are proposed: "Self-signed (generated)", "Server path", "Upload files" The certificate Common Name (CN) must match the value of the "Management Console Hostname" parameter. Self-signed (generated) Select this option to let the system generate a certificate using its local Certificate Authority. The issued certificate will be self-signed and browsers will display a warning when connecting. This is a good choice for testing a setup without bothering with certificate generation. Server path Select this option if the key and certificate is already stored on the server. Enter the absolute path to get them on the server. Upload files Select this option to upload the certificate and the key to the server. Save Click save button to confirm your choice and start using the certificate. You may neeed to reload your browser. Modify the certificate of the HipTest application When accessing the HipTest application, you can choose to use the same certificate for both the hiptest app and the administration console, or use separate certificates and hostname. This can be set in the Settings tab of the administration console HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 37 of 74

38 Use same certificate as the console When selecting "Use same certificate/key as admin console" then the certificate used to access the console will be used to access HipTest too. That means that the HipTest hostname and the console administration hostname must be the same, or the certificate must handle both hostnames if they are different. This is the default setting after a HipTest installation. Use custom certificate If you choose to use different certificates for both HipTest and the administration console, you should use separate hostnames. Then upload the certificate file and the private key file and click "Verify TLS settings" button to ensure the uploaded files are valid and that they match the hostname. Valid: Invalid because the hostname does not match: Once the certificate is valid, press "Save" button at the bottom of the page to apply changes and restart HipTest and use the given certificate. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 38 of 74

39 Linking JIRA to HipTest Enterprise If using the HipTest add-on with your JIRA server installation, you will have to configure it to contact your HipTest Enterprise instance instead of JIRA Server In the Jira administation menu, select Add-ons and select HipTest plugin for JIRA on the Manage add-ons page. Click on the Configure button: Enter the URL of your HipTest server and save: You're now ready to use JIRA server with your HipTest on-premises server. JIRA Cloud In order to install the Add-on, your HipTest on-premises instance needs to be accessible from the Internet, so that JIRA Cloud servers can access it. In the Jira administation menu, select Add-ons and click on the Upload add-on link HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 39 of 74

40 Fill the From this URL field with and click on Upload button. For instance, if your HipTest Enterprise domain is hiptest.example.com, then the add-on URL must be You re now ready to use JIRA Cloud with your HipTest on-premises server. Make JIRA accept HipTest self-signed certificate You can find detailed information about JIRA connecting to HipTest through SSL in JIRA documentation in the "Connecting to SSL services" chapter located at Meanwhile, the information provided in this section should be enough to get your JIRA instance connect to HipTest. When using HipTest default certificate or your own self-signed certificate, JIRA won't trust it and will refuse to connect to HipTest with the following error: javax.net.ssl.sslhandshakeexception When checking SSL certificate validity, JIRA checks if it has been signed by a Certificate Authority (CA) that it trusts. The list of trusted Certificate Authorities is stored in the Java truststore. The location of this file vary accross systems. It should be located at "JAVA_HOME/lib/security/cacerts". This location can be overriden with the java property "javax.net.ssl.truststore". Popular CA certificates like Verisign, Equifax, Thawte, etc. are already stored in it. You can run keytool -list -keystore /etc/ssl/certs/java/cacerts -storepass changeit to see them all. To make JIRA accept the SSL certificate used by HipTest, this certificate (or the certificate of its Certificate Authority) has to be added to Java HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 40 of 74

41 trustore. If you are using the default certificate generated at installation, the CA certificate to import is located at /var/lib/replicated/secrets/ca.crt. This file is the CA certificate that has been used to issue the server certificate used by HipTest. If you are using your own self-signed certificate, the certificate to import is the certificate itself. If you are using a certificate issued by your own Public Key Infrastructure, the certificate to import is the one used to sign the server certificate. If you are using a certificate issued by a recognized Certificate Authority, everything should be alright. Here are the steps to import the certificate into Java trustore: 1. Copy the certificate file to your JIRA server in a known location, like /tmp/hiptest.crt. 2. From the JIRA server, import the CA certificate into the Java truststore using the following command: sudo keytool -import -keystore /etc/ssl/certs/java/cacerts -alias hiptest -storepass changeit -file /tmp/hiptest.crt This will add the certificate to the list of certificates trusted by Java and JIRA. 3. Try again and this time, this should work correctly. To ensure that you added the certificate to the right keystore, check the value of JAVA_HOME. It can be found via the java.home property under Administration > System Settings from JIRA. Then the keystore will be located in <JAVA_HOME>/jre/lib/security/cacerts. Configuring database HipTest uses a PostgreSQL database to store its data. This database is embedded into the on-premises solution as a Docker container. For performance, scalability and maintainability reasons, you may want to use a third-party database service like Amazon RDS. This can be configured in the settings tab. Embedded database Using embedded database is the default. The database is exposed on port This can be changed if it conflicts with other ports. External database When using an external database, you totally own the database instance. You are in charge of its maintenance and backup. The snapshots taken from the administration dashboard will not include any database data. The database must be PostgreSQL 10.x. Enter the connection settings and save to use the external database. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 41 of 74

42 Migrating data from embedded database to external database It is possible to migrate data from the embedded database to the external database. The process is to save the embedded database in a dump file, switch to the external database and restore the dump file to the external database. Here are the steps: 1. Ensure you are using the embedded database From the administration console, go to settings page and ensure that you are using the embedded database. If it is already in use, you have nothing to do and you can jump to step 2. If you are not using it yet, select "Use embedded database" and apply changes by clicking the "Save" button. The HipTest app will restart and use the embedded database. 2. Create a dump of the database Run the following commands on the server: source /etc/replicated.alias replicated admin backup-postgres-db This will dump the embedded database data and save it at /var/lib/hiptest/db_backups/db.dump. 3. Switch to the external database From the administration console, go to settings page and choose to use the external database. Enter your database hostname, port and credentials. Apply changes. The HipTest app will restart and use the external database. 4. Restore the dump of the database Warning: be 100% sure you have switched to the external database! Once the HipTest application is fully started, run the following commands on the server: source /etc/replicated.alias replicated admin restore-postgres-db This will read /var/lib/hiptest/db_backups/db.dump and restore it to the external database. 5. Restart the HipTest application Restoring database implies interrupting some database connections and some containers must be restarted after this interruption. From the dashboard, click "Stop Now", and once it's fully stopped, click "Start Now". The migration of data from embedded database to external database is complete. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 42 of 74

43 Operations Restarting HipTest on-premises To restart the HipTest service, you have to restart all Replicated services on the server: replicated, replicated-operator and replicated-ui. N.B: For RHEL based distributions, this guide will assume you are using systemd as the default init system The supported init systems are: systemd, upstart and sysvinit. Here are the commands to use depending on the init system For systemd systemctl restart replicated replicated-agent replicated-ui For upstart restart replicated restart replicated-agent restart replicated-ui For sysvinit service replicated restart service replicated-agent restart service replicated-ui restart To confirm which init system is in use, you can use the following script if [[ "`/sbin/init --version 2>/dev/null`" =~ upstart ]]; then INIT_SYSTEM=upstart echo >&2 "upstart is used as the init system" elif [[ "`systemctl 2>/dev/null`" =~ -\.mount ]]; then INIT_SYSTEM=systemd echo >&2 "systemd is used as the init system" elif [ -f /etc/init.d/cron ] && [! -h /etc/init.d/cron ]; then INIT_SYSTEM=sysvinit echo >&2 "sysvinit is used as the init system" else echo >&2 "Error: failed to detect init system or unsupported." fi Stopping, starting and getting status To stop, start or getting status of the services, use start, stop or status command in place of the restart command. For example, to stop the replicated service on RedHat Enterprise Linux: systemctl stop replicated Updating server IP address If you need to update the server IP address you will need to manually edit Replicated config files. 1. Stop all replicated services 2. Change IP address in config files 3. Start all replicated services 4. Check that IP address changed in web administration console 5. Update IP address of HipTest service in settings 1. Stop all replicated services For Debian/Ubuntu HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 43 of 74

44 service replicated stop service replicated-operator stop service replicated-ui stop For CentOS/RedHat Enterprise Linux/Fedora systemctl stop replicated replicated-operator replicated-ui Then ensure that services are fully stopped: docker ps grep replicated This should yield no results, except replicated-statsd and replicated-premkit. 2. Change IP address in config files The IP address is stored in 2 different places: /etc/default/replicated /etc/default/replicated-operator It must be updated in all files. To edit the files, you can use the nano command: nano /etc/default/replicated nano /etc/default/replicated-operator Here is how the files should look like if the IP address was : /etc/default/replicated RELEASE_CHANNEL=stable PRIVATE_ADDRESS= SKIP_OPERATOR_INSTALL=0 REPLICATED_OPTS="-e LOG_LEVEL=info -e DAEMON_TOKEN=Wu39SFBBo0Qn5GD5iMdVRPhs7EsMZWdc -e NODENAME=tom" /etc/replicated-agent.conf RELEASE_CHANNEL=stable DAEMON_ENDPOINT=[ ]:9879 DAEMON_TOKEN=Wu39SFBBo0Qn5GD5iMdVRPhs7EsMZWdc DAEMON_HOST=[ ] PRIVATE_ADDRESS= REPLICATED_OPERATOR_OPTS="-e LOG_LEVEL=info -e PUBLIC_ADDRESS= e TAGS=local -e NODENAME=tom" 3. Start all replicated services For Debian/Ubuntu service replicated start service replicated-operator start service replicated-ui start For CentOS/RedHat Enterprise Linux/Fedora systemctl start replicated replicated-operator replicated-ui 4. Check that IP address changed in web administration console Now that all replicated services are up and running, you can go to the web administration console to check that the IP address has been updated on the Cluster page HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 44 of 74

45 If the IP address did not update automatically, carefully review the performed steps to ensure they all have been performed. If it still not updates, grab the support bundle and send it to We'll help you fix it. 5. Update IP address of HipTest service in settings In the web console, go to the Setting page. From there, update the HipTest hostname to match your IP address. Of course, you do not need to modify it if you are using a hostname to access the service (like hiptest.mycompany.com). Update HTTP Proxy / set HTTP Proxy after install There are several files that need to be modified, depending on the service manager. Upstart Update the file /etc/default/docker with updated http_proxy environment variable. Update the file /etc/default/replicated with updated HTTP_PROXY variable. Restart docker restart docker Systemd Follow instructions here HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 45 of 74

46 Update the file /etc/sysconfig/replicated with updated HTTP_PROXY variable. Restart docker systemctl restart docker HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 46 of 74

47 Upgrade HipTest Enterprise is composed of two parts: the HipTest application and the technology to provide the application as an installable package. Both can be upgraded independently. Upgrading Replicated Replicated is the technology making it possible to ship HipTest Enterprise as a package easy to install and administer. Key features include oneclick updates, audit logging, snapshot and restore utilities, friendly interface and so on. Which Replicated version do I use? To know your replicated version: 1. Go to the Support section from the administration console. 2. The Replicated version is the first number. On the screenshot, it is Upgrade to latest Replicated v2.x Upgrading is done by running the same commands used during initial installation. Replicated can be upgraded without any HipTest downtime. Online version To upgrade all Replicated components to their latest release, run the installation script command again: curl -ssl sudo bash This will download the latests Replicated binaries, install them and restart Replicated while keeping HipTest up. Airgap version Replicated can be upgraded by downloading the latest release from and running the following commands: tar xzvf replicated.tar.gz cat./install.sh sudo bash -s airgap This will unpack the latests Replicated binaries, install them and restart Replicated while keeping HipTest up. Upgrading HipTest application HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 47 of 74

48 Upgrading the application is done from the administration console dashboard. Note that during upgrade, HipTest will not be available to users until the upgrade completes. Upgrading to latest HipTest application version From the dashboard, the current version of HipTest is displayed. You can check for new versions by clicking on the "Check Now" button. If an update is available, the following message will be displayed: Click on the "View Update" button to go to the release history screen. On this screen, you can see all available versions and their related release notes. Click on "Install Update" button to perform the upgrade to the latest HipTest software. Note that during upgrade, the service is down until it finishes. Now on the dashboard, you should see the service is up and running. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 48 of 74

49 Congratulations, you have just upgraded HipTest! HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 49 of 74

50 Airgap Upgrade Upgrading requires to download the new airgap package, to copy it onto the HipTest server and to run the upgrade from the administration console. Note that during upgrade, HipTest will not be available to users until the upgrade completes. Download the airgap package Use the HipTest airgap download link provided by HipTest. A password is prompted: Use the password that HipTest provided you to access the list of available HipTest releases. Download the desired airgap package. The top one is the most recent release. Click on the "Download" button to reveal the download link. If you are downloading from the command line using curl or wget, it is important that the downloaded filename has a name ending with.airgap extension. Filenames without the.airgap extension won't be seen. Here are the commands to be used: # with curl curl --remote-name --remote-header-name <download-link> # with wget wget --content-disposition <download-link> Copy the airgap package onto the server Copy the airgap package to a location on your HipTest server. Using the same path you used for the installation is fine. The filename must end with the.airgap extension. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 50 of 74

51 Set the path to the airgap package From the web administration console, go to the console settings using the cog menu in the top bar The "Airgap Settings" section defines the "Update Path" where the airgap packages should be searched for. Ensure that this settings matches the path where you copied the airgap package you want to install. Note that you can also update the license file from this section. Perform the upgrade From the dashboard, there is a button to check for updates. Click the "Check Now" button to search for new airgap packages from the "Update Path" configured before. When a more recent airgap package is found, the following popup is displayed: Click on the "View Update" button to go to the release history screen. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 51 of 74

52 If the update does not show up, it may mean that the file is not at the right place, or that it does not end with.airgap, or that it was corrupted during transfer. From there, you see the available releases, one per airgap package file in the Update Path. You can review the release notes and install any newer release. Click on "Install Update" button to perform the upgrade. It will extract the new images, install them and restart HipTest. Note that during upgrade, the service is down until it finishes. Now on the dashboard, you should see the service is up and running. Congratulations, you have just upgraded HipTest! HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 52 of 74

53 Backup & Restore Backup The administration console has the ability to take snapshots of your HipTest on-premises installation. This feature is available since HipTest onpremises version The snapshot feature is for server migration or disaster recovery purposes. If you are using an external database, the snapshot will not include any data from it. You can configure snapshots from the console settings: Backup strategy The backup strategy can be configured to be Local, S3 or SFTP: Local: snapshots are created on local disk. The default location is: /var/lib/replicated/snapshots. This is the slowest option and should not be used in production. Slowest because under the hood it runs a docker container to copy each single file which adds significant overhead. It can also be risky to store all data on the same disk as an hardware failure would cause data and backups to be lost altogether. It would be safer to store the backups on a different physical host or SAN. If you really have no other other option than storing locally, you should prefer using SFTP pointing to localhost as it will be 3 to 10 times faster. S3: snapshots are created on AWS S3, Amazon Web Services Simple Storage Service. You need to provide the bucket name and region, and proper credentials. SFTP: snapshots are created on a remote host, which it connects to using SSH. SFTP stands for SSH File Transfer Protocol. You need to provide the snapshots destination folder on the remote host, the remote server host name. SSH key- based authentication is used to connect to the remote host without prompting for a password. So it needs the username which will be used for the connection, and the private key in PEM format. The private key must not be protected by a passphrase and the public key must be in the.ssh/authorized_keys file on the remote host with appropriate permissions. Please refer to ssh manual to set up key authentication correctly. For a production server, use either S3 or SFTP. Local should be used for testing only as it is slower and more risky in the case of an hardware failure. Automatic snapshots HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 53 of 74

54 You can configure automatic snapshots from the console settings to make regular backups: 1. Select how many snapshots to keep. 3 snapshots are kept by default. 2. Snapshot timeout is the maximum duration of the backup process. After this duration, the snapshot is cancelled and considered failed time given. 30 minutes should be enough. 3. Configure the frequency of automatic snapshots and the time at which the snapshot is created. Starting a snapshot At any moment you can take a snapshot of HipTest. To do so, click on the "Start Snapshot" button from the dashboard. The process takes a couple of minutes to complete. List snapshots You can list your snapshots from the cog menu: From there, you can see all snapshots along with their applicative version and the creation date. Restore HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 54 of 74

55 To restore you need to create a fresh install of replicated which you can find instructions for at first chapter. Before running the web console at place a copy of the full snapshot directory on the host. Proceed through the https setup screen and on the upload your license page click the 'restore from a snapshot' link. You will be redirected to this screen: 1. Enter the path on the host where you have copied the snapshots folder, 2. Click "Browse snapshots", 3. Locate the latest version you would like to backup from and click the "Restore" button. You will be given options to download the restored volumes. Click "Restore" button to continue. Once volumes have been restored, you will be redirected to the cluster screen: HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 55 of 74

56 The restore is not completed yet. Data is in the volumes, it need to be transferred to the database servers. HipTest needs to be started. Start HipTest from the dashboard: There are commands to run manually from the host. They are different depending on wether you use embedded or external database servers. If you are using the embedded database servers (the default) open a terminal on the host and enter the following commands to restore all database servers and reindex documents: source /etc/replicated.alias replicated admin restore-postgres-db replicated admin restore-mongo-db replicated admin restore-elasticsearch-db Here is a sample of the output you will get: If you are using external database servers, restore your data from backups you made (if needed), open a terminal and enter the following commands to reindex documents: source /etc/replicated.alias replicated admin restore-elasticsearch-db HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 56 of 74

57 During the database restore, active database connections have been interrupted. That's why the dashboard may indicate that some containers have stopped unexpectedly. Click "Start Now" to restart HipTest. The restore is now complete. Migrating from HipTest Cloud It is possible to migrate all your data from HipTest Cloud to a on-premises installation. Importing data from Cloud overwrites all existing HipTest data of an on-premises installation, so it is really meant to be used on first installation. If you are interested, contact support@hiptest.net so we can send you an archive containing your cloud data. The archive data we send you contains a partial database dump and your attachments. Extract it at the root of your server and then delete it: cd / sudo tar xzf /tmp/cloud_data.tar.gz shred /tmp/cloud_data.tar.gz Then you will need to perform the same steps as if you were restoring from a backup. Open a terminal on the host and enter the following commands: source /etc/replicated.alias replicated admin restore-postgres-db replicated admin restore-elasticsearch-db Here is a sample of the output you will get: During the database restore, active database connections have been interrupted. That's why the dashboard indicates that some containers have stopped unexpectedly. Click "Start Now" to restart HipTest. The migration is now complete. You can log in to HipTest using the same credentials you had on the Cloud version. In the administration console settings, you should set the username of the person in charge of HipTest on-premises in your organization. This user's will be displayed on the HipTest landing page so that new users know which person to reach if they want an account. HipTest on-premises - Installation guide (1.6.0) 2019 HipTest Page 57 of 74