Version: 9.4.27.v20200227 |

Managing Jetty Base and Jetty Home
Previous | Chapter 9. Starting Jetty Home | Next

##### Contact the core Jetty developers at www.webtide.com

private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services for sponsored feature development

## Managing Jetty Base and Jetty Home

Instead of managing multiple Jetty implementations out of several different distribution locations, it is possible to maintain a separation between the binary installation of the standalone Jetty (known as `${jetty.home}`), and the customizations for your specific environment(s) (known as `${jetty.base}`). In addition to easy management of multiple server instances, is allows for quick, drop-in upgrades of Jetty. There should always only be one Jetty Home (per version of Jetty), but there can be multiple Jetty Base directories that reference it.

Jetty Base
  - Also known as the `${jetty.base}` property.
  - This is the location for your configurations and customizations to the Jetty distribution.
Jetty Home
  - Also known as the `${jetty.home}` property.
  - This is the location for the Jetty distribution binaries, default XML IoC configurations, and default module definitions.

> ### Important

> Jetty Home should always be treated as a standard of truth. All configuration modifications, changes and additions should be made in the appropriate Jetty Base directory.

Potential configuration is resolved from these 2 directory locations. When Jetty starts up in processes configuration from them as follows:

Check Jetty Base First
  If the referenced configuration exists, relative to the defined Jetty base, it is used.
Check Jetty Home Second
  If the referenced configuration exists, relative to the defined Jetty home, it is used.
Use java.io.File(String pathname) Logic
  Lastly, use the reference as a `java.io.File(String pathname)` reference, following the default resolution rules outlined by that constructor. In brief, the reference will be used as-is, be it relative (to current working directory, aka $\{user.dir}) or absolute path, or even network reference (such as on Windows and use of UNC paths).

For more details on how startup with start.jar works, see Using start.jar: Executing

### Demo-Base in the Jetty Distribution

The Jetty Distribution comes with an example `${jetty.base}` which enables the various demonstration webapps and server configurations.

    [jetty-distribution-9.4.27.v20200227]$ ls -la

    total 496
    drwxrwxr-x 11 user group   4096 Oct  8 15:23 ./
    drwxr-xr-x 14 user group   4096 Oct  8 13:04 ../
    drwxrwxr-x  2 user group   4096 Oct  8 06:54 bin/
    drwxrwxr-x  6 user group   4096 Oct  8 06:54 demo-base/
    drwxrwxr-x  2 user group   4096 Oct 11 15:14 etc/
    drwxrwxr-x 11 user group   4096 Oct  8 06:54 lib/
    -rw-rw-r--  1 user group  30012 Sep 30 19:55 license-eplv10-aslv20.html
    drwxrwxr-x  2 user group   4096 Oct  8 06:54 logs/
    drwxrwxr-x  2 user group   4096 Oct  8 06:54 modules/
    -rw-rw-r--  1 user group   6262 Sep 30 19:55 notice.html
    -rw-rw-r--  1 user group   1249 Sep 30 19:55 README.TXT
    drwxrwxr-x  2 user group   4096 Oct  8 06:54 resources/
    drwxrwxr-x  2 user group   4096 Oct  8 06:54 start.d/
    -rw-rw-r--  1 user group   1780 Sep 30 19:55 start.ini
    -rw-rw-r--  1 user group  71921 Sep 30 19:55 start.jar
    -rw-rw-r--  1 user group 336468 Sep 30 19:55 VERSION.txt
    drwxrwxr-x  2 user group   4096 Oct  8 06:54 webapps/

    [jetty-distribution-9.4.27.v20200227]$ cd demo-base
    [demo-base]$ java -jar $JETTY_HOME/start.jar

    2013-10-16 09:08:47.800:WARN::main: demo test-realm is deployed. DO NOT USE IN PRODUCTION!
    2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-9.4.27.v20200227
    2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/jetty-distribution-9.4.27.v20200227/demo-base/webapps/] at interval 1
    2013-10-16 09:08:48.072:WARN::main: async-rest webapp is deployed. DO NOT USE IN PRODUCTION!
    ...

