JobServer 3.4.26

Product Configuration and Installation Notes


Table of Contents


Release Notes

JobServer Standard vs Professional:
-----------------------------------

  Note that JobServer Standard edition can only be installed on one host machine.
  It comes bundled with a built-in webserver, HSQL database and scheduling engine.
  Everything runs on one host machine making it very easy to get started.

  JobServer Professional by contrast can be installed and run on multiple machines
  and thus offers greater scalability by allowing for multiple tiers and support for
  highend databases. JobServer Pro can have one or more webservers configured and a
  primary and secondary JobServer scheduling engine as well for failover purposes.
  JobServer Pro supports failover and clustering allowing you to run jobs across
  many host computers. Clustering is supported through the use of Agent servers that
  can remotely run jobs. Also, JobServer Pro is be configured to work with remotely
  configured databases including Oracle, MYSQL, PostgreSQL and HSQL.


Upgrade Procedures:
-------------------

  You may use a new JobServer distribution (zip file) to upgrade an existing older
  JobServer environment you already have installed.

   Steps to perform an upgrade:

     1) Shutdown the existing JobServer environment you wish to upgrade.

     2) Unzip the JobServer distribution, example:
             > unzip jobserver-std-3.2.0.zip

     3) Find the "upgrade.bat" command in the newly unzipped jobserver directory.

     4) Run the "upgrade.bat" command found in the newly unzipped jobserver directory.

     5) Follow the step by step directions during the upgrade to complete the
        upgrade of the existing JobServer installation. You will be asked for
        the full directory path of the JobServer directory of the existing JobServer
        enviornment that you wish to upgrade.

     6) Manually apply all required database migration scripts between current release
        and release you are upgrading to. Database patches, if they exist, will be in
        the servicepack/rel-3-x-x directory for your database version.

     7) Restart upgraded JobServer environment when you are ready.

    Once the "upgrade.bat" command has completed your targeted JobServer environment
    will be upgrade to the same version as that of the new JobServer distribution.

   
Installation Steps:
-------------------

1 - JobServer requires Java JDK 1.6 or higher version to be installed on your host
    computer. Insure that this is properly installed before starting installation. 
    Make sure the JAVA_HOME environment variable is properly set. JobServer can be 
    installed on Windows XP, 200X, and Vista.
    
    Go to step 2 if you have already unpacked the software archive, otherwise,
    unzip the archive now. After unzipping the archive file, the JobServer 
    environment can be found within the newly unzipped "jobserver" directory.
    Place the "jobserver" directory in a permanent home directory.

2 - Run the install program in the newly created "jobserver" directory:

        > install.bat

    This will configure the software for use. It will also ask you to accept or
    reject the product license terms.

    
3 - Now that the software is installed it is time to configure the database. If
    you are using JobServer Standard version this step is not needed as the database
    is built-in. If this is the case, proceed to step 4 now. If you are using 
    JobServer Professional, you will need access to a database server
    instance. Follow the steps in the README file in the "database" directory 
    that corresponds to the database you will be using. Once you have completed
    the database setup, proceed to step 4 below. You can find the database
    README files here:
    
               ORACLE README
               MYSQL README
               PostgreSQL README
               HSQL README

               
4 - Edit the various JobServer system properties found in the 
    "system-config.bat" file in the "conf" directory. Often many of the 
    default settings will be adequate to get you started unless there is a conflict 
    (for example the http port number is already in use by another application). 
    This configuration file has several properties that can be set. The file 
    itself describes the various properties. Typically, you might need to set 
    the following properties:

           a) Web Server port number for http
           b) Web Server port number for shutdown
           c) JobServer Engine port number
           d) Select the database type you are using (ORACLE, MYSQL, ....)
           c) Set the various database properties according to your database
              configuration.
    
    Read through the "system-config.bat" for details on some of the other
    advanced properties that can be set.


