Version: 9.3.16.v20170120 |

Chapter 9. Starting Jetty
Previous | Part III. Jetty Administration Guide 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

## Chapter 9. Starting Jetty

## Startup Overview

The `start.jar` bootstrap manages the startup of standalone Jetty. It is responsible for:

Building the classpath
  The `start.jar` bootstrap builds a classpath for all the required Jetty features and their dependencies. It builds the classpath using either the `--lib` option to `start.jar` to add an individual classpath entry, or with the `--module` option that includes all the libs and their dependencies for a module (a named Jetty feature).
Instantiating the Server Components
  The server and its components are instantiated using either Jetty IoC XML or Spring. The Jetty server is a collection of POJOs for the server, connectors, session managers and others. These are instantiated, injected, and wired up together in XML files, commonly one per module/feature, that are passed as arguments to `start.jar`.
Resolving Server Filesystem Locations
  The `start.jar` mechanism resolves canonical locations for the `${jetty.home}` and the `${jetty.base}` directories. The `${jetty.home}` directory is the location of the standard distribution of Jetty. The `${jetty.base}` directory is the location of the local server customization and configurations. + If you want to modify the Jetty distribution, base and home can be the same directory. Separating the base and home directories allows the distribution to remain unmodified, with all customizations in the base directory, and thus simplifies subsequent server version upgrades.
Parameterizing the Server Configuration
  XML files primarily determine the server configuration. Many of these files are parameterized to allow simple injection of host names, ports, passwords and more. The `start.jar` mechanism allows you to set parameters on the command line or in properties files.

To achieve these start up mechanisms, the `start.jar` uses:

Command line arguments
  You can configure the entire server with command line arguments that specify libraries, properties and XML files. However in practice the INI and modules mechanisms (below) reduce the verbosity of the command line.
INI files
  The `start.jar` mechanism uses the contents of the `${jetty.base}/start.ini` and `${jetty.base}/start.d/*.ini` files with each line equivalent to a `start.jar` command line argument. This means that either a global `start.ini` file or multiple `start.d/feature.ini` files control the configuration of the server.

### Note

It is important to chose either `${jetty.base}/start.ini` or `${jetty.base}/start.d/*.ini` to manage configuration. Using both is not recommended and can lead to issues with your server.

Modules
  Instead of explicitly listing all the libraries, properties and XML files for a feature, the `start.jar` mechanism allows you to create modules. A module is defined in a `modules/*.mod` file, including the libraries, dependencies, XML, and template INI files for a Jetty feature. Thus you can use a single `--module=name` command line option as the equivalent of specifying `--lib=location`, `feature.xml` or `name=value` arguments for a feature and all its dependencies. Modules also use their dependencies to control the ordering of libraries and XML files. There are several module files included with the Jetty distribution that cover the most common server features, such as HTTP, HTTPS, SSL, Logging, Annotations…​etc. These module files should only be edited if you are making structural changes to the way the feature will perform. For more information, refer to the section on managing startup modules later in this chapter.
XML Files
  XML files in either Jetty IoC or Spring format instantiate the actual POJO components of the server. This includes all major components such as connectors, keystores, session managers, and data sources. Typically there are one or more XML files per module, and these are defined and activated in the corresponding module.

### Startup Example

The simplest way to start Jetty is via the `start.jar` mechanism using the following Java command line:

    [user]$ cd jetty-distribution-9.3.16.v20170120
    [jetty-distribution-9.3.16.v20170120]$ java -jar start.jar --module=http jetty.http.port=8080

This command uses the `start.jar` mechanism to bootstrap the classpath, properties, and XML files with the metadata obtained from the `http` module. Specifically the `http` module is defined in the `${jetty.home}/modules/http.mod` file, and includes the following:

    [jetty-distribution-9.3.16.v20170120]$ cat modules/http.mod
    [depend]
    server

    [xml]
    etc/jetty-http.xml

    [ini-template]
    jetty.http.port=8080
    http.timeout=30000

The `http` module declares that `http` depends on the server module, uses the `jetty-http.xml` file, and can be parameterized with `jetty.http.port` and `http.timeout` parameters. The INI-template section is not actually used by the command above, so the `jetty.http.port` must still be defined on the command line.

Following the server dependency, the `${jetty.home}/modules/server.mod` file includes:

    [jetty-distribution-9.3.16.v20170120]$ cat modules/server.mod
    [lib]
    lib/servlet-api-3.1.jar
    lib/jetty-http-${jetty.version}.jar
    lib/jetty-server-${jetty.version}.jar
    lib/jetty-xml-${jetty.version}.jar
    lib/jetty-util-${jetty.version}.jar
    lib/jetty-io-${jetty.version}.jar

    [xml]
    etc/jetty.xml

    [ini-template]
    threads.min=10
    threads.max=200

The `server` module declares the libraries the server needs and to use `jetty.xml` file. The combined metadata of the `http` and `server` modules results in `start.jar` generating the effective Java command line required to start Jetty.

