Skip to content
This repository has been archived by the owner on Dec 3, 2017. It is now read-only.

Runtime Configuration

Jump to bottom
Ralph Schaer edited this page Feb 11, 2013 · 31 revisions

By default the runner tries to read the configuration from a file with name config.yaml in the same directory where the jar resides.

It is possible to use a configuration file with a different name and/or from a different location by specifying the path to the file as the first argument

java -jar app.jar /etc/myconfig.yaml

If no configuration file is specified or exists the runner uses these defaults:

  • Extracts the jar contents into the subdirectory tc
  • Starts a Tomcat that listens on port 8080 and is either using the blocking Java based connector (org.apache.coyote.http11.Http11Protocol) or, if the tcnative.dll exists on the library path, a APR/native based connector (org.apache.coyote.http11.Http11AprProtocol)
  • Deploys the first war he finds in the jar to the ROOT context.

The configuration file has to be in the YAML format. The runner supports the following root level elements.

extractDirectory

Directory in which the runner extracts the war files and creates the temp and log directories. The runner creates this directory if it does not exists. Absolute and relative paths are supported. If this option denotes a relative path it will be resolved to the directory where the jar is located.
Default value is tc.
The first time the runner extracts a jar file he also extracts a timestamp file into the extraction directory. Then every time the runner starts he checks if the timestamp file in the jar is newer than the timestamp file in the extraction directory. If the jar is newer he deletes the extraction directory and recreates it with the new contents. If there is a lock on this directory the application startup fails.

# Set the extraction directory to /tmp/tc
extractDirectory: /tmp/tc

The executable jar supports an additional command line parameter (-c or --clean) that forces the deletion and recreation of the extraction directory.

java -jar app.jar /etc/myconfig.yaml -c

systemProperties

The runner sets this properties with System.setProperty. A web application can read these properties with System.getProperty. This is one way to configure a web application without hardcoding the configuration into the source.

# twitter4j configuration
systemProperties: 
  twitter4j.oauth.consumerKey: xQUmJb
  twitter4j.oauth.consumerSecret: VhC
  twitter4j.oauth.accessToken: 98029
  twitter4j.oauth.accessTokenSecret: KL3A6

As an alternative system properties can be specified on the command line

java -Dtwitter4j.oauth.consumerKey=xQUmJb -jar app.jar

connector

This element configures a HTTP or AJP connector. This element only supports one connector. If you need more than one connector use the connectors element (see next section).

For a list of configuration options see the official Tomcat documentation:

Every option that is described in the documentation is supported here. When the port configuration is omitted it is set to 8080 and the URIEncoding option is set to UTF-8 (this is different to the normal Tomcat handling where it is set to ISO-8859-1 by default!). The protocol element has the default value HTTP/1.1. This results in either a blocking Java based connector or an APR/native based connector.

# A blocking java based HTTP or APR/native based connector on port 80
connector: 
  port: 80

connectors

This element configures one or multiple HTTP and AJP connectors. To separate the different connector configurations the first sub element of every connector has to start with a minus (-) character. Every sub element that the connector element supports is also supported here.

# A non blocking java HTTP connector on port 81 and a AJP connector on port 8009
connectors: 
  - port: 81
    protocol: org.apache.coyote.http11.Http11NioProtocol
    connectionTimeout: 120000
    
  - port: 8009
    protocol: AJP/1.3
    tomcatAuthentication: false

context

This element configures a web application. If more than one web application has to be deployed use the contexts element (see next section). If no context or contexts element is specified the runner will deploy the first war file he finds to the ROOT context.

The following sub elements are supported:

  • embeddedWar
    Name of a war file that is embedded in the jar file. If not specified the runner takes the first war he finds. As a wildcard the character * is supported
context: 
  embeddedWar: test-*.war
  • externalWar
    Absolute or relative path to an external war (not embedded in our jar). If the path is relative the runner resolves it with the directory where the jar resides as base. If embeddedWar and externalWar are present embeddedWar takes precedence.
context: 
  externalWar: /var/another.war
  • contextFile
    Specifies an external context xml file. If this parameter points to a valid context xml file then searching for the /META-INF/context.xml file in the war is skipped.
context: 
  contextFile: /var/myconfig.xml
  • contextPath
    Specifies the context path of the web application. If specified with an empty value or element is omitted then the application is deployed in the ROOT context ("")
context: 
  # Root context
  # contextPath: 
  
  # /test context
  contextPath: /test
  • sessionPersistence
    If session objects should be persisted when Tomcat shuts down. Default false
context: 
  sessionPersistence: true
  • resource / resources
    These elements specifies one (resource) or multiple (resources) resource definitions.
    See the Tomcat documentation for more information about Resource Definitions and JNDI Resources. This is usually used for jdbc database pool or mail session definitions. If these resources need additional libraries don't forget to add them with the extraDependencies option in the Maven plugin configuration.
context: 
  resource:
    name: jdbc/db
    auth: Container
    factory: org.apache.tomcat.jdbc.pool.DataSourceFactory
    type: javax.sql.DataSource
    username: sa
    password: sa
    driverClassName: net.sourceforge.jtds.jdbc.Driver
    url: jdbc:jtds:sqlserver://localhost/db
    initialSize: 10
    minIdle: 10
    maxIdle: 20
    maxActive: 20
    maxWait: 20000
    defaultAutoCommit: false