5 - Test the environment setup by running this utility program:

        > jobserver\bin\jsmonitor.bat

    This should return status information informing you of the setup. Initially, the
    WebServer and JobServer Container will be "Shutdown". Now you are ready to 
    startup JobServer:

        > jobserver\bin\jsstartup.bat

    If you want to run the JobServer process in the background (without any corresponding
    MSDOS Windows) use the command:
    
        > jobserver\bin\jsstartup-windowless.bat
    
    Give JobServer a minute to startup and then run the environment status 
    check utility program again:
    
        > jobserver\bin\jsmonitor.bat
     
    You should now see the JobServer Container as "Idle" and the WebServer and
    Database as "Active". If you don't see this, double check your environment
    settings. Correct any problems and check the status again.

    If you encounter problems or errors you can check the logs for JobServer
    Container in:

       jobserver\EJS-DATA\startup-log\\startup-log.txt

    If you encounter errors with the webserver check the log files in:

      jobserver\sys\app\logs\\jobserver_log....
    

6 - After giving JobServer a moment to startup, access JobServer using your
    browser (Firefox 2.x, Chrome, or IE 6 or higher), using the url:

       http://<yourhost>:<port>/jobserver

    Where "yourhost" is the name of the machine that JobServer is installed on
    and "port" is the web server port number as defined in the 
    "system-config.bat" file. By default you should be able to use the following
    on most environments:

       http://<localhost>:<8020>/jobserver

    By default there is an application user called "admin" with a default password
    of "foofoo", that you will use to log into the JobServer Workbench. This user
    is the main administrative user of the JobServer applications and exists by
    default. It is recommended you change the password immediately. Use this user
    to create new users and grant rights to JobServer applications. The "admin"
    user is granted all available rights. When creating new users, you may grant
    them limited rights to applications, groups, and partitions as necessary.

    
7 - By default the product typically comes with a demo license key. If you 
    received a separate license key you may apply it by placing it in the
    "jobserver\conf" directory under the name "license.key" or you may also
    apply the new license key using the GUI (Product Config application). Note,
    that if you apply a new license key you will need to shutdown and then     
    restart the JobServer environment using the "jsshutdown.bat" and 
    "jsstartup.bat" commands for the new license to take effect.

    If you are running JobServer on multiple machines and have multiple license
    keys (one per host computer), you must set the license.key file in your
    %HOME%\.jobserver directory for each machine you have a license key for.


8 - JobServer can also be run as a Windows service. To do this, first edit the
    file "jobserver\bin\jsservice.xml". You may also set (and uncomment) the
    JOBSERVER_HOSTNAME property if you require customizing the hostname
    that JobServer is using (usually not necessary). Make sure environment
    the environment property variable "JAVA_HOME" is set at the System level.

    Then run the following command to install JobServer as a windows service:

     > jsservice.exe install  # this will install JobServer as a Windows service

    Now you can start JobServer as a windows service by running the command:

     > jsservice.exe start  # this starts the jobserver environment as a Windows service

    To stop JobServer and the windows service, just use the jsshutdown.bat command
    as discussed earlier or stop JobServer from the Windows service utility. Or
    you may also stop the service using the command:

     > jsservice.exe stop

    To restart the JobServer windows service use the command:

     > jsservice.exe restart

    If you want to uninstall JobServer from the windows service, run the
    following command:

     > jsservice.exe uninstall #make sure the service is not running before uninstall

    Windows service logging (error and standard out) files will be created in the
    "jobserver\bin" directory. You can customize the log file directory that the
    windows service will output to by uncommenting and configuring the ""
    tag in the jsservice.xml file.

    Note, if you are using Microsoft Remote Desktop (RDP), you will need
    to pass the "-Xrs" JVM arguement to all JobServer JVMs to disable shutdown
    hooks from being called on "console" logout to avoid problems with JobServer
    running as a windows service. To do this you can simply pass this JVM argument
    from the "conf\system-config.bat" properties file. Contact support for
    questions if you are using RDP.

9 - To install JobServer Pro on multiple machines. Install the JobServer software
    on a central file server then have the remote webservers, primary/secondary
    job scheduling host machines, and Agent machines mount the central file
    server and jobserver home directory.

    For high availability configurations, in these multi-host environments, it
    is recommended you install the JobServer software on a highly available central
    filesystem such as a NetApp or SAN.

    You will need to set the property "agentPort" in the system-config.bat
    file to enable the Agent feature. This will set the port number used by the
    Agent servers on each host machine they are installed and run on.

