Version: 9.4.7.v20170914 |

Startup a Unix Service using jetty.sh
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

## Startup a Unix Service using jetty.sh

The standalone Jetty distribution ships with a `bin/jetty.sh` script that can be used by various Unix distros (including OSX) to manage Jetty as a startup service.

This script is suitable for setting up Jetty as a service in Unix.

### Quick-Start a Jetty Service

The minimum steps to get Jetty to run as a Service include:

    [/opt/jetty]# tar -zxf /home/user/downloads/jetty-distribution-9.4.7.v20170914.tar.gz
    [/opt/jetty]# cd jetty-distribution-9.4.7.v20170914/
    [/opt/jetty/jetty-distribution-9.4.7.v20170914]# ls
    bin        lib                         modules      resources  start.jar
    demo-base  license-eplv10-aslv20.html  notice.html  start.d    VERSION.txt
    etc        logs                        README.TXT   start.ini  webapps

    [/opt/jetty/jetty-distribution-9.4.7.v20170914]# cp bin/jetty.sh /etc/init.d/jetty
    [/opt/jetty/jetty-distribution-9.4.7.v20170914]# echo JETTY_HOME=`pwd` > /etc/default/jetty
    [/opt/jetty/jetty-distribution-9.4.7.v20170914]# cat /etc/default/jetty
    JETTY_HOME=/opt/jetty/jetty-distribution-9.4.7.v20170914

    [/opt/jetty/jetty-distribution-9.4.7.v20170914]# service jetty start
    Starting Jetty: OK Wed Nov 20 10:26:53 MST 2013

From this demonstration we can see that Jetty started successfully as a Unix Service from the `/opt/jetty/jetty-distribution-{VERSION}` directory.

This configuration works well but it is running Jetty as the root user.

### Practical Setup of a Jetty Service

There are various ways this can be accomplished, mostly depending on your Unix environment (and possibly corporate policies).

The techniques outlined here assume an installation on Linux (demonstrated on Ubuntu 12.04.3 LTS).

Prepare some empty directories to work with.

    # mkdir -p /opt/jetty
    # mkdir -p /opt/web/mybase
    # mkdir -p /opt/jetty/temp

The directory purposes are as follows:

/opt/jetty
  Where the Jetty Distribution will be unpacked into
/opt/web/mybase
  Where your specific set of webapps will be located, including all of the configuration required of the server to make them operational.
/opt/jetty/temp

  This is the temporary directory assigned to Java by the Service Layer (this is what Java sees as the `java.io.tmpdir` System Property).

  This is intentionally kept separate from the standard temp directory of `/tmp`, as this location doubles as the Servlet Spec work directory. It is our experience that the standard temp directory is often managed by various cleanup scripts that wreak havoc on a long running Jetty server.

Jetty 9.3 requires Java 8 (or greater) to run. Make sure you have it installed.

    # apt-get install openjdk-7-jdk

Or download Java 7 from: http://www.oracle.com/technetwork/java/javase/downloads/index.html

    # java -version
    java version "1.6.0_27"
    OpenJDK Runtime Environment (IcedTea6 1.12.6) (6b27-1.12.6-1ubuntu0.12.04.2)
    OpenJDK 64-Bit Server VM (build 20.0-b12, mixed mode)

    # update-alternatives --list java
    /usr/lib/jvm/java-6-openjdk-amd64/jre/bin/java
    /usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java

    # update-alternatives --config java
    There are 2 choices for the alternative java (providing /usr/bin/java).

      Selection    Path                                            Priority   Status
    ------------------------------------------------------------
    * 0            /usr/lib/jvm/java-6-openjdk-amd64/jre/bin/java   1061      auto mode
      1            /usr/lib/jvm/java-6-openjdk-amd64/jre/bin/java   1061      manual mode
      2            /usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java   1051      manual mode

    Press enter to keep the current choice[*], or type selection number: 2
    update-alternatives: using /usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java to provide /usr/bin/java (java) in manual mode.

    # java -version
    java version "1.7.0_25"
    OpenJDK Runtime Environment (IcedTea 2.3.10) (7u25-2.3.10-1ubuntu0.12.04.2)
    OpenJDK 64-Bit Server VM (build 23.7-b01, mixed mode)

It is recommended that you create a user to specifically run Jetty. This user should have the minimum set of privileges needed to run Jetty.

    # useradd --user-group --shell /bin/false --home-dir /opt/jetty/temp jetty

This will create a user called `jetty`, belonging to the group called `jetty`, with no shell access (aka `/bin/false`), and home directory at `/opt/jetty/temp`.

Download a copy of the Jetty distribution from the Official Eclipse Download Site

Unpack it into place.

    [/opt/jetty]# tar -zxf /home/user/Downloads/jetty-distribution-9.4.7.v20170914.tar.gz
    [/opt/jetty]# ls -F
    jetty-distribution-9.4.7.v20170914/
    [/opt/jetty]# mkdir /opt/jetty/temp

It might seem strange or undesirable to unpack the first portion of the jetty-distribution directory name too. But starting with Jetty 9 the split between `${jetty.home}` and `${jetty.base}` allows for easier upgrades of Jetty itself while isolating your webapp specific configuration. For more information on the Jetty home and base concepts see the section on managing a Jetty installation earlier in this Chapter.

The `/opt/jetty/temp` directory is created as a durable place for Jetty to use for temp and working directories. Many Unix systems will periodically clean out the /tmp directory, this behavior is undesired in a Servlet container and has been known to cause problems. This durable directory at `/opt/jetty/temp` solves for that behavior.