If you want to see what the Jetty base looks like without executing Jetty, you can simply list the configuration by using the `--list-config` command.

    [demo-base]$ java -jar $JETTY_HOME/start.jar --list-config

    Java Environment:
    -----------------
     java.home=/usr/lib/jvm/jdk-7u21-x64/jre
     java.vm.vendor = Oracle Corporation
     java.vm.version = 25.92-b14
     java.vm.name = Java HotSpot(TM) 64-Bit Server VM
     java.vm.info = mixed mode
     java.runtime.name = Java(TM) SE Runtime Environment
     java.runtime.version = 1.8.0_92-b14
     java.io.tmpdir = /var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/
     user.dir = /home/user/jetty-distribution-9.4.27.v20200227
     user.language = en
     user.country = US

    Jetty Environment:
    -----------------
     jetty.home=/home/user/jetty-distribution-9.4.27.v20200227
     jetty.tag.version = master
     jetty.base=/home/user/jetty-distribution-9.4.27.v20200227/demo-base
     jetty.version=9.4.27.v20200227

     Config Search Order:
     --------------------
      <command-line>
      ${jetty.base} -> /home/user/jetty-distribution-9.4.27.v20200227/demo-base
      ${jetty.home} -> /home/user/Desktop/jetty-distribution-9.4.27.v20200227

    JVM Arguments:
    --------------
     (no jvm args specified)

    System Properties:
    ------------------
     jetty.base = /home/user/jetty-distribution-9.4.27.v20200227/demo-base
     jetty.home = /home/user/jetty-distribution-9.4.27.v20200227

    Properties:
    -----------
     demo.realm = etc/realm.properties
     https.port = 8443
     https.timeout = 30000
     jaas.login.conf = etc/login.conf
     jetty.dump.start = false
     jetty.dump.stop = false
     jetty.keymanager.password = OBF:1u2u1wml1z7s1z7a1wnl1u2g
     jetty.keystore = etc/keystore
     jetty.keystore.password = OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
     jetty.http.port = 8080
     jetty.secure.port = 8443
     jetty.truststore = etc/keystore
     jetty.truststore.password = OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
     org.eclipse.jetty.websocket.jsr356 = false
     threads.max = 200
     threads.min = 10
     threads.timeout = 60000

    Jetty Server Classpath:
    -----------------------
    Version Information on 42 entries in the classpath.
    Note: order presented here is how they would appear on the classpath.
          changes to the --module=name command line options will be reflected here.
     0:          9.4.27.v20200227 | ${jetty.home}/lib/jetty-client-9.4.27.v20200227.jar
     1:      1.4.1.v201005082020 | ${jetty.base}/lib/ext/javax.mail.glassfish-1.4.1.v201005082020.jar
     2:          9.4.27.v20200227 | ${jetty.base}/lib/ext/test-mock-resources-9.4.27.v20200227.jar
     3:                    (dir) | ${jetty.home}/resources
     4:                    3.1.0 | ${jetty.home}/lib/servlet-api-3.1.jar
     5:                  3.1.RC0 | ${jetty.home}/lib/jetty-schemas-3.1.jar
     6:          9.4.27.v20200227 | ${jetty.home}/lib/jetty-http-9.4.27.v20200227.jar
     7:          9.4.27.v20200227 | ${jetty.home}/lib/jetty-continuation-9.4.27.v20200227.jar
     8:          9.4.27.v20200227 | ${jetty.home}/lib/jetty-server-9.4.27.v20200227.jar
     9:          9.4.27.v20200227 | ${jetty.home}/lib/jetty-xml-9.4.27.v20200227.jar
    10:          9.4.27.v20200227 | ${jetty.home}/lib/jetty-util-9.4.27.v20200227.jar
    11:          9.4.27.v20200227 | ${jetty.home}/lib/jetty-io-9.4.27.v20200227.jar
    12:          9.4.27.v20200227 | ${jetty.home}/lib/jetty-jaas-9.4.27.v20200227.jar
    13:          9.4.27.v20200227 | ${jetty.home}/lib/jetty-jndi-9.4.27.v20200227.jar
    14:      1.1.0.v201105071233 | ${jetty.home}/lib/jndi/javax.activation-1.1.0.v201105071233.jar
    15:      1.4.1.v201005082020 | ${jetty.home}/lib/jndi/javax.mail.glassfish-1.4.1.v201005082020.jar
    16:                      1.3 | ${jetty.home}/lib/jndi/javax.transaction-api-1.3.jar
    17:          9.4.27.v20200227 | ${jetty.home}/lib/jetty-rewrite-9.4.27.v20200227.jar
    18:          9.4.27.v20200227 | ${jetty.home}/lib/jetty-security-9.4.27.v20200227.jar
    19:          9.4.27.v20200227 | ${jetty.home}/lib/jetty-servlet-9.4.27.v20200227.jar
    20:                    3.0.0 | ${jetty.home}/lib/jsp/javax.el-3.0.0.jar
    21:      1.2.0.v201105211821 | ${jetty.home}/lib/jsp/javax.servlet.jsp.jstl-1.2.0.v201105211821.jar
    22:                    2.3.2 | ${jetty.home}/lib/jsp/javax.servlet.jsp-2.3.2.jar
    23:                    2.3.1 | ${jetty.home}/lib/jsp/javax.servlet.jsp-api-2.3.1.jar
    24:                    2.3.3 | ${jetty.home}/lib/jsp/jetty-jsp-jdt-2.3.3.jar
    25:      1.2.0.v201112081803 | ${jetty.home}/lib/jsp/org.apache.taglibs.standard.glassfish-1.2.0.v201112081803.jar
    26:   3.8.2.v20130121-145325 | ${jetty.home}/lib/jsp/org.eclipse.jdt.core-3.8.2.v20130121.jar
    27:          9.4.27.v20200227 | ${jetty.home}/lib/jetty-plus-9.4.27.v20200227.jar
    28:          9.4.27.v20200227 | ${jetty.home}/lib/jetty-webapp-9.4.27.v20200227.jar
    29:          9.4.27.v20200227 | ${jetty.home}/lib/jetty-annotations-9.4.27.v20200227.jar
    30:                      4.1 | ${jetty.home}/lib/annotations/asm-4.1.jar
    31:                      4.1 | ${jetty.home}/lib/annotations/asm-commons-4.1.jar
    32:                      1.2 | ${jetty.home}/lib/annotations/javax.annotation-api-1.2.jar
    33:          9.4.27.v20200227 | ${jetty.home}/lib/jetty-deploy-9.4.27.v20200227.jar
    34:                      1.0 | ${jetty.home}/lib/websocket/javax.websocket-api-1.0.jar
    35:          9.4.27.v20200227 | ${jetty.home}/lib/websocket/javax-websocket-client-impl-9.4.27.v20200227.jar
    36:          9.4.27.v20200227 | ${jetty.home}/lib/websocket/javax-websocket-server-impl-9.4.27.v20200227.jar
    37:          9.4.27.v20200227 | ${jetty.home}/lib/websocket/websocket-api-9.4.27.v20200227.jar
    38:          9.4.27.v20200227 | ${jetty.home}/lib/websocket/websocket-client-9.4.27.v20200227.jar
    39:          9.4.27.v20200227 | ${jetty.home}/lib/websocket/websocket-common-9.4.27.v20200227.jar
    40:          9.4.27.v20200227 | ${jetty.home}/lib/websocket/websocket-server-9.4.27.v20200227.jar
    41:          9.4.27.v20200227 | ${jetty.home}/lib/websocket/websocket-servlet-9.4.27.v20200227.jar

    Jetty Active XMLs:
    ------------------
     ${jetty.home}/etc/jetty.xml
     ${jetty.home}/etc/jetty-webapp.xml
     ${jetty.home}/etc/jetty-plus.xml
     ${jetty.home}/etc/jetty-annotations.xml
     ${jetty.home}/etc/jetty-deploy.xml
     ${jetty.home}/etc/jetty-http.xml
     ${jetty.home}/etc/jetty-ssl.xml
     ${jetty.home}/etc/jetty-ssl-context.xml
     ${jetty.home}/etc/jetty-https.xml
     ${jetty.home}/etc/jetty-jaas.xml
     ${jetty.home}/etc/jetty-rewrite.xml
     ${jetty.base}/etc/demo-rewrite-rules.xml
     ${jetty.base}/etc/test-realm.xml

