Requirements

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.

Installation

• . 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.
• 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 the Controller archive for Windows systems and the graphical installer from the JS7 - Download page.
• On Windows systems a .zip archive including the installer is available from Extract the downloaded archive js7_controller_windows_installer.x.x.x.zip to an arbitrary <release>.zip.

Installation Video

This video explains how to install the JS7 Controller:

Installing the JS7 Controller

Installation

Extract the downloaded archive to a directory, e.g. C:\Temp.

After extraction of the installer .zip archive the directory structure includes:

• controller_install.xml (installer response file)
• install_controller.txt (installation notes)
• js7_controller_windows.<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)

Consider the following implications before running the installer:

• The installer can be run with or without a GUIin graphical mode or in headless mode, see JS7 - Controller - Headless Installation on Linux and Windows.

• The installer asks for elevated administrator administrative privileges, therefore it is not necessary required to change the permissions in the .\service directory and the installer sets read/write permissions for the log .\logs directory.
• After the installation you will find ...
  
  • a Windows service Service "SOS JS7 Controller -id=<Controller ID><controller-id>"
  • an executable file .\service\js7_controller_<Controller ID><controller-id>.exe that is started by the Windows service

...

• • Service.

Run Installer

• Run the installer dialog for the JS7 Controller using the following script:

  Code Block
  language bash title Windows command to open run the graphical installer GUI
  > C:\Temp\controller.x.x.x<release>\setup.cmd

• The installer asks for elevated administrator permissionsadministrative privileges.  
• Select the language to be used for the setup: English, Japanese and German are available.
  Image Removed
  Image Added

Welcome Window

• Click Next on the Welcome to the Installation screen
  Image Removed
  welcome window.
  
  Image Added

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 - How to apply a JS7 License Key.
    
    Image Added

License Agreement

• The License Agreement corresponding to the license option selected has to The License Agreement shown in Step 2 of the installation must be accepted before installation can occur.
  
  Image Modified

Installation Directory

• The installer opens a GUI window to specify the installation path directory after you accepted accept the terms of the license agreementLicense Agreement.
  
  Image Modified

Configuration Directory

• Choose the configuration directory for the Controller to which you want to store the Controller's configuration and journal files.
  
  Image Added

Installation Settings

• In the next window the Controller ID, which is a unique identifier for a Controller, is specified. You can use identifiers such as "controller-test", "controller-production" etc. Character 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 standby cluster members, 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 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 are operating a standalone Controller instance.
  • Note that operation of a Controller cluster requires a license certificate to have been specified in the License Agreement step described above. See also JS7 - License.
• Add the HTTP port which can that is to be used by the JS7 Controller. Make sure that the HTTP port is available , i.e. and is not otherwise used. If you run other applications that use this port then choose a different port.
• If you specify a service Windows Service account then make sure that this account has "Log on as service rights".
  Image Removed
  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 after installation using the Windows Service panel.
  
  Image Added

Specific Directories

• If you choose the installation directory If you selected the installation path 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 user but normally exclusively Service account. Typically only the administrator group should have write permissions for C:\Program Files.
  
  Image Modified

Installation Progress

• This step shows the displays progress of the first part of the installation procedure.
• Changes to the installation configuration installer options can no longer be made applied once this step has been started.
  
  Image Modified

Configuration Progress

• The processing panel displays The Perform External Process shows the progress of the second part of the installation procedure that includes setting permissions and installation of the Windows Service.
  
  Image Modified
  
  

  • The information shown in displayed with this step will be is written to the installation log file , which that can be found in the JS7_CONTROLLER_DATA/logs folder.

Completion

• The last step of the installation shows displays a summary of the installation (success/error) and paths to relevant informationfiles.
  
  Image Modified

• Note that if a problem occurs during installation a warning

  message

  will be

  shown here

  displayed and a link to the installation log file will be provided.

Installation without GUI

• A failed installation can be repeated at any time, uninstallation is not required.

Directory Structure

