Tomcat

From Alpine Linux

Apache Tomcat is an open source web server that implements the Java Servlet, JavaServer Pages, Java Expression Language and Java WebSocket technologies. It can also serve static HTML pages.

This How-To describes how to set-up Tomcat to deliver static HTML pages as well as web applications packed as Web application ARchives (WAR).

Installation

Java

Tomcat requires the Java Runtime Environment (JRE) which is included in various packages from the Alpine community repository.

Tip: The community repository is disabled by default. See the Enable Community Repository page for more information about how to enable it.

Which package to install? There are couple of questions you need to answer first:

  • Which Java version do you need?
  • Do you need a JRE only or Java Development Kit (JDK)?

At the time of writing (March 2021), the most popular Java versions were Java 8 and Java 11. Java 8 is a minimum required version for Tomcat versions 9 and 10.

If you plan to use Java to run Tomcat only and you don’t need tools included in JDK, you may leverage on packages containing a JRE only with no GUI support. Package with no GUI support are also named “headless”.

To install OpenJDK 8 Java Runtime (no GUI support), execute the command:

apk add openjdk8-jre-base

To install OpenJDK 11 (JRE headless), execute the command:

apk add openjdk11-jre-headless

To install OpenJDK 8, execute the command:

apk add openjdk8

To install OpenJDK 11, execute the command:

apk add openjdk11

To check which Java version is currently installed, execute the command:

java -version

Tomcat

Tomcat has to be downloaded from the Apache Tomcat homepage. You need the Binary Distribution Core (tar.gz), download it, save it in a place where you can easily find it and extract it into a folder of your choice. In this manual we will assume that Tomcat is extracted into the /opt/tomcat directory.

To create the /opt/tomcat directory, execute the command:

mkdir /opt/tomcat

To extract the binary distribution to the /opt/tomcat directory, execute the command:

tar xvzf apache-tomcat-9.0.44.tar.gz --strip-components 1 --directory /opt/tomcat

To test your installation, execute the command:

/opt/tomcat/bin/catalina.sh version

You should see a list of folders, the installed tomcat version, OS name, processor architecture and so on. If this fails, either the installed version of tomcat is somehow incompatible with the installed version of Java or one of the two programs was not properly installed.

Tip: Tomcat consists of several components, Catalina is the part responsible for running the server.

If the first test succeeded, you can test the server itself by running catalina.sh with the run command. The command will start Tomcat in your current console.

/opt/tomcat/bin/catalina.sh run

Now, point a browser on the same computer that Alpine runs on to http://127.0.0.1:8080/. You should see a page that says If you are seeing this, you successfully installed Tomcat. Congratulations!.

Tip: Make sure you included the :8080 after the IP adress. 8080 is the standard port of Tomcat, while your browser will search the server on port 80 unless you specify another port.

To stop Tomcat, press Control+C.

Usually, you don't want to start Tomcat in the current console, but as a background process. To start Tomcat in background, execute the startup.sh script:

/opt/tomcat/bin/startup.sh

To stop Tomcat, execute the shutdown.sh script:

/opt/tomcat/bin/shutdown.sh

Tomcat Service Script

You can also start Tomcat as an OpenRC service.

Create the /etc/init.d/tomcat file with the following content:

#!/sbin/openrc-run
description="Apache Tomcat"
command=/opt/tomcat/bin/catalina.sh
command_args=run
command_background=true
directory=/opt/tomcat
pidfile="/run/${RC_SVCNAME}.pid"

Make the /etc/init.d/tomcat file executable:

chmod +x /etc/init.d/tomcat

Now, you can start Tomcat using OpenRC as follows:

rc-service tomcat start

To stop Tomcat, execute the command

rc-service tomcat stop

To enable automatic start on system start, you can add the service to the default runlevel:

rc-update add tomcat default

Running Tomcat

There are two ways to publish documents with Tomcat: Either a dynamic java application (for example a wiki, a forum, or a blog) or as static pages (HTML, images). Tomcat is specialized on dynamic applications, which are usually deployed as WAR file.

Dynamic Content

Installing a WAR file is easy: Simply copy it to /opt/tomcat/webapps. Tomcat will automatically install it to a folder with the same name as the WAR file (whatever is written before the .WAR extension). For example, if you install jspwiki.war, you can open the wiki on http://127.0.0.1:8080/jspwiki/.

Static Content

To deliver static content, you need to edit the file server.xml in the folder /opt/tomcat/conf.

Find the <Host appBase="webapps"> section in the server.xml, and add the entry <Context docBase="/home/stuff" path="/static" /> directly before the closing </Host>. Replace /home/stuff with the folder where you will save your static files. The /static is the part of the URL you need to open your static files, it can be changed to whatever you like.

More detailed description how serving static content with tomcat works.