Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 37 ยท Architecture and Install

Installing Tomcat

Install Apache Tomcat step by step: check Java, download and verify the archive, unpack it, set JAVA_HOME, start the server, test port 8080, and use packages or Docker.

Installing Tomcat is refreshingly simple: it is a ZIP or tar.gz archive that you unpack, with no installer magic and no registry entries required. All you need is a Java runtime. This lesson walks through the whole procedure on Windows, Linux and macOS, explains how to verify the download, and compares the alternatives (OS packages, Docker, embedded).

The commands are shown read-only because Tomcat is not available on this site. A runnable prerequisite checker at the end uses plain Java to test your environment the way the startup scripts do.

Step 1: Java first

Tomcat needs a JRE or JDK that matches your Tomcat line (see versions and compatibility). For development install a JDK (you will compile servlets); on a server a JRE or a headless JDK package is enough.

Terminal
java -version
javac -version        # present only with a JDK

If the command is missing, install an LTS build such as Java 17 or 21 from a vendor like Eclipse Temurin, your Linux distribution's repository or brew install openjdk@21.

Step 2: download and verify

Download the Core distribution of the line you chose from the official Tomcat site (tomcat.apache.org): .tar.gz for Linux and macOS, .zip for Windows, or the Windows service installer. Next to each archive are checksum (.sha512) and signature (.asc) files. Verify at least the checksum, so a corrupted or tampered file never reaches your server:

Terminal
sha512sum -c apache-tomcat-10.1.x.tar.gz.sha512
# apache-tomcat-10.1.x.tar.gz: OK

For production also check the PGP signature against the Apache KEYS file.

Step 3: unpack

Terminal
sudo mkdir -p /opt/tomcat
sudo tar -xzf apache-tomcat-10.1.x.tar.gz -C /opt/tomcat --strip-components=1

On Windows extract the ZIP to a short path without spaces such as C:\tomcat. The folder you unpacked is called CATALINA_HOME; the next two lessons explain what is inside (directory layout).

Install in four moves

Java Install a supported JDK or JRE
Download Core archive plus checksum
Unpack Folder becomes CATALINA_HOME
Start startup script, test port 8080

No installer, no database, no registry.

1 / 2

Step 4: a dedicated user (Linux)

Never run Tomcat as root. A compromised web application would own your server. Create a service account that owns the runtime folders but not the configuration:

Terminal
sudo useradd -r -m -U -d /opt/tomcat -s /bin/false tomcat
sudo chown -R tomcat:tomcat /opt/tomcat/{logs,temp,work,webapps}
sudo chmod -R g+r /opt/tomcat/conf
sudo chmod g+x /opt/tomcat/conf

Step 5: set JAVA_HOME and start

Tomcat finds Java through JAVA_HOME (a JDK or JRE directory) or JRE_HOME; if neither is set it looks for java on the PATH.

Terminal
export JAVA_HOME=/usr/lib/jvm/temurin-21-jdk
/opt/tomcat/bin/startup.sh
tail -f /opt/tomcat/logs/catalina.out

On Windows:

BAT
set JAVA_HOME=C:\Java\jdk-21
C:\tomcat\bin\startup.bat

Wait for the line Server startup in [1234] milliseconds and open http://localhost:8080. You should see the Tomcat welcome page. The port is configured in a connector in conf/server.xml (connectors lesson).

Put permanent settings (JAVA_HOME, heap size) into a file called bin/setenv.sh (or setenv.bat) rather than editing catalina.sh. Tomcat reads it automatically, and your changes survive upgrades. See starting and stopping Tomcat.

Alternatives to the archive

Method Pros Cons
Archive (this lesson) Same on every OS, full control, multiple versions side by side You handle updates and the service wrapper
Linux package (apt install tomcat10) systemd unit, user and paths prepared; security updates Distribution versions lag behind; layout split between CATALINA_HOME and CATALINA_BASE
Windows service installer Registers a service and a tray monitor Windows only
Docker (docker run -p 8080:8080 tomcat:10.1-jdk21) Reproducible, easy to throw away Containers need persistent volumes for logs and uploads
Embedded One JAR, nothing to install Different operations model

The default webapps shipped with Tomcat (ROOT, docs, examples, manager, host-manager) are useful when learning but should be removed on production servers, as they enlarge the attack surface.

A prerequisite checker

This runnable program does what the startup scripts do in shell: it inspects the Java environment, evaluates whether the Java version fits a given Tomcat line and reports problems such as a missing compiler or a path with spaces. It uses only the standard library.

Java Check the prerequisites (stand-in for the startup scripts)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Verifying the installation

After startup, confirm four things: the log ends with Server startup in ..., http://localhost:8080 answers, bin/version.sh prints the expected version and the Java process runs as the expected user (ps -o user,cmd -C java). A common failure is Address already in use on port 8080, which means another program owns the port; either stop it or change the connector port.

This small program tests the same condition: it binds a port, then shows that a second attempt on the same port fails.

Java Why 'Address already in use' happens

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does Tomcat need installed before it can start?

    Tomcat is a Java program. It finds Java through JAVA_HOME, JRE_HOME or the PATH.
  2. 2. Why verify the .sha512 checksum of the download?

    A matching checksum proves the file is the one the project published (use the signature to prove who published it).
  3. 3. Where should permanent environment settings such as heap size go?

    setenv is read automatically and kept separate from files that upgrades replace.
  4. 4. Why should the default manager and examples webapps be removed on production servers?

    Sample apps and admin tools are not needed in production and can contain exploitable features if left reachable.
  5. 5. Which user should run Tomcat on Linux?

    An unprivileged service account limits the damage if a web application is compromised.

Summary

  • Install a supported JDK/JRE, download the Core archive, verify its checksum and unpack it; the folder is CATALINA_HOME.
  • Run Tomcat under a dedicated unprivileged user and keep settings in setenv.
  • Start with startup.sh or startup.bat, watch catalina.out, browse to port 8080.
  • Alternatives: OS packages, Windows service installer, Docker and embedded Tomcat.
  • Remove sample webapps on production and fix "Address already in use" by freeing or changing the port.

Next: The Tomcat directory layout