The directory at `/opt/web/mybase` is going to be a `${jetty.base}`, so lets configure it to hold your webapp and its configuration.

### Tip

In past versions of Jetty, you would configure / modify / add to the `jetty-distribution` directory directly. While this is still supported, we encourage you to setup a proper `${jetty.base}` directory, as it will benefit you with easier `jetty-distribution` upgrades in the future.

    # cd /opt/web/mybase/
    [/opt/web/mybase]# ls
    [/opt/web/mybase]# java -jar /opt/jetty/jetty-distribution-9.4.7.v20170914/start.jar \
       --add-to-start=deploy,http,console-capture
       INFO  : webapp          transitively enabled, ini template available with --add-to-start=webapp
       INFO  : server          transitively enabled, ini template available with --add-to-start=server
       INFO  : security        transitively enabled
       INFO  : servlet         transitively enabled
       INFO  : console-capture initialized in ${jetty.base}/start.ini
       INFO  : http            initialized in ${jetty.base}/start.ini
       INFO  : deploy          initialized in ${jetty.base}/start.ini
       MKDIR : ${jetty.base}/logs
       MKDIR : ${jetty.base}/webapps
       INFO  : Base directory was modified
    [/opt/web/mybase]# ls -F
    start.ini  webapps/

At this point you have configured your `/opt/web/mybase` to enable the following modules:

deploy
  This is the module that will perform deployment of web applications (WAR files or exploded directories), or Jetty IoC XML context deployables, from the `/opt/web/mybase/webapps` directory.
http

  This sets up a single Connector that listens for basic HTTP requests.

  See the created `start.ini` for configuring this connector.

console-capture
  When running Jetty as a service it is very important to have logging enabled. This module will enable the basic STDOUT and STDERR capture logging to the `/opt/web/mybase/logs/` directory.

Additionally, the `webapp`, `server`, `security` and `servlet` modules were enabled as they are dependencies for other modules.

See Using start.jar for more details and options on setting up and configuring a `${jetty.base}` directory.

Copy your war file into place.

    # cp /home/user/projects/mywebsite.war /opt/web/mybase/webapps/

Most service installations will want Jetty to run on port 80, now is the opportunity to change this from the default value of `8080` to `80`.

Edit the `/opt/web/mybase/start.ini` and change the `jetty.http.port` value.

    # grep jetty.http.port /opt/web/mybase/start.ini
    jetty.port=80

Change the permissions on the Jetty distribution and webapp directories so that the user you created can access it.

    # chown --recursive jetty /opt/jetty
    # chown --recursive jetty /opt/web/mybase

Next we need to make the Unix System aware that we have a new Jetty Service that can be managed by the standard `service` calls.

    # cp /opt/jetty/jetty-distribution-9.4.7.v20170914/bin/jetty.sh /etc/init.d/jetty
    # echo "JETTY_HOME=/opt/jetty/jetty-distribution-9.4.7.v20170914" > /etc/default/jetty
    # echo "JETTY_BASE=/opt/web/mybase" >> /etc/default/jetty
    # echo "TMPDIR=/opt/jetty/temp" >> /etc/default/jetty

Test out the configuration:

    # service jetty status
    Checking arguments to Jetty:
    START_INI      =  /opt/web/mybase/start.ini
    JETTY_HOME     =  /opt/jetty/jetty-distribution-9.4.7.v20170914
    JETTY_BASE     =  /opt/web/mybase
    JETTY_CONF     =  /opt/jetty/jetty-distribution-9.4.7.v20170914/etc/jetty.conf
    JETTY_PID      =  /var/run/jetty.pid
    JETTY_START    =  /opt/jetty/jetty-distribution-9.4.7.v20170914/start.jar
    CLASSPATH      =
    JAVA           =  /usr/bin/java
    JAVA_OPTIONS   =  -Djetty.state=/opt/web/mybase/jetty.state
           -Djetty.logs=/opt/web/mybase/logs
           -Djetty.home=/opt/jetty/jetty-distribution-9.4.7.v20170914
           -Djetty.base=/opt/web/mybase
           -Djava.io.tmpdir=/opt/jetty/temp
    JETTY_ARGS     =  console-capture.xml jetty-started.xml
    RUN_CMD        =  /usr/bin/java
           -Djetty.state=/opt/web/mybase/jetty.state
           -Djetty.logs=/opt/web/mybase/logs
           -Djetty.home=/opt/jetty/jetty-distribution-9.4.7.v20170914
           -Djetty.base=/opt/web/mybase
           -Djava.io.tmpdir=/opt/jetty/temp
           -jar /opt/jetty/jetty-distribution-9.4.7.v20170914/start.jar
           console-capture.xml
           jetty-started.xml

You now have a configured `${jetty.base}` in `/opt/web/mybase` and a `${jetty.home}` in `/opt/jetty/jetty-distribution-{VERSION}`, along with the service level files necessary to start the service.

Test the service to make sure it starts up and runs successfully.

    # service jetty start
    Starting Jetty: OK Wed Nov 20 12:35:28 MST 2013

    # service jetty check
    ..(snip)..
    Jetty running pid=2958

    [/opt/web/mybase]# ps u 2958
    USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
    jetty     2958  5.3  0.1 11179176 53984 ?      Sl   12:46   0:00 /usr/bin/java -Djetty...

You should now have your server running.

Previous | Top | Next
Managing XML Based Startup Configuration | Home | Startup via Windows Service

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