The `--list-config` command line option displays what the configuration will look like when starting Jetty. This includes information on the Java environment to the system properties, the classpath and the Active Jetty IoC XML used to build up the Jetty server configuration.

Of note, is that the output will make it known where the configuration elements came from, be it in either in `${jetty.home}` or `${jetty.base}`.

If you look at the `${jetty.base}/start.ini` you will see a layout similar to below.

    [my-base]$ cat start.ini

    # Enable security via jaas, and configure it
    --module=jaas
    jaas.login.conf=etc/login.conf

    # Enable rewrite examples
    --module=rewrite
    etc/demo-rewrite-rules.xml

    # Websocket chat examples needs websocket enabled
    # Don't start for all contexts (set to true in test.xml context)
    org.eclipse.jetty.websocket.jsr356=false
    --module=websocket

    # Create and configure the test realm
    etc/test-realm.xml
    demo.realm=etc/realm.properties

    # Initialize module server
    --module=server
    threads.min=10
    threads.max=200
    threads.timeout=60000
    jetty.dump.start=false
    jetty.dump.stop=false

    --module=deploy
    --module=jsp
    --module=ext
    --module=resources
    --module=client
    --module=annotations

In this example, `${jetty.base}/start.ini` is the main startup configuration entry point for Jetty. You will see that we are enabling a few modules for Jetty, specifying some properties, and also referencing some Jetty IoC XML files (namely the `etc/demo-rewrite-rules.xml` and `etc/test-realm.xml` files)