10- Optional environment variables you can set:

        JOBSERVER_HOME : Normally your jobserver environment will try to derive
                         the location of your jobserver home directory. You can
                         manually define the home directory by setting this
                         environment variable.

        JOBSERVER_HOSTNAME: By default jobserver uses the default hostname retrieved
                            from the "hostname" command. You can override this by
                            setting this environment variable manually for each host.

   
JobServer directory structure is as follows:
--------------------------------------------

 All files are contained under the "jobserver" directory. 

  - jobserver\EJS-DATA
      Directory contains files and subdirectories that contain server log files
      and job sandbox directories. This directory will grow as more and more
      jobs are run. Make sure that adequate disk space is allocated for growth.

  - jobserver\bin
      Executable programs, including jsstartup.bat, jsshutdown.bat, and jsmonitor.bat.

        jsstartup.bat  - starts up JobServer
        jsshutdown.bat - shuts down  JobServer
        jsmonitor.bat  - utility tool for monitoring and administrating JobServer
                         environment.

  - jobserver\common-lib
      Contains jar files that are common to Tasklets, Weblets and Services

        gwt - Directory for common jars used by all Weblets during GWT compiling.
                
        services - Directory for common jars used by all server-side code executed
                   in the webserver and used by all Weblets. This is where you can place
                   common jars that you want to be shared by all Weblets when they
                   run. This is also the directory to place the implementation for
                   org.soafaces.bundle.container.ContainerStartupListener
                   to enable custom startup logic when the webserver is started. The
                   class name can be specified with the WebContainerStartupListenerImpl
                   configuration property in the product-config.propreties file.

        workflow - Directory for common jars used by all jobs and Tasklets. This is
                   where you can place common jars that you want to be shared by all
                   jobs/tasklets when they run. This also is the directory to place the
                   implementation for org.soafaces.bundle.container.ContainerStartupListener
                   to enable custom startup logic when JobServer is started. The class name
                   can be specified with the ContainerStartupListenerImpl config property
                   in the product-config.propreties file.

  - jobserver\conf
      Configuration files used in configuring JobServer environment. The files
      of interest to the administrator are:

        license.key : License key provided to customer. Demo license may be provided
                      by default.

        product-config.properties : Advanced configuration options available to your
                                    JobServer product. 

        system-config.bat : Main configuration file for JobServer to set ports and other
                            critical configuration details.

  - jobserver\EJS-DATA\env\\env.info
      Environment information created when JobServer environment is run.

        env.info : Will contain environment information that is useful for debugging
                   by support staff.

  - jobserver\database
      Contains database setup information. If you are using the JobServer Professional
      version you will need to load the JobServer schema into the target database.
      Oracle, Postgres, HSQL, and Mysql are supported. Follow the instructions for the
      corresponding database you are using.

  - jobserver\sys
      Internal libraries.

  - jobserver\sys\app\logs\
      Locaton of webserver log files. Useful for debugging purposes.

  - jobserver\EJS-DATA\startup-log\\startup-log.txt
      Locaton of JobServer Engine startup log files. Useful for debugging purposes.

  - jobserver\soafaces
      Directory where SOAFaces jar (.sfb files) files are placed. When you develop or 
      acquire a new SOAFaces Bundle (SFB), this archive SFB file (jar format) should be
      placed in this directory so that it can be used by JobServer. Note that if you place
      a new SFB in this directory it will be detected within a couple of minutes. An
      SFB archive file will container your Weblet and Tasklet code.

  - jobserver\mule
      Directory where you can added your custom mule UMO jars and configuration files. 
      These UMOs will then be loaded by the JobServer Engine/Scheduler and by the
      JobServer WebServer when each is started. The following configuration exists:

        my-mule-conf : XML configuration files used by Mule engine running in JS
                       Container/Engine.

        my-mule-jars : Jar files used by Mule engine in JS Container/Engine as
                       defined by XML configuration.

        my-webmule-conf : XML configuration files used by Mule engine running in
                          JS Webserver.

        my-webmule-jars : Jar files used by Mule engine in JS WebServer as
                          defined by XML configuration.



