Product Knowledge Base

Space shortcuts

Page tree

Scope

  • JOC Cockpit is operated with a Docker container. 
  • Prerequisites
    • The JOC Cockpit requires a database to be available from any physical or virtual host or from a Docker container.
    • Consider to prepare the files indicated with chapter Build.

Build

The following files are required for the build context:

  • Dockerfile
  • Installer Response file joc_install.xml with individual installation settings. A template of this file is available when extracting the installer tarball.
  • Start Script start_joc.sh
  • JOC Cockpit installer tarball as available from SOS for download.

Dockerfile

  • Download: Dockerfile

    Dockerfile 
    FROM openjdk:8
LABEL maintainer="Software- und Organisations-Service GmbH"

# default user id has to match later run-time user
ARG USER_ID=$UID

# provide build arguments for release information
ARG JS_MAJOR=1.13
ARG JS_RELEASE=1.13.3

# add installer archive file
COPY joc_linux.${JS_RELEASE}.tar.gz /usr/local/src/
RUN test -e /usr/local/src/joc_linux.${JS_RELEASE}.tar.gz && \
    tar zxvf /usr/local/src/joc_linux.${JS_RELEASE}.tar.gz -C /usr/local/src/ && \
    rm -f /usr/local/src/joc_linux.${JS_RELEASE}.tar.gz && \
    ln -s /usr/local/src/joc.${JS_RELEASE} /usr/local/src/joc

# for JDK < 12, /dev/random does not provide sufficient entropy, see https://kb.sos-berlin.com/x/lIM3
RUN rm /dev/random && ln -s /dev/urandom /dev/random

# copy installer response file and run installer
COPY joc_install.xml /usr/local/src/joc/
RUN /usr/local/src/joc/setup.sh -u /usr/local/src/joc/joc_install.xml

# make default user the owner of directories
RUN groupadd --gid ${USER_ID:-1000} jobscheduler && \
    useradd --uid ${USER_ID:-1000} --gid jobscheduler --home-dir /home/jobscheduler --no-create-home --shell /bin/bash jobscheduler && \
    chown -R jobscheduler:jobscheduler /var/sos-berlin.com

# copy and prepare start script
COPY start_joc.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/start_joc.sh

# create volumes for data persistence 
# VOLUME /var/sos-berlin.com/joc

# allow incoming traffic to port
EXPOSE 4446 

# run-time user, can be overwritten when running the container
USER jobscheduler

CMD ["/usr/local/bin/start_joc.sh"]
  • Explanations
    • Line 1: We start from an Alpine image that includes JDK 8. Newer Java version can be used, see Which Java versions is JobScheduler available for?
    • Line 5: Consider that $UID provides the numeric ID of the account that the JOC Cockpit installation inside the Docker container is performed for. This numeric ID typically starts above 1000 and should correspond to the account that is used on the Docker host, i.e. the account on the Docker Host and the account inside the container should use the same numeric ID. This mechanism simplifies exposure of the Docker container's file system.
    • Line 8-9: Adjust the JobScheduler release number as required.
    • Line 12-16: The installer tarball is copied and extracted to the container.
    • Line 22-23: The installer response file is copied to the container, for details of this file see next chapter. Then the installer is executed for the current user.
    • Line 26-28: An account and group "jobscheduler" is created that is handed over ownership of installed files.
    • Line 31-32: The start script is copied to the container, see below chapter Start Script.
    • Line 38: Port 4446 is exposed for later mapping. This port is used for the connection between user browsers and JOC Cockpit.
    • Line 41: The account "jobscheduler" that is the owner of the installation is exposed for later mapping. This account should be mapped at run-time to the account in the Docker Host that would mount an optionally exposed volume.
    • Line 43: The start script is executed to launch the JOC Cockpit daemon.

Installer Response File

  • Download: joc_install.xml

    Installer Response File 
    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- 
XML configuration file for JOC