Multiple resources are specified with the resources element. Important is the minus (-) character at the beginning of every block

context: 
  resources: 
    - name: jdbc/EmployeeDB
      auth: Container
      type: javax.sql.DataSource
      description: Employees Database for HR Applications
    - name: mail/Session
      auth: Container
      type: javax.mail.Session
      mail.smtp.host: localhost
  • parameter / parameters
    These elements configures one (parameter) or multiple (parameters) named values that will be made visible to the web application as servlet context initialization parameters. See the Tomcat documentation for more information about Context Parameters 
context:
  # Corresponds to this xml definition
  #   <Parameter name="companyName" 
  #              value="My Company, Incorporated"
  #              override="false"/>
  parameter:
    name: companyName
    value: My Company, Incorporated
    override: false

Multiple parameters are specified with the parameters element. Important is the minus (-) character at the beginning of every block

context:
  parameters:
    - name: first
      value: 1
    - name: second
      value: 2
  • environment / environments
    These elements configures one (environment) or multiple (environments) named values that will be made visible to the web application as environment entry resources. See the Tomcat documentation for more information about Environment Entries and JNDI Resources 
context:
  # Corresponds to this xml definition
  # <Environment name="maxExemptions" value="10"
  #              type="java.lang.Integer" override="false"/>
  environment:
    name: maxExemptions
    value: 10
    type: java.lang.Integer
    override: false

Multiple environments values are specified with the environments element. Important is the minus (-) character at the beginning of every block

context:
  environments:
    - name: spring.profiles.active 
      value: development
      type: java.lang.String
    - name: indexBase
      value: /var/ix
      type: java.lang.String
    - name: next.version.major
      value: 5
      type: java.lang.Integer
    - name: next.version.minor
      value: 2
      type: java.lang.Integer

contexts

This element configures one or more web applications. All sub elements of context are supported. To separate the web applications the first element of each configuration block has to start with a minus (-) character.

contexts:        
  - embeddedWar: first*.war
    contextPath: /one
  
  - embeddedWar: second*.war
    contextPath: /two

listeners

This element configures the Tomcat lifeCycle listener. When this element is omitted the org.apache.catalina.core.AprLifecycleListener listener is installed by default.

#Install all listeners of a default Tomcat setup
listeners: 
  - org.apache.catalina.core.AprLifecycleListener
  - org.apache.catalina.core.JasperListener
  - org.apache.catalina.core.JreMemoryLeakPreventionListener
  - org.apache.catalina.mbeans.GlobalResourcesLifecycleListener
  - org.apache.catalina.core.ThreadLocalLeakPreventionListener

If the listeners element contains no sub elements, no listener is installed:

listeners:
# nothing here therefore no lifecycle listeners

valve

This element configures one valve. The current release (1.1) only supports valves on host level. See the Tomcat documentation Valve Component for more information. Every described configuration option is supported.

valve:
  className: org.apache.catalina.valves.AccessLogValve
  directory: logs
  prefix: localhost_access_log
  suffix: .txt
  pattern: "%h %l %u %t %r %s %b"

valves

This element configures one or more valves. All sub elements of valve are supported. To separate the valve configurations the first element of each block has to start with a minus (-) character.

valves:
  - className: org.apache.catalina.valves.AccessLogValve
    directory: logs
    prefix: localhost_access_log
    suffix: .txt
    pattern: "%h %l %u %t %r %s %b"
    
  - className: org.apache.catalina.valves.RemoteAddrValve
    allow: 127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1

jvmRoute

This element specifies the jvmRoute option of the engine container. This is needed for load balancing scenarios to enable session affinity.

jvmRoute: appserver1

shutdown

If specified sets the shutdown port and command in Tomcat. Tomcat then listens on the configured port for the shutdown command. When Tomcat receives the command he will gracefully shut down.
If command is omitted Tomcat uses the string 'SHUTDOWN_EXECUTABLE_JAR'. If port is omitted no shutdown listener will be installed.

shutdown:
  port: 8002
  command: SHUTDOWN_SERVER

To send the shutdown command to a running Tomcat the command line parameter stop exists. The stop command tries to read the specified config file or when the config file parameter is omitted it tries to read the file config.yaml from the same directory where the jar is saved (same rules as for the start).

java -jar app.jar stop [config.yaml]

useShutdownHook

If true installs a shutdown hook that gracefully shuts down Tomcat. Disabled by default. This could be useful when you start the executable jar on the command line and stop it with Ctrl-C. If no shutdown hook is installed Ctrl-C will abruptly stop Tomcat.

useShutdownHook: true

Do not enable the shutdown hook when the program is installed as a Windows service with procrun or the shutdown port and command is used.

silent

If true sets the log level to WARN for the loggers that log information on the Tomcat start up. This prevents the usual startup information being logged. The default (false) sets the log level to INFO.

silent: true

Table of Contents

Clone this wiki locally