//  ========================================================================
//  Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
//  ========================================================================
//  All rights reserved. This program and the accompanying materials
//  are made available under the terms of the Eclipse Public License v1.0
//  and Apache License v2.0 which accompanies this distribution.
//
//      The Eclipse Public License is available at
//      http://www.eclipse.org/legal/epl-v10.html
//
//      The Apache License v2.0 is available at
//      http://www.opensource.org/licenses/apache2.0.php
//
//  You may elect to redistribute this code under either of these licenses.
//  ========================================================================

[[startup-overview]]
=== 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 just a collection of java 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.
Modules::
  Instead of explicitly listing all the libraries, properties and XML
  files for a feature, the `start.jar` mechanism allows you to create
  modules. You define a module 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 many `--lib=location`, feature.xml,
  name=value arguments for a feature and all its dependencies. Modules
  also use their dependencies to control the ordering of libraries and
  XML files.
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:

[source, screen, subs="{sub-order}"]
....
[user]$ cd jetty-distribution-{VERSION}
[jetty-distribution-{VERSION}]$ 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:

[source, screen, subs="{sub-order}"]
....
[jetty-distribution-{VERSION}]$ 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:

[source, screen, subs="{sub-order}"]
....
[jetty-distribution-{VERSION}]$ 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 t0 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:

[source, screen, subs="{sub-order}"]
....
[jetty-distribution-{VERSION}]$ 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-{VERSION}
 jetty.base=/opt/jetty/jetty-distribution-{VERSION}
 jetty.version={VERSION}

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

System Properties:
------------------
 jetty.home = /opt/jetty/jetty-distribution-{VERSION}
 jetty.base = /opt/jetty/jetty-distribution-{VERSION}

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:               {VERSION} | ${jetty.home}/lib/jetty-http-{VERSION}.jar
 3:               {VERSION} | ${jetty.home}/lib/jetty-server-{VERSION}.jar
 4:               {VERSION} | ${jetty.home}/lib/jetty-xml-{VERSION}.jar
 5:               {VERSION} | ${jetty.home}/lib/jetty-util-{VERSION}.jar
 6:               {VERSION} | ${jetty.home}/lib/jetty-io-{VERSION}.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.

[source, screen, subs="{sub-order}"]
....
[user]$ cd jetty-distribution-{VERSION}
[jetty-distribution-{VERSION}]$ echo jetty.http.port=8080 > /tmp/jetty.properties
[jetty-distribution-{VERSION}]$ export JETTY_HOME=`pwd`
[jetty-distribution-{VERSION}]$ export JETTY_BASE=`pwd`
[jetty-distribution-{VERSION}]$ export JETTY_VERSION="${project.version}"
[jetty-distribution-{VERSION}]$ 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:

[source, screen, subs="{sub-order}"]
....
[user]$ cd jetty-distribution-{VERSION}
[jetty-distribution-{VERSION}]$ 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:

[source, screen, subs="{sub-order}"]
....
[example-base]$ java -jar $JETTY_HOME/start.jar
....
