Introduction
- The Controller is installed on Linux systems without use of an installer by extracting a .tar.gz archive.
- Technically the Controller can be operated for any Unix environment, however, the JS7 - Platforms include support for Controller operation with Linux.
- The Controller can be installed on Windows systems
- without use of an installer by extracting a .zip archive. This allows a portable installation that requires no administrative privileges.
- by running the Controller installer in headless mode.
Prerequisites
- A Java Runtime Environment starting from version 1.8 is required.
- For details see Which Java versions is JobScheduler available for?
Download
- Download the Controller archive for the target system from the JS7 - Download page.
- For Unix systems:
- A tarball archive is available that is extracted to create the Controller's directory structure (see below).
js7_controller_unix.<release>.tar.gz
- A tarball archive is available that is extracted to create the Controller's directory structure (see below).
- For Windows systems:
- A .zip archive is available that is extracted to create the Controller's directory structure (see below).
js7_controller_windows.<release>.zip
- A .zip archive including the installer is available that is used to run the installer in headless mode.
js7_controller_windows_installer.<release>.zip
- A .zip archive is available that is extracted to create the Controller's directory structure (see below).
- For Unix systems:
Installation from tarball/zip Archive
Installation
- Extract the downloaded archive to a directory.
- The resulting directory structure includes (only files and folders directly relevant):
controller
bin
controller.cmd|sh
- The Start Script for Windows/Unix platforms
controller_watchdog.cmd|sh
- Restarts the Controller for Windows/Unix platforms
environment_variables.cmd|sh
- Environment Startup Script for the JS7 Controller
lib
- The directory for Java libraries
service
(for operation as a Windows Service)amd64 (directory)
manager (directory)
x86 (directory)
install_controller_windows_service.cmd
js7_controller_<Controller ID>.exe
js7_controller_<Controller ID>w.exe
LICENSE.txt
NOTICE.txt
RELEASE-NOTES.txt
set_java_home_for_jetty_windows_service.cmd
uninstall_controller_windows_service.cmd
user_bin
Uninstaller
(Windows only, the empty directory remains in place after uninstall)install.log
js7.ico
shortcut.vbs
uninstall.cmd
uninstall_prepare.cmd
uninstaller.jar
var
logs
config
- state
- On Windows Systems:
- You have to modify the directory permissions for the above
.\logs
and.\service
directories if you extracted the Controller to e.g.C:\Program Files
.- This step is not required if you extract the Controller e.g. to
C:\ProgamData
. Start a command prompt with elevated administrative rights and execute e.g.
Allow full acces for "Users" on .\service and .\logs directoriescd "path\to\installation-directory" icacls "service" /L /grant *S-1-5-32-545:(OI)(CI)F icacls "logs" /L /grant *S-1-5-32-545:(OI)(CI)F
- This step is not required if you extract the Controller e.g. to
- You have to modify the directory permissions for the above
Update
Preparation
- Stop the JS7 Controller instance.
- Prepare to rollback in case that the update of the JS7 Controller is not successful:
- Take a backup of the Controller's installation directory and configuration directory, e.g. by creating a .tar.gz/.zip archive.
- Installation Directory:
- The default installation directory for the Controller is:
/opt/sos-berlin.com/js7/controller/<controller-id>
for Unix systems,C:\Program Files\sos-berlin.com\js7\controller\<controller-ID>
for Windows systems.
- The default installation directory for the Controller is:
- Configuration Directory
- The default configuration directory for the Controller is:
/home/sos/sos-berlin.com/js7/controller/<controller-id>
for Unix systems,C:\ProgramData\sos-berlin.com\js7\controller\<controller-id>
for Windows systems.
- The default configuration directory for the Controller is:
- Installation Directory:
- Take a backup of the Controller's installation directory and configuration directory, e.g. by creating a .tar.gz/.zip archive.
Running the Update
The update of the JS7 Controller is performed from the same download archive as used for any fresh installation.
- When extracting files to the same location then existing files with the same name will be overwritten. Files added by the user remain in place.
- This is particularly true for the Controller Start Script
./bin/controller.sh|cmd
that should not be modified by users.
- This is particularly true for the Controller Start Script
- The tarball/zip archive includes Java libraries in the
./lib
directory that ship with unique file names per Controller release.- Therefore, before extracting files, rename or remove an existing
./lib
directory in order to store libraries from the current Controller release only to this directory.
- Therefore, before extracting files, rename or remove an existing
Installation from Windows Installer in Headless Mode
The installer is available for Windows systems only.
- To run the Windows installer in graphical mode see JS7 - Controller - Use of Windows Graphical Installer.
- To run the Windows installer in headless mode consider the below information.
Installation
Installer Response File
- The Controller installation makes use the
controller_install.xml
response file that includes parameters such as the installation path, ports, etc.- For a fresh installation the installer response file is included with the downloaded archive.
- The default location of the
controller
_install.xml
file from a previous installation is:C:\Program Files\sos-berlin.com\js7\controller\<controller-id>
The
controller
_install.xml
file is explained with the code listing below. The comments included are intended to be self-explanatory.
Running the Installer
Running the installer of JS7 Controller on Windows systems:
Running the installer of JS7 Controller on Windows systemsC:\temp\controller.[release]> setup.cmd controller_install.xml
Installation Log
The installer creates a log file in the directory that is pointed to by the environment variable JS7_CONTROLLER_LOGS
or in the logs
sub-directory of the Controller configuration directory.
- The default location of the
logs
directory for the Controller isC:\ProgramData\sos-berlin.com\js7\controller\<controller-id>
- Installation log files are named according to the pattern
Install_V<release>_<date-time>_....log
where<
release>
is the release number and<
date-time>
refers to the point in time of installation.
- For further references about logging see JS7 - Logging
Update
Preparation
- Stop the JS7 Controller instance.
- Prepare to rollback in case that the update of the JS7 Controller is not successful.
- Take a backup of the Controller's installation directory and configuration directory, e.g. by creating a .zip archive.
- Installation Directory:
- The default installation directory for the Controller is
C:\Program Files\sos-berlin.com\js7\controller\<controller-id>
- The default installation directory for the Controller is
- Configuration Directory
- The default configuration directory for the Controller is
C:\ProgramData\sos-berlin.com\js7\controller\<controller-id>
- The default configuration directory for the Controller is
- Installation Directory:
- Take a backup of the Controller's installation directory and configuration directory, e.g. by creating a .zip archive.
Running the Update
The update procedure makes use of the same installer response file as explained for a fresh installation.
Steps to run the installer are the same as explained for a fresh installation.
Rollback
Rollback from tarball/zip Archive Installation
- To rollback the installation of a JS7 Controller instance remove the newly created installation directory and configuration directory of the JS7 Controller.
- Restore the directories from a previous backup, e.g. by extracting the respective .tar.gz/.zip backup archives to the installation directory and configuration directory.
Rollback from Installation with Headless Installer for Windows
- To perform the rollback of the JS7 Controller instance run the uninstaller from the command line.
- The default location of the
uninstall.cmd
file is:C:\Program Files\sos-berlin.com\js7\controller\<controller-id>\Uninstaller
- The default location of the
- Restore from a previous backup, e.g. by extracting the .tar.gz/.zip archive to the installation directory and configuration directory.
- Re-install the Windows Service from the command line:
- Switch to the
.\bin
directory for the Controller from the command line- The default location of the
.\bin
directory is:C:\Program Files\sos-berlin.com\js7\controller\<controller-id>\bin
- The default location of the
Run the below command that will install the Controller's Windows Service.
controller.cmd
install
-service [--http-port=<number>] [--ip-address=<
hostname
or ip address>]
- Switch to the
Automated Start-up and Shutdown
For Unix systems, the start-up and shutdown configurations apply that are executed by root
, e.g. in /etc/init.d
or corresponding locations and by use of systemd
.
- Consider use of the
JS7_CONTROLLER_USER
environment variable to run a Controller that is started byroot
for a different user account. - For use with
systemd
find a sample service file from./bin/controller.service-example
file.
For Windows systems operation of the Controller by a Windows Service is recommended as such services can be configured to start/stop automatically on server start-up and shutdown.