Design and Usage of the InitBuilder components

Introduction

InitBuilder gives you a standard, predictable and portable way of controlling the lifecycle of your applications at a process level. For example, using InitBuilder,
you to setup something like Tomcat on your Windows laptop and move it to a remote Linux machine.

TODO example

InitBuilder introduces standard system variables, directory structures and writes portable initialization scripts. The initialization scripts help level the operating environment across operating system platforms.
Standard directory paths help you avoid multi-tenancy conflicts and the need to access the root user.

Vocabulary

Platform - a cross-platform product, like JBoss, Tomcat, Apache httpd, which as base binaries and configuration applicable to all instantiations of it. Platforms that do not work on most operating systems are out of scope. These include products that only exist on Windows such as IIS
Instance - an instance of a platform, most often implemented as a process on the host operating system. Multiple instances must be able to run on the same host without conflicts.
Environment Variable - Environment variables are a set of dynamic named values that can affect the way running processes will behave on a computer. ref
Environment Module - Introduces environment variables for a particular scope. These are overridable.

Design

Environment Management

Environment Variables are typically set in a user profile.
However, this user profile is generally not built from a source controlled system, and is unpredictable at best. Process portability requires that we ensure that important variables such as ones that maintain time zone information (TZ on Unix) and system library search path
(LD_LIBRARY_PATH on Unix or PATH on windows) do not bleed in from the user or the operating system.
When these are not controlled, application portability cannot be guaranteed.
This problem is well known, and projects such as Modules seek to address it.

Like other parts of InitBuilder, this process has to be portable. The "important" environment variables are not the same across Windows and UNIX-like operating systems like Linux.
InitBuilder process involves the same process, and implements it differently based on the os.
Basically, the script generated by InitBuilder has a sync command.
This sync command reads environment modules and creates a script or service used to run the Instance in the background.

Clearing the Environment

There are a couple environment variables that are named differently on operating system families.
We have normalized names of these so that they can be set in a cross-platform way.

LIBRARY_PATH - In unix this is LD_LIBRARY_PATH; in windows, this is an addition to PATH; in java, this is java.library.path

Environment Modules

Environment modules are exposed in two ways shell functions and source files. These are used to compose the runtime environment of the Instance.

shell functions - defined in the init script itself to reduce footprint on the host.
source files - files named environment.bash (on unix) or environment.cmd (on windows).

Environment scopes

CrossPlatform - shell function - In order to work cross-platform and without creating a lot of complexity, some shortcuts are taken.
For example, the process depends on the ps auxwww command to work.
As such, on Solaris hosts, this implies /usr/ucb/ps be found first in the PATH.
Eventhough the path /usr/ucb isn't present on other UNIX-style hosts, paths that are not found do not hurt anything. Pragmatically, we prefix /usr/ucb to all unix paths so that we don't need to write a function to determine this per-platform.
Instance - shell function - sets up variables like INSTANCE_NAME, LISTEN_HOST, and LISTEN_PORT
Platform - shell function - sets up additional variables like PATH and NATIVE_PATH, and binds args to the above parameters.
Deployment - optional source file - any deviations needed for the specific application, such as additional java args or classpath entries (in Java), or additional NATIVE_PATH for things like apache httpd.

Operations

All operations need a minimum environment setup such that operations such as ps can operate.
Accordingly, the init script InitBuilder creates always does the following:

zero out environment variables known to conflict with applications
load CrossPlatform module

Sync

Sync is a process that composes the environment of a process. This is not performed inline, as the running process may have a different version of variables from the prior one.
Accordingly, Sync is used to establish a new environment for a process to run.
In UNIX, this implies creation of a shell script, In Windows, this implies creation of a Service.

Stop the service, if not already running
- this unlocks files that we may need to overwrite. For example, in Windows the corresponding service must be stopped before it can be re-written.
Load Instance module
Load Platform module
Load Deployment module
Write new Start process
- In Unix, this is technically a shell script that can be nohuped.
  This is named ${INSTANCE_NAME}.bash in the ${CONFIG_DIR}
- In Windows, we do two things: create a shell script and also a background process
  - The shell script can be used to run the process in the foreground (as supported).
    This is named %INSTANCE_NAME%.cmd in the %CONFIG_DIR%
  - In Windows, it is typically difficult to get a simple shell script to operate in the background as a service non-attached to the current user.
    As such, we use some tool to generate a service called %INSTANCE_NAME%

Stop

Stop the instance running in the background. This is typically performed by looking for INSTANCE_NAME in the process table. This implies that the INSTANCE_NAME must be unique in the process table.

Run

Run the instance in the foreground (where possible). This technically invokes the ${INSTANCE_NAME}.bash or %INSTANCE_NAME%.cmd file previously created by Sync

Start

Start the process in the background. In Unix, we nohup the ${INSTANCE_NAME}.bash. In Windows, we executenet start %INSTANCE_NAME%`;

Status

Returns 0 if the process is running, and 1 if the process isn't.