Using Mule:
-----------

 JobServer comes with integrated support for Mule. This gives you the ability to both
 invoke/access remote Mule services as well as host Mule services directly in your
 JobServer environment by embedding Mule servers in the your JobServer environment.

 Invoking Mule Services from Tasklets and Weblets:
 You can use JobServer and the SOAFaces Open Source SDK to invoke remote Mule services
 anywhere in your network. You can use the MuleClient available from the SOAFaces
 server-side Tasklet API to access mule/SOA services found anywhere within your enterprise.
 The SOAFaces Weblet API also allows you, through the SOAFaces GWT UniversalClient interface,
 to access Mule/SOA services directly from your GWT/Weblet applications.

 Embedding Mule Servers in JobServer:
 You can also deploy Mule services both in the JS webserver(s) and the JS Container.
 This allows you to embed an instance of a Mule server in both the JS Conainer and in
 the JS webserver(s) and thus host Mule services directly in the JobServer environment.
 You can configure the Mule services for both the webservers and JS Container by
 including mule XML configuration files in the "jobserver\mule" directory as described
 in the previous section above.

 Configuring Mule:
 If you have a distribution of JS that includes Mule, you can enable Mule by setting the
 "useMule" property in the system-config.properties to true. It is important to have this
 properly set to true to have the Mule features enabled within the JobServer environment.
 There are also three other properties you can configure to control what level of Mule support
 you wish to have active in JobServer. The properties are documented in the Advanced
 Configuration Properties section found here.



Weblet Only Mode:
-----------------

 You can configure the JobServer environment to only run Weblets, if you only want
 to build SOA GUI applications and are not interested in running a job scheduling
 environment. You can specify it to use weblet only mode in the system-config.bat
 configuration file. Set the WebletOnlyMode property to true.

 This disables the job scheduler from running and allows you to configure
 mule/SOA applications (and use Weblets) without the scheduler. You can deploy
 multiple weblet applications and deploy them across a cluster of JS webservers.



Webserver Clustering:
---------------------

 If you are using JobServer Professional, then you can configure your environment to
 be clustered on any number of webserver host machines when configuring the webserver
 tier within JobServer. This allows running the JobServer GUI applications and JobServer
 web services across a cluster of web servers to distribute load. To do this you install
 your JobServer environment on a central file server that can be mounted across your
 cluster of machines. Then use the jsstartup.bat command to startup your JS webserver on
 each machine.


Job Processing & Clustering - Using Agents:
-------------------------------------------

 You have the option of running jobs on multiple servers and thus distributing the
 load across a cluster of servers. This serves two purposes. One you can
 expand your processing power and run jobs across your network in a distributed
 fashion. Second, it allows you to bulid-in redundancy and failover capability
 so that if one computer goes down others can pick up the job processing load.
 JobServer supports the concept of Agents, which are computers running the JobServer
 software that can be tied to job Partitions to enable distributed and clustered
 job processing.

 Note, to enable the Agents feature in JobServer, you will need to set the property
 "agentPort" in the system-config.properties file to enable the Agent feature. This
 will set the port number used by the Agent servers on each host machine they are
 installed and run on.


Installing Agent Nodes:
-----------------------

 You can add new Agent nodes to a JobServer cluster using the following steps:

 1) Make sure you have the property "agentPort" set in the system-config.properties
    file. This defines the port number that all the Agent nodes will use. You must
    also explicitly set the "primarySchedServer" property. This lets all the remote
    nodes know the name of the primary node.
 2) Agent nodes must use the same installation directory used by the primary/secondary
    nodes. All the nodes in a JobServer cluster must mount the main central directory
    where the JobServer software is installed, so you install the JobServer software
    only once and all the JobServer host computers that are part of the cluster must
    mount this central installation directory. So make sure your Agent nodes are
    mounting the central directory where you have the JobServer software installed.
 3) Now, use the JobServer Workbench UI and go to the System Admin Agent UI. From
    this app you can define and "Add" new Agent nodes. Note, this step only defines
    and configures a new Agent node. It does not actually initialize or start the node
    yet.
 4) Next, using the command line, login directly into the Agent host machine and go to
    the "jobserver/bin" directory and run the command "jsstartup.bat". This will
    initialize the Agent node and add it into the JobServer cluster and make it
    available to start/stop and allow it to run jobs. Also note, when you do this make
    sure the "AgentContainer" hostname shown in the results of the "jsstartup.bat"
    script matches then name of the host name you set in this Add Agent UI. If the Agent
    computer has multiple host names, you can force the Agent node to use a specific one
    (the one set in the Agent UI), by having your administrator customize the specific
    hostname you want to use by setting the shell script property "JOBSERVER_HOSTNAME".
 5) Next, use the JobServer Workbench UI and go to the System Admin Agent UI. From
    this app you can start/stop and manage your newly initialized Agent node in the
    JobServer cluster.


