install-script

A repository for shell scripts that aid in the installation of LabKey products and services.

Supported Operating Systems

• AlmaLinux 9
• Amazon Linux v2
• RedHat Enterprise Linux 9
• Ubuntu 20.04 & 22.04

LabKey Install Script Usage Examples

For portability and maintainability, install scripts in this repo expect input to be supplied as environment variables. Below you'll find a couple examples of how to invoke install scripts while supplying those environment variables.

Example 1: Use environment variables on the command line as inputs to the installation script

Environment variable inputs can be provided as part of the command line when invoking the installation script.

sudo su -
LABKEY_COMPANY_NAME='Megadodo Publications' LABKEY_DEFAULT_DOMAIN='megadodo.com' LABKEY_BASE_SERVER_URL='https://megadodo.com' LABKEY_VERSION='21.7.1' ./install-labkey.bash

Another option for achieving super-user privileges while maintaining environment variables is sudo's "-E" flag. Which passes the current environment through to the command you're using sudo to run:

export LABKEY_COMPANY_NAME='Megadodo Publications' LABKEY_DEFAULT_DOMAIN='megadodo.com' LABKEY_BASE_SERVER_URL='https://megadodo.com' LABKEY_VERSION='21.7.1'
sudo -E ./install-labkey.bash

Example 2: Use a source script to provide Environment variables inputs

The installation scripts install-labkey.bash and install-wcp.bash utilize a myriad of installation variables. The majority of which have reasonable defaults. (See the documented Inputs section below for more details on the available installation variables.) However, a minimum set of installation variables must be supplied to instantiate systems successfully. To ease installation some sample environment files have been provided. Please see the included sample_embedded_envs.sh, sample_std_tomcat_envs.sh, and sample_wcp_envs.sh in the repo. Using one of these users can edit or create their own environments file and invoke the installation script as follows:

sudo su -
source ./sample_embedded_envs.sh
./install-labkey.bash

WCP Install Script Usage

The WCP installation script install-wcp.bash depends on the install-labkey.bash script for many common installation functions. The URL to this script is a required input. To ease installation a sample environment file has been provided.

sudo su -
source ./sample_wcp_envs.sh
./install-wcp.bash

Sample Helper Scripts Usage

In addition to the sample installation environment files. This repo includes a few other sample environment files to assist in various configurations and use cases. The power and flexibility of the script's modular functions allow for varied use cases such as installing java & tomcat, updating tomcat, etc. We have included a few examples which demonstrate these use cases.

• sample_install_only_java_env.sh - Sample env file that installs only OS dependencies and Java
• sample_install_only_tomcat_env.sh - Sample env file to install only Tomcat and Java - can also be used to update Tomcat

Inputs Reference

The following tables list the available input variables and default values. In the table below, NULL is the Bash definition of "null". E.g.: an empty string.

General Install Inputs

Both tomcat Install Type Inputs

Standard tomcat Install Type Inputs

Embedded tomcat Install Type Inputs

Tomcat TLS Certificates Inputs

Tomcat properties used in application.properties for embedded installations

Postgres Inputs

SMTP Inputs

ALT File Root Inputs

WCP Inputs

Applies only to install-wcp.bash

Invocation

To avoid the complexity of parsing CLI flags in bash or with getopts, and to maximize the portability of the script, all inputs to the script should be supplied as Environment Variables. So invocation is expected to look like:

LABKEY_COMPANY_NAME='Megadodo Publications' ... ./install-labkey.bash

Development

Installation of LabKey products and service can be described in "steps" and that's the fundamental abstraction this script/repo strive to leverage.

You'll find the install script segmented into Bash functions which serve as these "steps" and are named as such. The collected body of "step functions" are then called in the main loop of the script in an order that makes sense.

As with any Bash script, the guiding principles should be to fail early and to provide sensible defaults that would allow someone to run the script without any input, and receive a functional (albeit generically configured) instance of the product.

Some generic functions designed to keep logic within the script manageable are provided: platform() and platform_version() which will inspect /etc/os-release and/or execute lsb_release to identify the OS and the OS version:

if [[ "$(platform)" == 'ubuntu' ]]; then
  echo 'do something specific to Ubuntu'
fi

case "_$(platform)" in
  _alpine)
    sudo apk update
    sudo apk add sl
    ;;
  _ubuntu)
    sudo apt-get update
    sudo apt-get install sl
    ;;
  _*)
    echo "can't install sl on unrecognized platform: \"$(platform)\""
    ;;
esac

The tests and other shells scripts may use the LABKEY_INSTALL_SKIP_MAIN environment variable when sourceing this script to allow for setting all of the script's functions without executing them.

Similarly, a general mechanism for skipping "step functions" has been included that allows users to provide the step's name in an environment variable of the shape: LABKEY_INSTALL_SKIP_<step fn name>_STEP which will cause the script to.. you guessed it.. skip that step. For example, to skip the intro step function and void printing the LabKey ascii art: LABKEY_INSTALL_SKIP_INTRO_STEP=1 ./install-labkey.sh This is accomplished by the _skip_step() function which should be included as the first line in any "step functions":

function step_example() {
  if _skip_step "${FUNCNAME[0]/step_/}"; then return 0; fi

  echo 'an example function'
}

Setting LABKEY_INSTALL_SKIP_EXAMPLE_STEP=1 would cause the script in the above example to void printing "an example step".

Writing Tests

This repo uses an "xUnit"-style testing tool called shunit2. shunit2 was chosen over bats due to the lack of strict mode support in bats when sourcing other scripts and their functions. See also: Support for "unofficial strict mode"?.

shunit2 uses "assertions" as the currency with which code functionality is purchased. Some common, self-explanatory assertions are: assertEquals, assertNull, and assertTrue. Assertions generally follow the format: <assertionFunction> <message upon failure> <expected results> <actual results> and in true Bash fashion, mostly operate on strings. E.g.: assertEquals 'values not equal' 'apple' "$(fn_which_prints_pear)" would fail assuming fn_which_prints_pear would print "pear".

Tests for specific functionality of a given installation "step" can be written to a test script file named after that step (as with step_intro_test.sh). And tests for internal functions can be written to the internals.sh script file.

Try to avoid writing tests that verify the functionality of reliable tools like mkdir.

Running tests Locally

An advantage of having a "purely bash" testing framework is the ability to just add the shunit2 source file into one's repo, so you'll both find it within the test directory and excluded from shell script linting in the github actions.

Since a copy of the shunit2 source code exists in this repo, the tests are self-contained and, assuming they have execute permissions, can be run simply as:

./test/internals.sh

A small helper script designed to run all script files ending in .sh in the test directory has been included: runner.sh. And is used in the github actions. This can also be executed to run all the tests.

Running Github Actions Locally

If you don't wish to install shellcheck/shfmt/yamllint/etc. locally, you can run the github actions locally using a tool called act (available via homebrew on mac):

act -s 'GITHUB_TOKEN=<github token>'

# | test_platform_lsb_release
# | test_platform_version_lsb_release
# |
# | Ran 2 tests.
# |
# | OK
# | test_step_skipping
# |
# | Ran 1 test.
# |
# | OK

All scripts derived from this repo's template.sh script should support a DEBUG flag that enables set -x when set to a value other than an empty string:

DEBUG=1 ./install-labkey.bash

Reference

• Spring application.properties
• shunit2 assertions
• bash "strict mode"
• sh-checker Github Action
• shellcheck codes
• shfmt flags