If you call the installer with this XML file then 
you accept at the same time the terms of the 
licence agreement under GNU GPL 2.0 License 
(see http://www.gnu.org/licenses/gpl-2.0.html)
-->
<AutomatedInstallation langpack="eng">
    <com.izforge.izpack.panels.UserInputPanel id="home">
        <userInput/>
    </com.izforge.izpack.panels.UserInputPanel>
    <com.izforge.izpack.panels.HTMLLicencePanel id="gpl_licence"/>
    <com.izforge.izpack.panels.TargetPanel id="target">
        
        <!-- SELECT THE INSTALLATION PATH
             It must be absolute! 
             For example:
             /opt/sos-berlin.com/joc on Linux
             C:\Program Files\sos-berlin.com\joc on Windows -->
        <installpath>/opt/sos-berlin.com/joc</installpath>
        
    </com.izforge.izpack.panels.TargetPanel>
    
    <com.izforge.izpack.panels.UserInputPanel id="jetty">
        <userInput>
            
            <!-- JOC requires a servlet container such as Jetty. 
                 If a servlet container already installed then you can use it. 
                 Otherwise a Jetty will be installed in addition if withJettyInstall=yes.
                 You need root permissions to install JOC with Jetty. -->
            <entry key="withJettyInstall" value="yes"/>
            <entry key="jettyPort" value="4446"/>
            <!-- Specify the name of the Windows service or Linux Daemon (default: joc).
                 Only necessary for multiple instances of JOC on one server. It must be 
                 unique per server. This entry is deactivated by a comment because it
                 MUST NOT BE CHANGED DURING OVER-INSTALLATION! -->
            <!--
            <entry key="jettyServiceName" value="joc"/>
            -->
            <!-- Only necessary for Windows -->
            <entry key="jettyStopPort" value="40446"/>
            <!-- Only necessary for Unix (root permissions required) -->
            <entry key="withJocInstallAsDaemon" value="yes"/>
            <!-- To enter a JOC User (default=current User). 
                 For Unix only (root permissions required)!!! -->
            <entry key="runningUser" value=""/>
            <!-- Path to Jetty base directory 
                 For example:
                 /home/[user]/sos-berlin.com/joc/jetty_base on Linux
                 C:\ProgramData\sos-berlin.com\joc\jetty_base on Windows -->
            <entry key="jettyBaseDir" value="/var/sos-berlin.com/joc"/>
            <!-- Choose (yes or no) wether the JOC's Jetty should be (re)started at the end of the installation -->
            <entry key="launchJetty" value="no"/>
            
            <!-- Java options for Jetty. -->
            <!-- Initial memory pool (-Xms) in MB -->
            <entry key="jettyOptionXms" value="128"/>
            <!-- Maximum memory pool (-Xmx) in MB -->
            <entry key="jettyOptionXmx" value="512"/>
            <!-- Thread stack size (-Xss) in KB -->
            <entry key="jettyOptionXss" value="4000"/>
            <!-- Further Java options -->
            <entry key="jettyOptions" value=""/>
            
        </userInput>
    </com.izforge.izpack.panels.UserInputPanel>
    
    <com.izforge.izpack.panels.UserInputPanel id="reportingDatabase">
        <userInput>
            <!-- Reporting Database Configuration -->
            
            <!-- Database connection settings can be specified with following entries such as
                 databaseHost, databasePort, ... or by a hibernate configuration file 
                 Posible values are 'withoutHibernateFile' (default) and 'withHibernateFile'. -->
            <entry key="reporting.databaseConfigurationMethod" value="withoutHibernateFile"/>
                 
            <!-- Choose the database management system. Supported values are 'mysql' for MySQL,
                 'oracle' for Oracle, 'mssql' for MS SQL Server, 'pgsql' for PostgreSQL.
                 Only if reporting.databaseConfigurationMethod=withoutHibernateFile -->
            <entry key="reporting.databaseDbms" value="mysql"/>
            
            <!-- Path to a hibernate configuration file if reporting.databaseConfigurationMethod=withHibernateFile -->
            <entry key="reporting.hibernateConfFile" value=""/>
            
        </userInput>
    </com.izforge.izpack.panels.UserInputPanel>
    
    <com.izforge.izpack.panels.UserInputPanel id="reportingDbconnection">
        <userInput>
            <!-- Reporting Database Configuration  if reporting.databaseConfigurationMethod=withoutHibernateFile -->
                 
            <!-- Enter the name or ip address of the database host 
                 This entry can also be used to configure the URL(s) for Oracle RAC databases.
                 For example:
                 <entry key="reporting.databaseHost" value="(DESCRIPTION=(ADDRESS_LIST=(LOAD_BALANCE=OFF)(FAILOVER=ON)
                    (ADDRESS=(PROTOCOL=TCP)(HOST=tst-db1.myco.com)(PORT=1604))
                    (ADDRESS=(PROTOCOL=TCP)(HOST=tst-db2.myco.com)(PORT=1604)))
                    (CONNECT_DATA=(SERVICE_NAME=mydb1.myco.com)(SERVER=DEDICATED)))"/>
                 The "reporting.databaseSchema" and "reporting.databasePort" entries should then be left empty. -->
            <entry key="reporting.databaseHost" value="mysql-5-7"/>
            
            <!-- Enter the port number for the database instance. Default ports are for MySQL 3306, 
                 Oracle 1521, MS SQL Server 1433, postgreSQL 5432. -->
            <entry key="reporting.databasePort" value="3306"/>
            
            <!-- Enter the schema -->
            <entry key="reporting.databaseSchema" value="jobscheduler113"/>
            
            <!-- Enter the user name for database access -->
            <entry key="reporting.databaseUser" value="jobscheduler"/>
            
            <!-- Enter the password for database access -->
            <entry key="reporting.databasePassword" value="jobscheduler"/>
            
        </userInput>
    </com.izforge.izpack.panels.UserInputPanel>
    
    <com.izforge.izpack.panels.UserInputPanel id="reportingJdbc">
        <userInput>
            <!-- Reporting Database Configuration 
                 NOT SUPPORTED FOR SYBASE AND DB2 -->
            
            <!-- You can specify an external JDBC connector then set reporting.internalConnector = no
                 For license reasons MySQL, MS SQL Server and Oracle ojdbc7 JDBC 
                 drivers are not provided. 
                 Alternatively you can use the mariadb JDBC Driver for MySQL and 
                 the jTDS JDBC Driver for MS SQL Server and Sybase which is provided. 
                 An Oracle ojdbc6 JDBC driver is also provided. -->
                 
            <!-- You can choose between 'yes' or 'no' for using the internal JDBC connector
                 or not -->
            <entry key="reporting.internalConnector" value="yes"/>
                 
            <!-- Select the path to JDBC Driver -->
            <entry key="reporting.connector" value=""/>
            
        </userInput>
    </com.izforge.izpack.panels.UserInputPanel>
    
    <com.izforge.izpack.panels.UserInputPanel id="database">
        <userInput>
            <!-- JobScheduler Database Configuration -->
            
            <!-- Set 'yes' if the Reporting and the JobScheduler database are the same.
                 If 'yes' then further JobScheduler database variables are ignored. -->
            <entry key="sameDbConnection" value="yes"/>
            
            <!-- Database connection settings can be specified with following entries such as
                 databaseHost, databasePort, ... or by a hibernate configuration file 
                 Posible values are 'withoutHibernateFile' (default) and 'withHibernateFile'. -->
            <entry key="databaseConfigurationMethod" value="withoutHibernateFile"/>
                 
            <!-- Choose the database management system. Supported values are 'mysql' for MySQL,
                 'oracle' for Oracle, 'mssql' for MS SQL Server, 'pgsql' for PostgreSQL,
                 'db2' for DB2 and 'sybase' for Sybase. 
                 Only if databaseConfigurationMethod=withoutHibernateFile -->
            <entry key="databaseDbms" value="mysql"/>
            
            <!-- Path to a hibernate configuration file if databaseConfigurationMethod=withHibernateFile -->
            <entry key="hibernateConfFile" value=""/>
            
        </userInput>
    </com.izforge.izpack.panels.UserInputPanel>
    
    <com.izforge.izpack.panels.UserInputPanel id="dbconnection">
        <userInput>
            <!-- JobScheduler Database Configuration if databaseConfigurationMethod=withoutHibernateFile -->
                 
            <!-- Enter the name or ip address of the database host 
                 This entry can also be used to configure the URL(s) for Oracle RAC databases.
                 For example:
                 <entry key="databaseHost" value="(DESCRIPTION=(ADDRESS_LIST=(LOAD_BALANCE=OFF)(FAILOVER=ON)
                    (ADDRESS=(PROTOCOL=TCP)(HOST=tst-db1.myco.com)(PORT=1604))
                    (ADDRESS=(PROTOCOL=TCP)(HOST=tst-db2.myco.com)(PORT=1604)))
                    (CONNECT_DATA=(SERVICE_NAME=mydb1.myco.com)(SERVER=DEDICATED)))"/>
                 The "databaseSchema" and "databasePort" entries should then be left empty. -->
            <entry key="databaseHost" value="mysql-5-7"/>
            
            <!-- Enter the port number for the database instance. Default ports are for MySQL 3306, 
                 Oracle 1521, MS SQL Server 1433, postgreSQL 5432, DB2 50000, Sybase 5000. -->
            <entry key="databasePort" value="3306"/>
            
            <!-- Enter the schema -->
            <entry key="databaseSchema" value="jobscheduler113"/>
            
            <!-- Enter the user name for database access -->
            <entry key="databaseUser" value="jobscheduler"/>
            
            <!-- Enter the password for database access -->
            <entry key="databasePassword" value="jobscheduler"/>
            
        </userInput>
    </com.izforge.izpack.panels.UserInputPanel>
    
    <com.izforge.izpack.panels.UserInputPanel id="jdbc">
        <userInput>
            <!-- JobScheduler Database Configuration -->
            
            <!-- You can specify an external JDBC connector then set internalConnector = no
                 For license reasons MySQL, Sybase, MS SQL Server and Oracle ojdbc7 JDBC 
                 drivers are not provided. 
                 Alternatively you can use the mariadb JDBC Driver for MySQL and 
                 the jTDS JDBC Driver for MS SQL Server and Sybase which is provided. 
                 An Oracle ojdbc6 JDBC driver is also provided.
                 An internal JDBC connector for DB2 is not available -->
                 
            <!-- You can choose between 'yes' or 'no' for using the internal JDBC connector
                 or not -->
            <entry key="internalConnector" value="yes"/>
            
            <!-- Select the path to JDBC Driver -->
            <entry key="connector" value=""/>
            
            <!-- Only for DB2: Select the path to DB2 license file for JDBC Driver -->
            <entry key="connectorLicense" 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>
  • Explanations
    • The above installer response file works for releases 1.13. Other releases ship with different versions of this file. You should pick-up a template of this file that matches your JobScheduler release by extracting the installer tarball. 
    • Generally all defaults of the response file can be maintained.
      • This includes use of port 4446 for the connection of user browsers to JOC Cockpit. At run-time this port can be mapped, see Dockerfile.
    • Line 182-233: The database connection makes use of a hostname "mysql-5-7" that is assumed to be the hostname of a Docker container in the same Docker network running the MySQL database.
      • Modify the database connection settings as required for use with your DBMS and access credentials.