JobServer Failover Configuration:
---------------------------------

 JobServer can be configured in a failover mode by specifying a secondary server
 that will automatically start the JobServer scheduling engine if the primary server
 fails to start. For example, if JobServer on the primary server crashes, the
 secondary JobServer instance on the secondary server will detect the failover and
 start a new JobServer scheduling engine that will put the job scheduler into the same
 mode it was previously running in on the primary server, and then continue to run jobs
 and retry failed jobs (if the failed jobs are configured with the retry option).


Tasklet Logging:
----------------

 JobServer captures all logging performed by a Tasklet when Log4J or Java Logging
 logging calls are made. When you implement your Tasklet, you can use either one
 of these logging frameworks to have your logging messages appear in Job Tracker
 when the Tasklet is run in a job.

 Log4J logger must implement additivity=true for logging to be captured by Job Tracker.
 You normally do not need to configure anything extra, but you can find Log4J and Java
 Logging configuration files the jobserver\conf directory.

    
  
Advanced Configuration Properties:
---------------------------------

  JobServer Standard and Professional have configuration options that
  can be set in the "product-config.properties" file. Below are listed
  some of the advanced properties that can be set.

     SchedulerScanTime:
          The scheduler default wait time before scanning. The scheduler
          does not wait for the scan time to run a job. The scan time is
          primarly for testing purposes and to recover from error situations.

     PartitionThreadCache: 
          Thread pool size used by Partitions. Having a thread pool can improve
          Job run response times. It allows a job that runs to reuse an already
          created/cached thread, thereby avoiding the cost of creating a new 
          thread. Note, that this may be a problem for some systems that have 
          certain dependencies on ThreadLocal variable usage. Set this property 
          to zero, if this is a concern; this will cause a new thread to be created 
          instead of using the cache/pool.
     
     MuleConfigGUIEnabled:
          When set to "true", this will enable an option in the JobServer startup GUI
          that will allow the user to manually configure if JobServer should be started
          with or without an embedded Mule server.  Note, this option does not enable or
          disable Mule from running inside the JobServer container, it only allows the
          user, from the System Administration tool, to manually control this
          configuration option.

     MuleServerWSEnabled:
          When set to "true", will enable all JobServer webservers to run an
          embedded Mule server instance to host Mule services implementations. You
          will need to have Mule software installed and the useMule property set
          for this to be effective. Defaults to false.

     MuleClientInitialize:
          When set to "true", this will initialize the MuleClient API in the JS
          Scheduling Engine. Set this to "false" if you plan to initialize your
          own MuleClient and Mule Context during JS startup (ContainerStartupListener).
          If you do not initialize this or create your own MuleClient during startup
          then Tasklets that run, that try to use a MuleClient, will create a background
          thread first time they are run and will prevent the job from completing
          properly. Defaults to true.

     EmailAlertScanTime:
          Number of seconds to wait before checking for and sending out an alert email
          if there is a problem with the JobServer Scheduler. Email will be sent if
          JobServer Scheduler is not in running mode or if secondary WebServer is
          not available (and secondary scheduler hostname is specified). Setting to
          zero disables these email alerts. These alerts are sent by the webservers.

     SOAFacesDirScanTime:
          Time in seconds between when the web server will check for new .sfb files
          to expand. It also is the time between flushing the classloader cache
          for a SFB (to check fo updated SFB classes).

     ContainerStartupListenerImpl:
          Implementation of interface that will be initialized when the JobServer Engine/Scheduler
          is started. Place the corresponding implementation classes/jars in the directory
          jobserver\common-lib\workflow. See SOAFaces JavaDocs.

     AgentContainerStartupListenerImpl:
          Implementation of interface that will be initialized by JobServer Agent servers when
          they are started. Place the corresponding implementation classes/jars in the directory
          jobserver\common-lib\workflow. See SOAFaces JavaDocs.

     JVMContainerStartupListenerImpl:
          Implementation of interface that will be initialized by an external JobSever proceses
          when a job is run in an external JVM process. Place corresponding implementation
          classes/jars in the directory jobserver\common-lib\workflow. See SOAFaces JavaDocs.

     WebContainerStartupListenerImpl:
          Implementation of interface that will be initialized when the web server is started.
          Place the corresponding implementation classes/jars in the directory
          jobserver\common-lib\services. See SOAFaces JavaDocs.

     TaskBeanThreadJoin:
          When set to "true" will force a job to join all tasklet sub threads before
          tasklet/job completes processing.

     FailoverScanTime:
          Seconds to wait between checking for running JobServer instance. If no primary
          server is detected, it will attempt to start a new instance on primary or
          secondary host. This defines the time to wait before JobServer instance process
          is restarted if it was shutdown unexpectedly. Note, this does not start the
          JobServer scheduler, it only puts JobServer in IDLE state. Setting this property
          to 0, disables auto restarting of JobServer instances. See PrimeFailoverRestartEnabled
          property for how to put JS Scheduler back into running mode after an unexpected
          crash.

     PrimeFailoverRestartEnabled:
          If true, enables the primary webserver/watchdog to restart the JobServer
          scheduler if it is detected to be shutdown unexpectedly and to put the scheduler back into
          the same mode it was in before the crash. If you are using a secondary failover server,
          the secondary failover watchdog will attempt to perform the same task and restart
          the primary scheduler automatically if it can. Enabling this, allows the primary
          watchdog to do the same restart task as the secondary watchdog. You should in
          general, set this property to be true when using a failover configuration.
          You can use this feature even without failover/secondary server being configured
          (FailoverScantTime enabled). Set this property if you want the primary weberver/watchdog
          to restart the JobServer scheduler on the primary server if a crash is detected.

     WebServerSystemCacheScanTime:
          Seconds to wait by webserver to reload system cache information such as
          changes to email notifications and other related system information.

     DualInstanceCheckScanTime:
          Seconds to wait by primary and secondary server to check for multiple
          JobServer instances running. This helps prevent multiple instance from
          running concurrently. Will force shutdown if detected.

     TaskletClassloaderCache:
          Set to true to enable classloaders used by Tasklets to be cached between
          job runs. Normally this is disabled which requires each Tasklet to have
          a unique classloader per run even if classes are the same. This has benefits
          in that nothing is saved (static class state) between two different job runs.
          Advantage of enabling cache is reduced classloading load and memory usage.

     ChildFirstClassloading:
          If true, it makes Tasklets and Weblets use "child first" class loading similar
          to how java webapp containers work when running web applications. If false
          then the default parent first class loading rules apply.

     DBErrorRetryCount:
          This specifies the number of retries that are attempted when a low level database
          error or problem occurs during JS system processing or job/tasklet processing.

     DBErrorRetryTime:
          Related to the DBErrorRetryCount property. Specifies the amount of seconds
          to wait after each set of DBErrorRetryCount retries are attempted.



SSL Support:
-----------
  
  It is recommended you place an Apache reverse proxy SSL server in front of
  JobServer's webserver for best support for SSL. If you do not wish to do
  this and you want JobServer's webserver to support SSL directly, follow
  the instructions below.

  Accessing the JobServer applications over SSL is available. To do this
  you need to create a "webserver.keystore" file and place it in the directory
  "jobserver\conf". You will need to have a server certificate issued from a 
  major certificate authority (e.g. verisign.com or thawte.com). Once you have
  been issued a certificate place it in the "webserver.keystore" file and set
  with the password "changeme". Then replace the server.xml file with serverSSL.xml
  file found in jobserver\sys\app\conf.

  This will startup the web server with ssl enabled. You should now be able
  to access Jobserver using the url:

      https://<yourhost>:<port>/jobserver

      
   
For support:
-----------

      support@grandlogic.com
      



Copyright © Grand Logic, Inc. All Rights Reserved.