Simplicité instances manager

This document applies to the Simplicité Instances Manager (SIM) software available on instances servers.

Introduction

Architecture

The SIM offers a command line interface (CLI), a webservices interface (API) - built on top of the CLI - and a web user interface (UI) - built on top of the API - to manage several Simplicité® instances on a server:

Instances manager

Using the CLI offers the full features of the SIM, the API and the UI offers only a subset of the CLI features.

Features

The SIM offers the following features:

All above actions are triggered manually using the CLI, the API or thee UI.

The following actions are triggered by a system-level task scheduler (cron table);

Note that the automatic backup can be configured to export the backup files to a remote storage. Otherwise the backup files are only stored locally on the SIM server.

Implementing pre/post action hooks (see bellow) allow you to customize the standard features of the SIM.

UI usage

The instances manager UI is available on <base URL>/ui.

The UI offers uses the API documented bellow and thus offers equivalent - but somehow limited by a simplified user experience - services.

To create a new instance, enter an instance name (or leave empty for an automatic name) then select the version from the Create button:

To manage an existing instance, clic on one instance in the list, then select the action from the Action button:

The Monitor action opens a new tab and allow to monitor a given instance by tracking record of recurring health checks:

API usage

The instances manager API is available on <base URL>/api.

The API services are using HTTP GET methods only and URL-encoded parameters only. All API responses are JSON-encoded.

For all API services, you can get a pretty printed JSON response by appending &prettyprint=true.

By default the authentication method is HTTP basic auth (username + password), but client certficate authentication can also be used. The examples bellow are using the curl command HTTP client, <credentials> is thus either:

Manager API

Get API configuration

curl -k -s <credentials> <base URL>/api[?action=config]

The action parameter can be ommitted in this case as config is the default action.

Get available versions

curl -k -s <credentials> <base URL>/api?action=versions

Instances API

List instances

curl -k -s <credentials> <base URL>/api?action=list[&param=<version>]

The parameters are:

Create instance

curl -k -s <credentials> <base URL>/api?action=add[&name=<instance name>][&param=<version (or instance name to clone)>][&options[<option name>]=<option value>]

The parameters are:

Stop instance

curl -k -s <credentials> <base URL>/api?action=stop&name=<instance name>[&force=<true|false>]

The parameters are:

Start instance

curl -k -s <credentials> <base URL>/api?action=start&name=<instance name>

The parameters are:

Instance health check

curl -k -s <credentials> <base URL>/api?action=health&name=<instance name>

The parameters are:

Instance I/O credentials

curl -k -s <credentials> <base URL>/api?action=iocredentials&name=<instance name>

The parameters are:

Instance last logs

curl -k -s <credentials> <base URL>/api?action=logs&name=<instance name>

The parameters are:

Download instance logs

curl -k -s <credentials> <base URL>/api?action=download&param=logs&name=<instance name>

The parameters are:

Get access logs report

curl -k -s <credentials> <base URL>/api?action=accesslogs&name=<instance name>

The parameters are:

Upgrade instance

curl -k -s <credentials> <base URL>/api?action=upgrade&name=<instance name>

The parameters are:

Upgrade all automatic upgrade instances

curl -k -s <credentials> <base URL>/api?action=upgradeall

Reset instance

curl -k -s <credentials> <base URL>/api?action=reset&name=<instance name>

The parameters are:

Delete instance

curl -k -s <credentials> <base URL>/api?action=del&name=<instance name>[&force=<true|false>]

The parameters are:

Clone instance

curl -k -s <credentials> <base URL>/api?action=clone&name=<instance name>&param=<cloned instance name>

The parameters are:

Rename instance

curl -k -s <credentials> <base URL>/api?action=rename&name=<instance name>&param=<new instance name>

The parameters are:

Save instance on server

curl -k -s <credentials> <base URL>/api?action=save&name=<instance name>

The parameters are:

Save all automatic save instances on server

curl -k -s <credentials> <base URL>/api?action=saveall

Download instance data

curl -k -s <credentials> <base URL>/api?action=download&param=data&name=<instance name>

The parameters are:

Download instance webapp

curl -k -s <credentials> <base URL>/api?action=download&param=webapp&name=<instance name>

The parameters are:

Download full instance

curl -k -s <credentials> <base URL>/api?action=download&name=<instance name>

The parameters are:

Once downloaded you can simply unzip the instance and launch it locally:

Windows:

@echo off