Another way to see this is by asking Jetty what its configuration looks like by appending --list-config to the command line:

    [jetty-distribution-9.3.16.v20170120]$ java -jar start.jar --module=http jetty.http.port=9099 --list-config

    Java Environment:
    -----------------
     java.home=/user/lib/jvm/jdk-7u21-x64/jre
     java.vm.vendor=Oracle Corporation
     java.vm.version=23.25-b01
     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.7.0_25-b15
     java.io.tmpdir=/tmp

    Jetty Environment:
    -----------------
     jetty.home=/opt/jetty/jetty-distribution-9.3.16.v20170120
     jetty.base=/opt/jetty/jetty-distribution-9.3.16.v20170120
     jetty.version=9.3.16.v20170120

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

    System Properties:
    ------------------
     jetty.home = /opt/jetty/jetty-distribution-9.3.16.v20170120
     jetty.base = /opt/jetty/jetty-distribution-9.3.16.v20170120

    Properties:
    -----------
     jetty.http.port = 9099

    Jetty Server Classpath:
    -----------------------
    Version Information on 7 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:                    3.1.0 | ${jetty.home}/lib/servlet-api-3.1.jar
     1:                  3.1.RC0 | ${jetty.home}/lib/jetty-schemas-3.1.jar
     2:               9.3.16.v20170120 | ${jetty.home}/lib/jetty-http-9.3.16.v20170120.jar
     3:               9.3.16.v20170120 | ${jetty.home}/lib/jetty-server-9.3.16.v20170120.jar
     4:               9.3.16.v20170120 | ${jetty.home}/lib/jetty-xml-9.3.16.v20170120.jar
     5:               9.3.16.v20170120 | ${jetty.home}/lib/jetty-util-9.3.16.v20170120.jar
     6:               9.3.16.v20170120 | ${jetty.home}/lib/jetty-io-9.3.16.v20170120.jar

    Jetty Active XMLs:
    ------------------
     ${jetty.home}/etc/jetty.xml
     ${jetty.home}/etc/jetty-http.xml

This represents the entirety of the configuration that is applied to start Jetty.

If you don’t want to use the `start.jar` bootstrap, you can start Jetty using a traditional Java command line.

The following is the equivalent Java command line for what the `start.jar` bootstrap above performs.

    [user]$ cd jetty-distribution-9.3.16.v20170120
    [jetty-distribution-9.3.16.v20170120]$ echo jetty.http.port=8080 > /tmp/jetty.properties
    [jetty-distribution-9.3.16.v20170120]$ export JETTY_HOME=`pwd`
    [jetty-distribution-9.3.16.v20170120]$ export JETTY_BASE=`pwd`
    [jetty-distribution-9.3.16.v20170120]$ export JETTY_VERSION="${project.version}"
    [jetty-distribution-9.3.16.v20170120]$ java -Djetty.home=$JETTY_HOME \
    -Djetty.base=$JETTY_BASE \
    -cp \
     $JETTY_HOME/lib/servlet-api-3.1.jar\
    :$JETTY_HOME/lib/jetty-schemas-3.1.jar\
    :$JETTY_HOME/lib/jetty-http-$JETTY_VERSION.jar\
    :$JETTY_HOME/lib/jetty-server-$JETTY_VERSION.jar \
    :$JETTY_HOME/lib/jetty-xml-$JETTY_VERSION.jar\
    :$JETTY_HOME/lib/jetty-util-$JETTY_VERSION.jar\
    :$JETTY_HOME/lib/jetty-io-$JETTY_VERSION.jar\
    org.eclipse.jetty.xml.XmlConfiguration \
    /tmp/jetty.properties \
    $JETTY_HOME/etc/jetty.xml \
    $JETTY_HOME/etc/jetty-http.xml

The Java command line sets up the classpath with the core Jetty jars and the servlet API, executes the XmlConfiguration class and passes it some XML files that define the server and an HTTP connector running on the port defined in the `jetty.properties` file.

You can further simplify the startup of this server by using the INI template defined by the modules to create a `start.ini` file with the command:

    [user]$ cd jetty-distribution-9.3.16.v20170120
    [jetty-distribution-9.3.16.v20170120]$ mkdir example-base
    [example-base]$ cd example-base
    [example-base]$ ls -la
    total 8
    drwxrwxr-x  2 user webgroup 4096 Oct  4 11:49 ./
    drwxrwxr-x 12 user webgroup 4096 Oct  4 11:49 ../

    [example-base]$ java -jar $JETTY_HOME/start.jar --add-to-start=http

    WARNING: http            initialised in ${jetty.base}/start.ini (appended)
    WARNING: http            enabled in     ${jetty.base}/start.ini
    WARNING: server          initialised in ${jetty.base}/start.ini (appended)
    WARNING: server          enabled in     ${jetty.base}/start.ini

    [example-base]$ ls -la
    total 12
    drwxrwxr-x  2 user webgroup 4096 Oct  4 11:55 ./
    drwxrwxr-x 12 user webgroup 4096 Oct  4 11:49 ../
    -rw-rw-r--  1 user webgroup  250 Oct  4 11:55 start.ini

Once complete, you can edit the `start.ini` file to modify any parameters and you can run the server with the simple command:

    [example-base]$ java -jar $JETTY_HOME/start.jar

Previous | Top | Next
Part III. Jetty Administration Guide | Home | Using start.jar

See an error or something missing? Contribute to this documentation at Github!(Generated: 2017-01-20)