Skip to main content

Initial application installation

This section describes installing an application built on the Genesis Application Platform. Readers need to have some experience of Linux system administration.

Required artifacts​

Application distribution​

After a build process is finished, the result is an application distribution artifact. At present, Genesis applications are built as ZIP files ready to be copied to and unzipped on the target host(s).

When using the standard configuration of a Genesis application, a build will generate:

  • an application distribution named genesisproduct-{appName}-distribution-{appVersion}-bin.zip which contains the application's own libraries, config and scripts
  • a site-specific distribution names {app-name}-site-specific-{appVersion}-bin.zip which contains the site-specific configuration and scripts for the application.

These, along with dependent Genesis distributions required by the app, will need to be installed on hosts per the instructions further down in this page.

Genesis distributions​

These are distributions which are maintained by Genesis, and power all Genesis applications. They include all the libraries, scripts and config required by the given module. These include:

These distribution zip bundles are released to the Genesis artifactory along with the underlying libs, and are contained in *-distribution folders under the libs-release-client repository. For example the main Genesis Server framework distributions are found here. You'll need access to Genesis Server artifacts.

When the version of any of these Genesis dependencies is updated in the application, the related distribution zip for that release needs to be added onto the box and replace the respective distribution that is already there.

Where using the Genesis build plugin's buildImage, it will read the application codebase to determine the module versions to include and further docker commands can be used to deploy them. If you are setting things up manually, you can to determine which module versions in the same way buildImage does by reading the dependencies from the application's codebase.

Installing code​

All of the required distribution zips (those of the application, and it's Genesis dependencies) will need to be put onto the host and unzipped. To recap, here's an overview of the distributions needed:

  • The application distribution zip file
  • The application site-specific distribution zip file
  • The Genesis dependency distribution zip files
  • The client code zip file

When using the buildImage and docker deployment scripts, a lot of this will be taken care of. The following section gives an overview of what is happening and advice in case you are building your own build and deployment scripts.

Application paths​

The default application install path for Genesis-built applications is chosen to divide the application up (for when more than one application is installed on a host) and to manage versions.

For portability, Genesis application artifacts represent complete installs, with everything needed placed inside one directory tree.

The default path for server-side code is generated as follows:

installDate=$(date +%Y%m%d)
runUser=<provide the username the application will run as>

# make the server directory and maintain a symlink in the runUser's homedir
mkdir -p /data/${runUser}/server/${installDate}/run
rm -f /home/${runUser}/run
ln -s /data/${runUser}/server/${installDate}/run /home/${runUser}/run

The web code is served up by nginx, and so it is installed separately from the server-side code. The default path for the web code is generated as follows:

installDate=$(date +%Y%m%d)
runUser=<provide the username the application will run as>

# make the directory and create a stable path for the nginx document root
mkdir -p /data/${runUser}/web-${installDate}
rm -f /data/${runUser}/web
ln -s /data/${runUser}/web-${installDate} /data/${runUser}/web

Unzipping the code​

A quick note on absolute paths​

The build artifacts are unlikely to contain absolute paths for files, so it is important to have the correct extract directory when unzipping them.

You can use the zipinfo command (part of the unzip package) to examine the files inside the ZIP.

Below is sample output for part of a Genesis Server Framework distribution ZIP.

$ zipinfo genesis-distribution-6.1.0-bin.zip 
Archive:  genesis-distribution-6.1.0-bin.zip
Zip file size: 234214088 bytes, number of entries: 573
drwxr-xr-x  2.0 unx        0 b- defN 22-Jul-10 16:24 genesis/
drwxr-xr-x  2.0 unx        0 b- defN 22-Jul-10 16:24 genesis/bin/
-rw-r--r--  2.0 unx   118037 b- defN 22-Jul-10 16:04 genesis/bin/genesis-consolidator2-6.1.0.jar
-rw-r--r--  2.0 unx   531691 b- defN 22-Jul-10 16:04 genesis/bin/genesis-cluster-6.1.0.jar
-rw-r--r--  2.0 unx   101884 b- defN 22-Jul-10 16:24 genesis/bin/genesis-webmon-6.1.0.jar
(and more)

Server distributions​

The following is applicable to all of your application's server distribution artifacts, including the application, site-specific and the genesis provided distributions detailed earlier in this page.

The ZIP files contain relative paths, so the extract path matters. Therefore, either chdir to the correct directory, or use a command-line argument to unzip.

installDir=$(date +%Y%m%d)
runUser=<provide the username the application will run as>

cd /data/${runUser}/server/${installDate}/run; unzip <absolute path to application ZIP>

# OR

unzip <absolute path to application ZIP> -d /data/${runUser}/server/${installDate}/run

Web code​

The web ZIP is also likely to contain relative paths, so again, the extract path matters. Therefore, either chdir to the correct directory, or use a command-line argument to unzip.

installDir=$(date +%Y%m%d)
runUser=<provide the username the application will run as>

cd /data/${runUser}/web-${installDate}; unzip <absolute path to web ZIP>

# OR

unzip <absolute path to web ZIP> -d /data/${runUser}/web-${installDate}

Post-install tasks​

Following the installation of the distributions, two key Genesis commands must be run to complete the installation. Both must be run as the application user, as they will generate files with the ownership of the user running the command.

  • The command genesisInstall creates a set of files, consolidating config to create a unified view of it, which the processes will consume. It is needed after an install or an upgrade. For more details, see the commands reference.

  • The command remap --commit handles the data model, and thus the database schema. Its purpose is to generate DAO (data access object) classes and apply the data model schema to the database. For more details, see the commands reference.