• The resulting directory structure after installation includes (only files and folders immediately relevant):

• Run the installer for JS7 Controller parametrized with the controller_install.xml the file that is included with the extracted archive.

• This parameter file is preconfigured, i.e. you can run it without any changes.

  Code Block
  language bash title Windows command to open the installer GUI
  > cd C:\Temp\controller.x.x.x > setup.cmd controller_install.xml

• If you run the installer without modifications in controller_install.xml then
  
  • the installation path is C:\Program Files\sos-berlin.com\js7\controller
    
  • the http port is 4444
  • the log folder is C:\ProgramData\sos-berlin.com\js7\controller
  If you want to modify the default options then edit the
  • (installation directory)
    • .js7controllerinstallinformation (binary installer information)
    • .version (release information)
    • controller_install.xml
  file before you start the installer.
  • • (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 (plain 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 used by JS7) 
    • var (junction to data directory)
    • bin
      • 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 for Java libraries)
    • service (directory for operation as a Windows Service)
      • install_controller_windows_service.cmd (used by installer)
      • js7_controller_<controller-id>.exe
      • js7_controller_<controller-id>w.exe
      • LICENSE.txt (copy of Apache License, Version 2.0)
      • NOTICE.txt (Apache Commons Daemon license notice)
      • RELEASE-NOTES.txt (Apache Commons Daemon release notes)
      • uninstall_controller_windows_service.cmd (used by uninstaller)
      • amd64
      • manager
      • x86
    • 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.cmd (used by uninstaller)
      • uninstaller.jar (used by uninstaller)
  • C:\ProgramData\sos-berlin.com\js7\controller (data directory)
    
    • controller_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 JS7 - Controller HTTPS 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

  Updating the JS7 Controller

  The update of the JS7 Controller is performed from the same download archive as used for a fresh installation:

  • js7_controller_windows_installer.<release>.zip

  Preparation

  • Stop the JS7 Controller instance, e.g. using the Controller's Windows Service.
  • Prepare to rollback in case the update of the JS7 Controller is not successful:
    • Take a backup of the Controller's installation and configuration directories, e.g. by creating a .zip archive.
      
      • Installation Directory
        • The default installation directory for the Controller is C:\Program
      The default controller_install.xml the file is shown in the code listing below. The extensive comments are intended to be self-explanatory.  Code Block

      language	xml
      title	Content of controller_install.xml
      linenumbers	true

      <?xml version="1.0" encoding="UTF-8" standalone="no"?> <!-- XML configuration file for JS7 Controller setup The JS7 Controller is available with a dual licensing model. - GNU GPL 2.0 License (see http://www.gnu.org/licenses/gpl-2.0.html) - JS7 Commercial License (see licence.txt) The setup asks you for the desired license model (see <entry key="licenceOptions" .../> below). If you call the setup with this XML file then you accept at the same time the terms of the chosen license agreement. --> <AutomatedInstallation langpack="eng"> <com.izforge.izpack.panels.UserInputPanel id="home"> <userInput/> </com.izforge.izpack.panels.UserInputPanel> <!--com.izforge.izpack.panels.UserInputPanel id="licences"> <userInput--> <!-- Select the license model (GPL or Commercial) --> <!--entry key="licenceOptions" value="GPL"/--> <!-- If you selected GPL as license model than the licence must be empty. Otherwise please enter a license key if available. It is also possible to modify the license key later. --> <!--entry key="licence" value=""/> </userInput> </com.izforge.izpack.panels.UserInputPanel--> <com.izforge.izpack.panels.HTMLLicencePanel id="gpl_licence"/> <com.izforge.izpack.panels.HTMLLicencePanel id="commercial_licence"/> <com.izforge.izpack.panels.TargetPanel id="target"> <!-- SELECT THE INSTALLATION PATH The installation expands this path with the JS7 ID as subdirectory. It must be absolute! For example C:\Program
      • • Files\sos-berlin.com\js7\controller
      • • \<controller-
      -> <installpath>C:\Program Files
      • • id>
      • Configuration Directory
        • The default configuration directory for the Controller is C:\ProgramData\sos-berlin.com\js7
      \controller</installpath> </com.izforge.izpack.panels.TargetPanel> <com.izforge.izpack.panels.UserPathPanel id="userpath"> <!-- SELECT THE DIRECTORY FOR CONFIGURATION AND LOG FILES The installation expands this path with the JS7 ID as subdirectory. The path must be absolute! Default path is C:\ProgramData
      • • \controller\<controller-id>

  Update

  An update using the graphical installer can be done by 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
      --> <UserPathPanelElement>C:\ProgramData
      • \<controller-id>\Uninstaller
  • Restore the Controller folders from the backup by unzipping the .zip archive for the installation and configuration directories to 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

    • Run the following command that installs the Controller's Windows Service:

      controller.cmd install-service

  Installation Log

  The installer creates a log file in the directory that is 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-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 by root 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
  Having completed the installation or update of a JS7 Controller you can start the Controller either manually or from its Unix daemon/Windows Service, see JS7 - Controller Command Line Operation. Consider the following information about initial operation: JS7 - Initial Operation for Standalone Controller JS7 - Initial Operation for Controller Cluster

  Further References

  • Installation
    • JS7 - Controller - Headless Installation on Linux and Windows
  • Operation
    • JS7 - Controller - Command Line Operation
    • JS7 - Initial Operation for Standalone Controller
    • JS7 - Initial Operation for Controller Cluster
  • Configuration
    • JS7 - Controller Configuration Items
    • JS7 - Controller HTTPS Connectionscontroller</UserPathPanelElement> </com.izforge.izpack.panels.UserPathPanel> <com.izforge.izpack.panels.UserInputPanel id="network"> <userInput> <!-- ID of the JS7 Controller --> <entry key="controllerId" value="controller"/> <!-- Choose yes if the JS7 Controller is a Standby-Controller in a cluster --> <entry key="isStandby" value="no"/> <!-- Choose (yes or no) wether the JS7 Controller should be started at the end of the installation --> <entry key="launchController" value="yes"/> <!-- HTTP port of the JS7 Controller --> <entry key="controllerPort" value="4444"/> <!-- Set optionally an ip address or hostname. It could be used for indicating which network interfaces the JS7 Controller should listen to when using HTTP. If it is empty then it listens to all available network interfaces. --> <entry key="controllerHost" value=""/> <!-- The JS7 Controller will be installed as Windows service. You can set the service account otherwise the local system account will be used. The account has to be the form 'Domain\User'. --> <entry key="serviceAccount" value=""/> <entry key="servicePassword" value=""/> </userInput> </com.izforge.izpack.panels.UserInputPanel> <com.izforge.izpack.panels.UserInputPanel id="environment"> <userInput> <!-- Directory where the JS7 Controller's log files are stored (default: '[above user path]\logs'). --> <entry key="logPath" value=""/> <!-- Directory where the JS7 Controller's pid file is stored (default: above log path). --> <entry key="pidFilePath" value=""/> <!-- Working directory for all jobs which started by the JS7 Controller e.g. %USERPROFILE% (default: [installation path]) --> <entry key="workPath" value=""/> <!-- The JS7 Controller requires a Java JRE at least version '1.8'. You can choose a different Java environment than the Java which is used during this installation. --> <entry key="javaHome" value=""/> <!-- Set optionally Java options (default: -Xmx500m). --> <entry key="javaOptions" value=""/> </userInput> </com.izforge.izpack.panels.UserInputPanel> <com.izforge.izpack.panels.UserInputPanel id="end"> <userInput/> </com.izforge.izpack.panels.UserInputPanel> <com.izforge.izpack.panels.InstallPanel id="install"/> <com.izforge.izpack.panels.ProcessPanel id="process"/> <com.izforge.izpack.panels.FinishPanel id="finish"/> </AutomatedInstallation>