When Jetty’s `start.jar` resolves the entries in the `start.ini`, it will follow the resolution rules above.

For example, the reference to `etc/demo-rewrite-rules.xml` was found in `${jetty.base}/etc/demo-rewrite-rules.xml`.

### Declaring Jetty Base

The Jetty distribution’s `start.jar` is the component that manages the behavior of this separation.

The Jetty `start.jar` and XML files always assume that both `${jetty.home}` and `${jetty.base}` are defined when starting Jetty.

You can opt to manually define the `${jetty.home}` and `${jetty.base}` directories, such as this:

    [jetty-distribution-9.4.27.v20200227]$ pwd
    /home/user/jetty-distribution-9.4.27.v20200227

    [jetty-distribution-9.4.27.v20200227]$ java -jar start.jar \
        jetty.home=/home/user/jetty-distribution-9.4.27.v20200227 \
        jetty.base=/home/user/my-base

    2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-9.4.27.v20200227
    2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
    ...

Alternately, you can declare one directory and let the other one be discovered.

The following example uses default discovery of `${jetty.home}` by using the parent directory of wherever `start.jar` itself is, and a manual declaration of `${jetty.base}`.

    [jetty-distribution-9.4.27.v20200227]$ pwd
    /home/user/jetty-distribution-9.4.27.v20200227

    [jetty-distribution-9.4.27.v20200227]$ java -jar start.jar jetty.base=/home/user/my-base

    2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-9.4.27.v20200227
    2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
    ...

But Jetty recommends that you always start Jetty from the directory that is your `${jetty.base}` and starting Jetty by referencing the `start.jar` in your `{$jetty.home}` remotely.

The following demonstrates this by allowing default discovery of `${jetty.home}` via locating the `start.jar`, and using the `user.dir` System Property for `${jetty.base}`.

    [jetty-distribution-9.4.27.v20200227]$ pwd
    /home/user/jetty-distribution-9.4.27.v20200227

    [jetty-distribution-9.4.27.v20200227]$ cd /home/user/my-base
    [my-base]$ java -jar /home/user/jetty-distribution-9.4.27.v20200227/start.jar

    2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-9.4.27.v20200227
    2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
    ...

> ### Important

> Be aware of the `user.dir` system property, as it can only be safely set when the JVM starts and many 3rd party libraries (especially logging) use this system property. It is strongly recommended that you sit in the directory that is your desired `${jetty.base}` when starting Jetty to have consistent behavior and use of the `user.dir` system property.

Previous | Top | Next
Using start.jar | Home | Managing Server Classpath

See an error or something missing? Contribute to this documentation at Github!(Generated: 2020-02-27)