Version: 9.4.7.v20170914 |

Running Jetty
Previous | Chapter 2. Using 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

## Running Jetty

To start Jetty on the default port of 8080, run the following command:

    > cd $JETTY_HOME
    > java -jar start.jar

    2015-06-04 10:50:44.806:INFO::main: Logging initialized @334ms
    2015-06-04 10:50:44.858:WARN:oejs.HomeBaseWarning:main: This instance of Jetty is not running from a separate {jetty.base} directory, this is not recommended.  See documentation at http://www.eclipse.org/jetty/documentation/current/startup.html
    2015-06-04 10:50:44.995:INFO:oejs.Server:main: jetty-9.3.0.v20150601
    2015-06-04 10:50:45.012:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:///opt/jetty-distribution-9.3.0.v20150601/webapps/] at interval 1
    2015-06-04 10:50:45.030:INFO:oejs.ServerConnector:main: Started ServerConnector@19dfb72a{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
    2015-06-04 10:50:45.030:INFO:oejs.Server:main: Started @558ms

You can point a browser at this server at http://localhost:8080. However, as there are no webapps deployed in the `$JETTY_HOME` directory, you will see a 404 error page served by Jetty. Note the HomeBase warning - it is not recommended to run Jetty from the `$JETTY_HOME` directory. Instead, see how to create a Jetty Base below.

> ### Note

> You will see examples throughout the documentation referencing `$JETTY_HOME` and `$JETTY_BASE` as well as `{jetty.home}` and `{jetty.base}`. These terms are used to refer to the location of your Jetty installation directories. Many users find it helpful to define `$JETTY_HOME` as an environment variable that maps to their Jetty distribution directory. More information can be found in our Administration section on managing Jetty Home and Jetty Base.

### Demo Base

Within the standard Jetty distribution there is the `demo-base` directory, which demonstrates the recommended way to run a Jetty base in a directory separate from `$JETTY_HOME`:

    > cd $JETTY_HOME/demo-base/
    > java -jar $JETTY_HOME/start.jar

    2017-08-16 16:55:15.571:INFO::main: Logging initialized @521ms to org.eclipse.jetty.util.log.StdErrLog
    2017-08-16 16:55:15.907:WARN::main: demo test-realm is deployed. DO NOT USE IN PRODUCTION!
    2017-08-16 16:55:15.910:INFO:oejs.Server:main: jetty-9.4.7-SNAPSHOT
    2017-08-16 16:55:15.931:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:///tmp/jetty-distribution-9.4.7-SNAPSHOT/demo-base/webapps/] at interval 1
    2017-08-16 16:55:16.151:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=50ms
    2017-08-16 16:55:16.369:INFO:oejs.session:main: DefaultSessionIdManager workerName=node0
    2017-08-16 16:55:16.369:INFO:oejs.session:main: No SessionScavenger set, using defaults
    2017-08-16 16:55:16.370:INFO:oejs.session:main: Scavenging every 660000ms
    2017-08-16 16:55:16.416:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@7113b13f{/,file:///tmp/jetty-distribution-9.4.7-SNAPSHOT/demo-base/webapps/ROOT/,AVAILABLE}{/ROOT}
    2017-08-16 16:55:16.625:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=82ms
    2017-08-16 16:55:16.631:WARN::main: test webapp is deployed. DO NOT USE IN PRODUCTION!
    2017-08-16 16:55:16.751:INFO:oejsh.ManagedAttributeListener:main: update PushFilter null->org.eclipse.jetty.servlets.PushCacheFilter@1a677343 on o.e.j.w.WebAppContext@2d7275fc{/test,file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-test.war-_test-any-7157753932050220016.dir/webapp/,STARTING}{/test.war}
    2017-08-16 16:55:16.757:INFO:oejsh.ManagedAttributeListener:main: update QoSFilter null->org.eclipse.jetty.servlets.QoSFilter@79079097 on o.e.j.w.WebAppContext@2d7275fc{/test,file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-test.war-_test-any-7157753932050220016.dir/webapp/,STARTING}{/test.war}
    2017-08-16 16:55:16.760:WARN:oeju.DeprecationWarning:main: Using @Deprecated Class org.eclipse.jetty.servlets.MultiPartFilter
    2017-08-16 16:55:16.809:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@2d7275fc{/test,file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-test.war-_test-any-7157753932050220016.dir/webapp/,AVAILABLE}{/test.war}
    2017-08-16 16:55:16.816:INFO:oejsh.ContextHandler:main: Started o.e.j.s.h.MovedContextHandler@7c9d8e2{/oldContextPath,null,AVAILABLE}
    2017-08-16 16:55:16.854:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=23ms
    2017-08-16 16:55:16.891:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@69453e37{/doc,file:///tmp/jetty-distribution-9.4.7-SNAPSHOT/demo-base/webapps/doc/,AVAILABLE}{/doc}
    2017-08-16 16:55:16.942:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=25ms
    2017-08-16 16:55:16.945:WARN::main: test-jaas webapp is deployed. DO NOT USE IN PRODUCTION!
    2017-08-16 16:55:16.983:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@4e3958e7{/test-jaas,file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-test-jaas.war-_test-jaas-any-6953571893682159674.dir/webapp/,AVAILABLE}{/test-jaas.war}
    2017-08-16 16:55:17.106:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=21ms
    2017-08-16 16:55:17.109:WARN::main: test-jndi webapp is deployed. DO NOT USE IN PRODUCTION!
    2017-08-16 16:55:17.192:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@1d8bd0de{/test-jndi,file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-test-jndi.war-_test-jndi-any-1246461885510956986.dir/webapp/,AVAILABLE}{/test-jndi.war}
    2017-08-16 16:55:17.307:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=53ms
    2017-08-16 16:55:17.310:WARN::main: test-spec webapp is deployed. DO NOT USE IN PRODUCTION!
    2017-08-16 16:55:17.388:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@51dcb805{/test-spec,[file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-test-spec.war-_test-spec-any-3750193079644252256.dir/webapp/, jar:file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-test-spec.war-_test-spec-any-3750193079644252256.dir/webapp/WEB-INF/lib/test-web-fragment-9.4.7-SNAPSHOT.jar!/META-INF/resources],AVAILABLE}{/test-spec.war}
    2017-08-16 16:55:17.490:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=53ms
    2017-08-16 16:55:17.493:WARN::main: async-rest webapp is deployed. DO NOT USE IN PRODUCTION!
    2017-08-16 16:55:17.516:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@1de76cc7{/async-rest,[file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-async-rest.war-_async-rest-any-8972552397332323832.dir/webapp/, jar:file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-async-rest.war-_async-rest-any-8972552397332323832.dir/webapp/WEB-INF/lib/example-async-rest-jar-9.4.7-SNAPSHOT.jar!/META-INF/resources],AVAILABLE}{/async-rest.war}
    2017-08-16 16:55:17.643:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=83ms
    2017-08-16 16:55:17.921:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@242b836{/proxy,file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-javadoc-proxy.war-_javadoc-proxy-any-4521643038409884891.dir/webapp/,AVAILABLE}{/javadoc-proxy.war}
    2017-08-16 16:55:17.936:INFO:oejs.AbstractConnector:main: Started ServerConnector@6f15d60e{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
    2017-08-16 16:55:17.944:INFO:oejus.SslContextFactory:main: x509=X509@58e1d9d(jetty,h=[jetty.eclipse.org],w=[]) for SslContextFactory@446a1e84(file:///tmp/jetty-distribution-9.4.7-SNAPSHOT/demo-base/etc/keystore,file:///tmp/jetty-distribution-9.4.7-SNAPSHOT/demo-base/etc/keystore)
    2017-08-16 16:55:17.944:INFO:oejus.SslContextFactory:main: x509=X509@4f0f2942(mykey,h=[],w=[]) for SslContextFactory@446a1e84(file:///tmp/jetty-distribution-9.4.7-SNAPSHOT/demo-base/etc/keystore,file:///tmp/jetty-distribution-9.4.7-SNAPSHOT/demo-base/etc/keystore)
    2017-08-16 16:55:18.071:INFO:oejs.AbstractConnector:main: Started ServerConnector@41488b16{SSL,[ssl, http/1.1]}{0.0.0.0:8443}
    2017-08-16 16:55:18.072:INFO:oejs.Server:main: Started @3022ms

You can visit this demo server by pointing a browser at http://localhost:8080, which will now show a welcome page and several demo/test web applications.

> ### Warning

> The demonstration web applications are not necessarily secure and should not be deployed in production web servers.

You can see the configuration of the demo-base by using the following commands:

    > cd $JETTY_HOME/demo-base/
    > java -jar $JETTY_HOME/start.jar --list-modules
    ...

    > java -jar %JETTY_HOME/start.jar --list-config
    ...

The `--list-modules` command will return a complete list of available and enabled modules for the server. It will also display the location of the modules, how and in what order they are implemented, dependent modules, and associated jar files.

The `--list-config` command displays a trove of information about the server including the Java and Jetty environments, the configuration order, any JVM arguments or System Properties set, general server properties, a full listing of the Jetty server class path, and active Jetty XML files.

### Creating a new Jetty Base

The `demo-base` directory described above is an example of the `jetty.base` mechanism. A Jetty base directory allows the configuration and web applications of a server instance to be stored separately from the Jetty distribution, so that upgrades can be done with minimal disruption. Jetty’s default configuration is based on two properties:

jetty.home
  The property that defines the location of the Jetty distribution, its libs, default modules and default XML files (typically start.jar, lib, etc).
jetty.base
  The property that defines the location of a specific implementation of a Jetty server, its configuration, logs and web applications (typically start.d/*.ini files, logs and webapps).

> ### Important

> Your Jetty Home directory should be treated as a standard of truth and remain unmodified or changed. Changes or additions to your configuration should take place in the Jetty Base directory.

The `jetty.home` and `jetty.base` properties may be explicitly set on the command line, or they can be inferred from the environment if used with commands like:

    > cd $JETTY_BASE
    > java -jar $JETTY_HOME/start.jar

The following commands create a new base directory, enables both the HTTP connector and the web application deployer modules, and copies a demo webapp to be deployed:

    > JETTY_BASE=/tmp/mybase
    > mkdir $JETTY_BASE
    > cd $JETTY_BASE
    > java -jar $JETTY_HOME/start.jar

    WARNING: Nothing to start, exiting ...

    Usage: java -jar start.jar [options] [properties] [configs]
           java -jar start.jar --help  # for more information

    > java -jar $JETTY_HOME/start.jar --create-startd
    INFO : Base directory was modified
    > java -jar $JETTY_HOME/start.jar --add-to-start=http,deploy

    INFO: server          initialised (transitively) in ${jetty.base}/start.d/server.ini
    INFO: http            initialised in ${jetty.base}/start.d/http.ini
    INFO: security        initialised (transitively) in ${jetty.base}/start.d/security.ini
    INFO: servlet         initialised (transitively) in ${jetty.base}/start.d/servlet.ini
    INFO: webapp          initialised (transitively) in ${jetty.base}/start.d/webapp.ini
    INFO: deploy          initialised in ${jetty.base}/start.d/deploy.ini
    MKDIR: ${jetty.base}/webapps
    INFO: Base directory was modified

    > cp $JETTY_HOME/demo-base/webapps/async-rest.war webapps/ROOT.war
    > java -jar $JETTY_HOME/start.jar

    2015-06-04 11:10:16.286:INFO::main: Logging initialized @274ms
    2015-06-04 11:10:16.440:INFO:oejs.Server:main: jetty-9.3.0.v20150601
    2015-06-04 11:10:16.460:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:///tmp/mybase/webapps/] at interval 1
    2015-06-04 11:10:16.581:WARN::main: async-rest webapp is deployed. DO NOT USE IN PRODUCTION!
    2015-06-04 11:10:16.589:INFO:oejw.StandardDescriptorProcessor:main: NO JSP Support for /, did not find org.eclipse.jetty.jsp.JettyJspServlet
    2015-06-04 11:10:16.628:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@1a407d53{/,[file:///tmp/jetty-0.0.0.0-8080-ROOT.war-_-any-4510228025526425427.dir/webapp/, jar:file:///tmp/jetty-0.0.0.0-8080-ROOT.war-_-any-4510228025526425427.dir/webapp/WEB-INF/lib/example-async-rest-jar-9.3.0.v20150601.jar!/META-INF/resources],AVAILABLE}{/ROOT.war}
    2015-06-04 11:10:16.645:INFO:oejs.ServerConnector:main: Started ServerConnector@3abbfa04{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
    2015-06-04 11:10:16.646:INFO:oejs.Server:main: Started @634ms

### Changing the Jetty Port

You can configure Jetty to run on a different port by setting the `jetty.http.port` property on the command line:

    > cd $JETTY_BASE
    > java -jar $JETTY_HOME/start.jar jetty.http.port=8081
    ...

When the server starts, it will now run on port 8081. It is important to note that setting properties on the command line will only take affect for that instance of the server. To change the configuration so that the server will always start on the desired port, you will need to edit the `start.d/http.ini`

> ### Note

> The configuration by properties works via the following chain:

> - The start.d/http.ini file is part of the effective command line and contains the --module=http argument which activates the http module.
> - The modules/http.mod file defines the http module which specifies the etc/jetty-http.xml configuration file and the template ini properties it uses.
> - The jetty.http.port property is used by the Property XML element in etc/jetty.http.xml to inject the ServerConnector instance with the port.

> For more information see the Quickstart Configuration Guide and Configuring Connectors.

### Adding SSL for HTTPS & HTTP2

Building on the example above, we can activate additional modules to add support HTTPS and HTTP2 for the server. To add HTTPS and HTTP2 connectors to a Jetty configuration, the modules can be activated by the following command:

    > java -jar $JETTY_HOME/start.jar --add-to-start=https,http2

    ALERT: There are enabled module(s) with licenses.
    The following 1 module(s):
     + contains software not provided by the Eclipse Foundation!
     + contains software not covered by the Eclipse Public License!
     + has not been audited for compliance with its license

     Module: alpn-impl/alpn-8
      + ALPN is a hosted at github under the GPL v2 with ClassPath Exception.
      + ALPN replaces/modifies OpenJDK classes in the sun.security.ssl package.
      + http://github.com/jetty-project/jetty-alpn
      + http://openjdk.java.net/legal/gplv2+ce.html

    Proceed (y/N)? y
    INFO  : alpn-impl/alpn-1.8.0_92 dynamic dependency of alpn-impl/alpn-8
    INFO  : alpn            transitively enabled, ini template available with --add-to-start=alpn
    INFO  : alpn-impl/alpn-8 dynamic dependency of alpn
    INFO  : http2           initialized in ${jetty.base}/start.d/http2.ini
    INFO  : https           initialized in ${jetty.base}/start.d/https.ini
    INFO  : ssl             transitively enabled, ini template available with --add-to-start=ssl
    MKDIR : ${jetty.base}/lib/alpn
    DOWNLD: http://central.maven.org/maven2/org/mortbay/jetty/alpn/alpn-boot/8.1.8.v20160420/alpn-boot-8.1.8.v20160420.jar to ${jetty.base}/lib/alpn/alpn-boot-8.1.8.v20160420.jar
    MKDIR : ${jetty.base}/etc
    COPY  : ${jetty.home}/modules/ssl/keystore to ${jetty.base}/etc/keystore
    INFO  : Base directory was modified

    > java -jar $JETTY_HOME/start.jar
    [...]
    2017-05-22 12:48:23.271:INFO:oejs.AbstractConnector:main: Started ServerConnector@134d0064{SSL,[ssl, alpn, h2, http/1.1]}{0.0.0.0:8443}
    [...]

The `--add-to-start` command sets up the effective command line in the ini files to run an ssl connection that supports the HTTPS and HTTP2 protocols as follows:

- transitively enabled the `ssl` module that configures an SSL connector (eg port, keystore etc.) by adding `etc/jetty-ssl.xml` and `etc/jetty-ssl-context.xml` to the effective command line.
- transitively enabled the `alpn` module that configures protocol negotiation on the SSL connector by adding `etc/jetty-alpn.xml` to the effective command line.
- creates `start.d/https.ini` that configures the HTTPS protocol on the SSL connector by adding `etc/jetty-https.xml` to the effective command line.
- creates `start.d/http2.ini` that configures the HTTP/2 protocol on the SSL connector by adding `etc/jetty-http2.xml` to the effective command line.
- checks for the existence of a `etc/keystore` file and if not present, downloads a demonstration keystore file.

#### Changing the Jetty HTTPS Port

You can configure the SSL connector to run on a different port by setting the `jetty.ssl.port` property on the command line:

    > cd $JETTY_BASE
    > java -jar $JETTY_HOME/start.jar jetty.ssl.port=8444

Alternatively, property values can be added to the effective command line built from the `start.ini` file or `start.d/*.ini` files, depending on your set up. Please see the section on Start.ini vs. Start.d for more information.

### More start.jar options

The job of the `start.jar` is to interpret the command line, `start.ini` and `start.d` directory (and associated .ini files) to build a Java classpath and list of properties and configuration files to pass to the main class of the Jetty XML configuration mechanism. The `start.jar` mechanism has many options which are documented in the Chapter 9, Starting Jetty administration section and you can see them in summary by using the command:

    > java -jar $JETTY_HOME/start.jar --help

Previous | Top | Next
Chapter 2. Using Jetty | Home | Deploying Web Applications

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