Start Script

  • Download: start_joc.sh

    Start Script
    #!/bin/sh

/opt/sos-berlin.com/joc/jetty/bin/jetty.sh start && tail -f /dev/null
  • Explanations
    • Line 3: The standard start script jetty.sh is used. The tail command prevents the start script from terminating in order to keep the container alive.

Build Command

There are a number of ways how to write a build command, find the following example:

  • A typical build command could look like this:

    Build Command
    #!/bin/sh

IMAGE_NAME="joc-1-13"

docker build --no-cache --rm --tag=$IMAGE_NAME --file=./build/Dockerfile --network=js --build-arg="USER_ID=$UID" ./build
  • Explanations
    • Using a common network for JobScheduler components allows direct access to resources such as ports within the network. The network is required at build time to allow the installer to use the JobScheduler database.
    • Consider use of the --build-arg that injects the USER_ID environment variable into the image with the numeric ID of the account running the build command. This simplifies later access to the optionally exposed volume specified by the Dockerfile as the same numeric user ID and group ID inside and outside of the container are used.

Run

There are a number of ways how to write a run command, find the following example:

  • A typical run command could look like this:

    Run Command
    #!/bin/sh

IMAGE_NAME="joc-1-13"
RUN_USER_ID="$(id -u $USER):$(id -g $USER)"

mkdir -p /some/path/logs

docker run -dit --rm --user=$RUN_USER_ID --hostname=$IMAGE_NAME --network=js --publish=4446:4446 --volume=/some/path/logs:/var/log/sos-berlin.com/joc:Z --name=$IMAGE_NAME $IMAGE_NAME
  • Explanations
    • Using a common network for JobScheduler components allows direct access to resources such as ports within the network.
    • The RUN_USER_ID variable is populated with the numeric ID of the account and the group that executes the run command. This value is assigned the --user option to inject the account information into the container (replacing the account specified with the USE jobscheduler instruction in the Dockerfile).
    • Port 4446 for access by user browsers to JOC Cockpit should be mapped to some outside port on the Docker host. Consider the firewall on the Docker host to allow incoming traffic to the mapped port.
    • Specify a logs directory to be created that is referenced with the --volume option to expose the log directory of the JOC Cockpit for reading. Avoid to modify log files in this directory and to add new files.



  • No labels