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