set JAVA_HOME=<path to your JDK home, e.g. %CD%\jdk-1.8.0>
set PATH=%JAVA_HOME%\bin;%PATH%

set TOMCAT_ROOT=<path to your instance, e.g. %CD%\tomcat>
set TOMCAT_ADMIN_PORT=8005
set TOMCAT_HTTP_PORT=8080
set TOMCAT_HTTPS_PORT=8443

set JAVA_OPTS=%JAVA_OPTS% -server -Dfile.encoding=UTF-8 -Dgit.basedir=%TOMCAT_ROOT%\webapps\ROOT\WEB-INF\git -Dtomcat.adminport=%TOMCAT_ADMIN_PORT% -Dtomcat.httpport=%TOMCAT_HTTP_PORT% -Dtomcat.httpsport=%TOMCAT_HTTPS_PORT%
if not exist %TOMCAT_ROOT%\work mkdir %TOMCAT_ROOT%\work
if not exist %TOMCAT_ROOT%\temp mkdir %TOMCAT_ROOT%\temp
if not exist %TOMCAT_ROOT%\logs mkdir %TOMCAT_ROOT%\logs
cd %TOMCAT_ROOT%\bin
.\startup.bat
exit

Linux:

#!/bin/bash

export JAVA_HOME=<path to your JDK home, e.g. `pwd`/jdk-1.8.0>
export PATH=$JAVA_HOME/bin:$PATH

export TOMCAT_ROOT=<path to your instance, e.g. `pwd`/tomcat>
export TOMCAT_ADMIN_PORT=8005
export TOMCAT_HTTP_PORT=8080
export TOMCAT_HTTPS_PORT=8443

export JAVA_OPTS="$JAVA_OPTS -server -Dfile.encoding=UTF-8 -Dgit.basedir=$TOMCAT_ROOT/webapps/<instance|'ROOT'>/WEB-INF/git -Dtomcat.adminport=$TOMCAT_ADMIN_PORT -Dtomcat.httpport=$TOMCAT_HTTP_PORT -Dtomcat.httpsport=$TOMCAT_HTTPS_PORT"
[ ! -d $TOMCAT_ROOT/work ] && mkdir $TOMCAT_ROOT/work
[ ! -d $TOMCAT_ROOT/temp ] && mkdir $TOMCAT_ROOT/temp
[ ! -d $TOMCAT_ROOT/logs ] && mkdir $TOMCAT_ROOT/logs
cd $TOMCAT_ROOT/bin
./startup.sh

Instance actions history

curl -k -s <credentials> <base URL>/api?action=history&name=<instance name>

The parameters are:

Requests API

This applies only if the instances manager is configured to handle instance requests.

List requests

curl -k -s <credentials> <base URL>/api?action=requests

CLI usage

The instances manager CLI is available on <base URL>/term if the web shell service is enabled on the server, otherwise a SSH client is required. The available actions are the same as the ones offered from the API services.

CLI actions

Usage:

sim

Get configuration

sim config

Get available versions

sim versions

Get all instances

sim list [<version|single keyword> or SQL:<sql where clause>]

Example of SQL where clause (i is the table alias for instances, v the table alias for versions and r the table alias for requests):

sim list "SQL:i.version in ('4.0', '3.2') and i.status = 'started' and i.version_date < v.date"

Get one single instance

sim get <name>

Add an instance

sim add <name> <version (or instance name to clone)>

Save an instance

sim save <name>

Note: during the save action the Tomcat process, if running, is suspended to ensure saved data consistency.

Reset an instance

sim reset <name> <version>

Delete an instance

sim delete|rm <name>

Clone an instance

sim clone|cp <name> <cloned name>

Rename an instance

sim rename|mv <name> <new name>

Start/stop an instance

sim start|stop <name>

Upgrade an instance

sim upgrade <name>

View last logs of an instance

sim logs <name>

Download an instance

sim download <name> <type: all|webapp|data|logs>

Get access logs report for an instance

sim accesslogs <name>

Control the Tomcat server of an instance (only applicable on a started instance)

sim tomcat-<status|stop|start|debug> <name>

Using debug is similar to start except that the Tomcat server is then started in JPDA debug mode. The JPDA port is available as the JPDA_ADDRESS environment variable.

Run ant task for an instance

sim ant-<task: purgelogs|purgejobs|purgesupervisions|purgerecyclebin|purgeexports|purgetempfiles|purgeall|buildindex|...> <name> [<param>]

Protect/unprotect an instance

sim protect <name>
sim|unprotect <name>

