Page History
Table of Contents |
---|
Installing the JS7 Controller
Prerequisites
Introduction
- First of all, you don't need to read this article in all its parts. For most situations it is sufficient to check the prerequisites, download the software and run the installer that will guide you.
- In this article you find the details about available installer options, updates and rollback for interested parties.
- The Controller can be installed by use of the graphical installer, for headless installation see JS7 - Controller - Headless Installation on Linux and Windows.
Prerequisites
- A Java Runtime Environment 1.8 or newer is required. For details see Which Java versions is JobScheduler available for?
- It is necessary that a time service is operated on the server which hosts the Controller. This is to synchronize the system clock's time.
Download
- Technically the Controller can be operated in any Unix environment. Note, however, that the JS7 - Platforms article describes support for Controller operation in more detail.
Download
- Select Choose the Controller archive for Windows systems and the graphical installer from the JS7 - Download page.
- For On Windows systems a .zip archive including the installer is available from
js7_controller_windows_installer.<release><release>.zip
.
Installation Video
This video explains how to install the JS7 Controller:
Widget Connector | ||
---|---|---|
|
Installing the JS7 Controller
Installation
Extract the downloaded archive to a directory, e.g. C:\Temp
.
...
controller_install.xml
(installer response file)install_controller.txt
(installation notes)js7_controller_windows.<release><release>.jar
(installer library for a given release)license.gpl
(copy of GPLv3 (General Public License) )license.txt, license.html
(copy of JS7 JobScheduler Commercial License Agreement)setup.cmd
(installer script)
...
The installer can be run in graphical mode or in headless mode, see JS7 - Controller - Use of Linux/Windows Headless InstallationHeadless Installation on Linux and Windows.
- The installer asks for elevated administrative privileges, therefore it is not required to change the permissions in the
.\service
directory and the installer sets read/write permissions for the.\logs
directory. - After the installation you will find
- a Windows Service "
SOS JS7 Controller -id=<controller-id>
" - an executable file
.\service\
js7_controller_<controller-id>.exe
that is started by the Windows Service.
- a Windows Service "
...
Run Installer
Run the installer for the JS7 Controller using the following script:
Code Block language bash title Windows command to run the graphical installer > C:\Temp\controller.<release>\setup.cmd
- The installer asks for administrative privileges.
- Select the language to be used for the setup: English, Japanese and German are available.
Welcome Window
- Click Next on the welcome window.
License Options
- The License window displays licenses available for the JS7 Controller.
- The Open Source License GPLv3 (General Public License) is available.
- The SOS Commercial License can be used by adding a license certificate file that you receive from SOS after purchase of a license. For details see JS7 - FAQ - How to apply a JS7 License Key.
License Agreement
- The License Agreement corresponding to the license option selected has to be accepted before installation can occur.
Installation Directory
- The installer opens a window to specify the installation directory after you accept the terms of the License Agreement.
Configuration Directory
- Choose the configuration directory for the Controller to which you want to store the Controller's configuration and journal files.
Installation Settings
- With In the next window specify the Controller ID that , which is a unique identifier for a Controller, is specified. You can use identifiers such as "controller-test", "controller-production" etc. Upper case and lower case characters are consideredCharacter case is significant, the characters a-z, A-Z, 0-9, underscore and hyphen are allowed. Spaces are not allowed in a Controller ID.
- If you intend to operate a Controller cluster with two Controller instances for the active and for the standby cluster membermembers, then specify the same identifier during installation of each Controller instance as otherwise the instances will not be considered members of the same cluster. This identifier cannot be modified after installation, changes to the Controller ID require reinstallation of the Controller.
- A checkbox allows to specify if the currently installed Controller instance will initially start the initial role of the current Controller instance to be specified - i.e. whether it starts with an active or a standby role. Do not select this checkbox if you operate are operating a standalone Controller instance.
- Consider Note that operation of a Controller cluster requires to add a license certificate from a previous above step, see JS7 - Licensingto have been specified in the License Agreement step described above. See also JS7 - License.
- Add the HTTP port that is to be used by the JS7 Controller. Make sure that the HTTP port is available and is not otherwise used. If you run other applications that use this port then choose a different port.
- If you specify a Windows Service account then make sure that this account has "Log on as service permissions". Consider that credentials that you enter to this window are stored in clear text with the installer response file. It is considered more secure not to add credentials with this step, but to add credentials directly with after installation using the Windows Service panel after installation.
Configuration Directory
- Choose the configuration directory for the Controller to which you want to store the Controller's configuration files and journal files.
Specific Directories
- If you choose the installation directory to be located in
C:\Program Files
then it is recommended to choose configure the log directory to be outside of the installation path, e.g.C:\ProgramData\sos-berlin.com\js7\controller\logs
. - The installer sets read/write permissions for the specified Windows Service account. Typically only the administrator group should have write permissions for
C:\Program Files
.
Installation Progress
- This step displays progress of the first part of the installation procedure.
- Changes to installer options can no longer be applied once this step is has been started.
Configuration Progress
- The processing panel displays progress of the second part of the installation procedure that includes to set setting permissions and to install installation of the Windows Service.
The information displayed with this step is written to the installation log file that can be found in the
JS7_CONTROLLER_DATA/logs
folder.
Completion
The last step of the installation displays a summary of the installation (success/error) and paths to relevant files.
...
Note that if a problem occurs during installation a warning will be displayed and a link to the installation log file will be provided.
- A failed installation can be repeated at any time, no uninstallation is not required.
Directory Structure
- The resulting directory structure after installation includes (only files and folders immediately relevant):
C:\Program Files\sos-berlin.com\js7\controller
(installation directory).js7controllerinstallinformation
(binary installer information).version
(release information)controller_install.xml
(installer response file used from previous installation)license.gpl
(copy of GPLv3 (General Public License) used for the Open Source JS7 - License)license.html
, (HTML format of license terms for the commercial JS7 - License)license.txt
(copy of JS7 JobScheduler Commercial License Agreementplain text format of license terms for the commercial JS7 - License)sbom.json
(JS7 - Software Bill of Materials)ThirdParty.txt
(list of 3rd party components and licenses included with the used by JS7 Controller)var
(junction to data directory)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
anonymize-logs.cmd
(used to anonymize log files, see JS7 - Log Anonymization)controller.cmd
(Start Script)controller_instance.cmd-example
(Sample Instance Start Script to set individual environment variables. Drop the-example
extension to activate this file.)controller_watchdog.cmd
(restarts the Controller if not operated as a Windows Service, called by Start Script)
lib
(directory for Java libraries)log4j2.xml
(used for based console logging to stdout, see JS7 - Logging)patches
(used for JS7 - Patches for Controller, the directory is cleaned up when running the installer)user_lib (
used for licensed binary code, see JS7 - How to apply a JS7 License Key)- (additional directories
lib
(directory- for Java libraries)
service
(directory for operation as a Windows Service)amd64
manager
install_controller_windows_service.cmdcmd
(used by installer)js7_controller_<controller-id>.exe
js7_controller_<controller-id>w.exe
LICENSE.txt.txt
(copy of Apache License, Version 2.0)NOTICE.txttxt
(Apache Commons Daemon license notice)RELEASE-NOTES.txttxt
(Apache Commons Daemon release notes)uninstall_controller_windows_service.cmd
x86
user_bin
cmd
(used by uninstaller)amd64
manager
x86
environment_variables.cmd|sh-example
Sample configuration file to set individual environment variables. Drop the-example
extension to activate this file.
Uninstaller
(Uninstaller directory for Windows only, the empty directory remains in place after uninstall)install.log
(lists installed files)js7.ico
(uninstaller icon)shortcut.vbs
(creates shortcuts for the Windows start menu)uninstall.cmd
(used by uninstaller)uninstall_prepare.cmdcmd
(used by uninstaller)uninstaller.jarjar
(used by uninstaller)
C:\ProgramData\sos-berlin.com\js7\controller
(configuration data directory)
var
(datacontroller_home
(junction to installation directory)config
(directory for configuration files)controller.conf
(general Controller configuration, see JS7 - Controller Configuration Items)lib
(optional directory for licensed binary code)license
(optional directory for license certificate files)private
(directory for security related configuration files)private.conf-example
(security related configuration, see JS7 - Controller Configuration Items)- For setting up HTTPS connections see up JS7 - Controller Configuration ItemsHTTPS Connections
- For setting up authentication and digital signature checks
trusted-pgp-keys
(empty directory, can be used to add individual PGP public keys for signing, see JS7 - Secure Deployment of Scheduling Objects)trusted-x509-keys
(directory to hold X.509 certificates for signing, see JS7 - Secure Deployment of Scheduling Objects)sos.intermediate-ca.pem
(default certificate of SOS to allow deployment with JOC Cockpit)
logs
(directory for log files)state
(directory for journal files)work
(directory for work files)
Rollback
To perform a rollback on Windows systems follow the below steps:
- Run the JS7 Controller uninstaller.
- 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
Updating the JS7 Controller
The update of the JS7 Controller is performed from the same download archive as used for any a fresh installation:
js7_controller_windows_installer.<release>.zip
Preparation
- Stop the JS7 Controller instance, e.g. from using the Controller's Windows Service.
- 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 directorydirectories, 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 directorydirectories, e.g. by creating a .zip archive.
Update
The An update using the graphical installer can be done by rerunning running the installer setup.cmd
file from the .zip archive and by providing the same parameters such as installation directory, port etc.
Rollback
To perform a rollback on Windows systems follow the below steps:
- Run the JS7 Controller uninstaller.
- 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 the Controller folders from the backup by unzipping the .zip archive for the installation directory and configuration directory directories to the their respective locations.
- Re-install the Windows Service from the command line:
- Switch to the Controller's
.\bin
directory 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 following command that installs the Controller's Windows Service:
controller.cmd
install
-service
- Switch to the Controller's
Installation Log
The installer creates a log file in the directory that is pointed to indicated by the environment variable JS7_CONTROLLER_LOGS
or in the logs
sub-directory of the Controller's configuration directory.
- The default location of the
logs
directory for the Controller is:C:\ProgramData\sos-berlin.com\js7\controller/<controller<controller-id> id>
on Windows.
- Installation log files use names 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 information about logging see JS7 - Logging .
Automated Startup and Shutdown
For Unix systems startup and shutdown configurations apply that are executed by the root
account e.g. from /etc/init.d
scripts and by use of systemd
.
- Consider use of the
JS7_CONTROLLER_USER
environment variable from the./bin/controller_instance.sh
script 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
. - For details see JS7 - systemd Service Files for automated Startup and Shutdown with Unix Systems
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 startup and shutdown.
- Consider to assign a service account to the JS7 Controller service with the Windows Service Panel.
- Consider to allow the JS7 Controller service to be automatically started on server startup.
Initial Operation
Info |
---|
|
Further References
- Installation Use of Linux/Windows Headless Installation
- Operation
- Configuration