tdp-simple-app-installer

0.2.1-beta • Public • Published

TDPSimpleAppInstaller

Overview

TDPSimpleAppInstaller is a small module which can be used to run one or more existing/external installer shell scripts in a defined sequence. The aim is to simplify and genericise installation of applications which are formed from independent modules.

Version

Master: 0.2.1-beta Use with caution!

Operating system support

Operating system support should not be a major issue for this module though I always mention in my projects for transparency that I do not design or test for correct function on non-*nix-like OS's (e.g. Windows). If you want to test/develop and submit pull requests for Windows support then I will certainly consider them but likely only if they have minimal to no impact on performance and reliability for *nix-like OSs. The reason for this is simply that I personally don't consider Windows to be a serious server operating system and thus a good direction in which to spend my time and i'm not trying to offend anyone. I realise that others may completely differ in opinion and you're always welcome (obviously) to fork the repo and create your own version with Windows support. If my time were unlimited then I would likely spend some time on Windows support but sadly it's not.

Dependencies

TDPSimpleAppInstaller itself has few dependencies:

Module dependencies

  • fs (core nodejs module) - filesystem utilities
  • path (core nodejs module) - filesystem paths
  • execSync - synchronous child process execution

Test/dev dependencies

  • mocha - javascript test framework
  • should - extended assertions, used in tests with mocha
  • sleep - sleep() function for nodejs (used in one of the test installers to help verify correct execution sequence)

Issues/problems

Please log any issues/problems in Github issues for this project.

Installation

Installation is simple, mainly via NPM:

  1. Ensure you have nodejs and NPM installed and available in your users $PATH (on *nix you can usually check this in a shell/terminal by running which node and/or which npm - the shell will return you the location of the program if it's correctly installed e.g. you'd be shown /usr/local/bin/node or /usr/local/bin/npm - a blank/non-existant result indicates a problem)
  2. Ensure you're in the directory you want to install this module into (it will be installed into ./node_modules/tdp-simple-app-installer)
  3. Run npm install tdp-simple-app-installer to install the module itself

Usage/configuration

Usage is very simple and takes one of two major forms as shown below (note that TDPSimpleAppInstaller is function-scoped so you need to use the new construct to use it).

Programmatic usage (using TDPSimpleAppInstaller in your NodeJS scripts)

Programmatic usage is very simple, example usages are shown below.

Example 1: JS object configuration

var tsai=require("tdp-simple-app-installer");
...
var installerConfig=
{
    installers:
    {
        webFrontEndRole:
        {
            content:"./node_modules/myContentModule/bin/installer option1 option2",
            storage:"./node_modules/myStorageModule/bin/installerV2 option1 option2 option3",			app:"./node_modules/myAppModule/bin/installer option1"
        },
        loggingRole:
        {
            logger:"./node_modules/myLoggingModule/bin/installLogger option1 option2"
        },
        monitoringRole:
        {
            monitoringApp:"./node_modules/myMonitoringModule/bin/installV3"
        }
    },
    logging:
    {
        transport:"Console",
        options:
        {
            level:"debug",
            colorize:true
        }
    },
    options:
    {
        exitOnInstallerError:false
    }
}
var t=new tsai().runInstallers(installerConfig, ["webFrontEndRole", "loggingRole"]);

i.e. you can simply pass a JS object to the runInstallers() function along with an array of roles which you want to run installers for.

Example 2: Path to config file

var tsai=require("tdp-simple-app-installer");
var t=new tsai().runInstallers("/path/to/installerConfigFile.js", ["webFrontEndRole", "loggingRole"]);

Where the path is relative to your script which includes the above (i.e. the full/absolute path will be formed via path.join(__dirname, "/path/to/installerConfigFile.js"))

The JS object has the form shown above, notes:

  • Within the "installers" block, the first dimension key names ("webFrontEnd", "logging", "monitoring" in the above example) are the role titles which are simply used for reference, call them whatever you want
  • Installers will be run in the order defined in the JS object (but bear i mind that if you use numbers in place of the installer block key names ("webFrontEnd", "logging", "monitoring" in the above example) then the numbers will determine the order)
  • The "logging" block of the config object specifies the logging transport and options - winston is used for logging so these are native winston options
  • Any configuration directives which are omitted will have defaults automatically inserted. Default options are described below

Shell-style usage

TDPSimpleAppInstaller can be used as a shell script which may be more convenient in some cases. There is a shell script located at bin/runInstallers which can be invoked via a shell/terminal, taking arguments:

  1. path to to a valid TDPSimpleAppInstaller configuration file (where the path is relative to the location from which your module was installed)
  2. ...N space-separated list of roles for which you want run install scripts
$cd /path/to/where/you/installed/TDPSimpleAppInstaller/from
$./node_modules/tdp-simple-app-installer/bin/runInstallers path/to/myConfigFile.js role1 role2 role3

NOTE: You may need to set the bin/runInstaller file permissions to be executable for the user you're running it as. On *nix-like operating systems you can do this simply (assuming you're in the base module installation directory) by running chmod ug+x bin/runInstallers - you should also check that the relevant user/group owns the file.

Default options

Default options are taken from a template file in config/defaultConfig.js and are:

{
    installers:
    {
        
    },
    logging:
    {
        transport:"Console",
        options:
        {
            level:"debug",
            colorize:true
        }
    },
    options:
    {
        stopOnScriptError:false
    }
}

This means that by default, no installer scripts will be run and winston will log to the console at debug level with colourised/colorized output.

Testing

Tests are in /test and are currently very simple/basic - written in mocha and should. You can run tests from the shell/terminal in the installation directory by simply running mocha.
Important note since the test files included are executable shell scripts (which do nothing other than write to the console), you will need to set their permissions to be executable for the user you're running them as. On *nix-like operating systems you can do this simply (assuming you're in the base module installation directory) by running chmod ug+x test/testInstallers/* - you should also check that the relevant user/group own the files.

To do

  • Log remaining issues and the below in github issues
  • Test NPM module installation
  • Create more exhaustive tests
  • Optimise code

License

TDPSimpleAppInstaller is issued under a Creative Commons attribution share-alike license. This means you can share and adapt the code provided you attribute the original author(s) and you share your resulting source code. If, for some specific reason you need to use this library under a different license then please contact me and i'll see what I can do - though I should mention that I am committed to all my code being open-source so closed licenses will almost certainly not be possible.

Readme

Keywords

none

Package Sidebar

Install

npm i tdp-simple-app-installer

Weekly Downloads

0

Version

0.2.1-beta

License

none

Last publish

Collaborators

  • tdp_org