Activate/deactivate auto-update on an instance

sim autoupdate <name>
sim noautoupdate <name>

Activate/deactivate auto-save on an instance

sim autosave <name>
sim noautosave <name>

Set/reset custom URL of an instance

sim seturl <name> <custom URL>
sim reseturl <name>

Show process of an instance

sim ps <name>

Connect to instance's database

sim db <name> [<input file>]

The client tool used to connect to database depends on the database vendor (e.g. mysql client is used for MySQL/MariaDB, psql for PostgreSQL, ...)

Note: with embedded HSQLDB the instance must be stopped before connecting to database

Advanced CLI usage examples

This example gets status of all instances of a given version:

for NAME in `sim ls 4.0 | awk '{print $1}'`; do sim health $NAME | grep status; done

This example stops all instances with matching names:

sim ls myinstances\* | awk '{print $1}' | xargs -L 1 sim stop

This more advanced example upgrades all started instances of version 3.2or 4.0 that needs upgrade:

sim list "SQL:i.version in ('3.2', '4.0') and i.status = 'started' and i.version_date < v.date" | awk '{print $1}' | xargs -L 1 sim upgrade

Etc.

Hooks

It is possible to extend the manager behavior using the following script hooks (located in <manager home>/hooks):

pre-add.sh
post-add.sh
pre-reset.sh
post-reset.sh
pre-upgrade.sh
post-upgrade.sh
pre-save.sh
post-save.sh
pre-start.sh
post-start.sh
pre-stop.sh
post-stop.sh
pre-del.sh
post-del.sh

All hooks receive as argument their caller script's arguments (e.g. instance name, version and options for pre/post-add.sh).

Note: if your usage of the hooks is to add/alter elements to instances' Tomcat (configuration files, additional Java JARs or static web components, ...) you need to do it in the pre/post-add.sh but also in the pre/post-upgrade.sh (and maybe also in the pre/post-reset.sh) as upgrade (and reset) actions reinstall Tomcat.

Docker CLI actions

As of version 5.12, basic actions are also available to manage instances as Docker containers:

sim docker config
sim docker pull
sim docker list [--json]
sim docker add [--json] [<name|->] [<mysql|postgresql>]
sim docker del [--json] <name>
sim docker start [--json] <name>
sim docker stop [--json] <name>
sim docker save [--json] <name>
sim docker restart [--json] <name>
sim docker inspect <name>
sim docker logs <name> [<nb lines>]
sim docker shell <name>
sim docker database <name>

An optional API and UI gateway is also available to wrap the above CLI.

Note: at that stage the Docker instances relies on the various Simplicité Docker base server images and only supports Traefik as reverse proxy. The above hooks are not applicable.

Configuration

Global settings

The global settings are set as environment variables in the <manager home>/config.sh file (without the export keyword)

Core settings

Manager settings
System settings

Warning: these system settings SHOULD NOT be changed unless you know precisely what you are doing.

Reverse proxy settings
SSL settings

Backup settings

SCP destination
FTP destination
OpenStack object storage container destination
GoogleCloud object storage bucket destination

Mail settings

Databases settings

MySQL settings
PostgreSQL settings
Oracle settings

Note that other Oracle-related environment variable can be set here if not set otherwise, e.g:

ORACLE_HOME=/u01/app/oracle/product/11.2.0/xe
LD_LIBRARY_PATH=${ORACLE_HOME}/lib:${LD_LIBRARY_PATH}
SQLPATH=${ORACLE_HOME}/lib:${SQLPATH}
PATH=${ORACLE_HOME}/bin:${PATH}
NLS_LANG=AMERICAN_AMERICA.UTF8
ORACLE_SID=XE
SQLServer settings

Note that other SQLServer-related environment variable can be set here if not set otherwise:

MSSQL_HOME=/opt/mssql-tools
PATH=${MSSQL_HOME}/bin:${PATH}

Instance-specific settings

Instance-specific settings are set as environment variables in the <instance home>/.simplicite file (with the export keyword).

Warning: these variables are set upon creation of the instance and SHOULD NOT be changed manually unless you know precisely what you are doing.

Example:

export SERVICE_CONTEXT=
export SERVICE_URL=http://localhost:10078/io
export SERVICE_USER=designer
export SERVICE_PASSWORD=d98990faa918c84584ef
export SERVICE_DATABASE=oracle
export SERVICE_DATABASE_HOST=localhost
export SERVICE_DATABASE_PORT=1521
export SERVICE_ORACLE_SID=XE