LearnAI ToolsCareerPractice BuildsPlayContact
Lesson 520 min read

Setting Up a JSP Project (Tomcat)

Install Apache Tomcat, understand the WEB-INF folder structure, and learn how a JSP project gets deployed as a WAR or exploded directory.

Introduction

JSP does not run on its own - it needs a servlet container to translate, compile, and serve .jsp files. Apache Tomcat is by far the most widely used servlet container for learning and running JSP applications, and it is free and open-source. In this lesson, you will install Tomcat, understand how it expects a project to be organized, and learn the two common ways to deploy a JSP application to it.

Installing Apache Tomcat

Apache Tomcat can be downloaded from the official Apache Tomcat website as a zip/tar archive. You do not need to "install" it in the traditional sense - you extract the archive to a folder on your machine, and that folder becomes your Tomcat home directory.

  • Make sure a Java Development Kit (JDK) is installed first - Tomcat requires Java to run.
  • Download the appropriate Tomcat version (for example, Tomcat 10.x) for your operating system.
  • Extract the archive to a location such as C:\tomcat or /opt/tomcat.
  • Set the JAVA_HOME environment variable so Tomcat can locate your JDK installation.
Tomcat Version Note

Tomcat 10 and later use the jakarta.servlet package (matching Jakarta EE), while Tomcat 9 and earlier use javax.servlet. Make sure your Tomcat version matches the package names your project or tutorial uses.

Starting and Testing Tomcat

Inside the Tomcat home directory is a bin folder containing startup scripts. On Windows you run startup.bat; on macOS/Linux you run startup.sh.

Starting Tomcat from a terminal
cd tomcat/bin


# Windows
startup.bat


# macOS / Linux
./startup.sh

By default Tomcat listens on port 8080. Once it is running, open a browser and go to http://localhost:8080 - you should see the Tomcat welcome page confirming the server is up.

Browser at http://localhost:8080

Click Run to see what this code prints.

The webapps Folder Structure

Tomcat serves applications from its webapps folder. Each subfolder inside webapps is treated as a separate web application, accessible at http://localhost:8080/<folder-name>/. For example, a folder named myapp becomes accessible at http://localhost:8080/myapp/.

Basic Tomcat directory layout
tomcat/
├── bin/            (startup/shutdown scripts)
├── conf/           (server.xml and other configuration)
├── logs/           (server logs, useful for debugging)
├── webapps/
│   ├── ROOT/       (served at http://localhost:8080/)
│   └── myapp/      (served at http://localhost:8080/myapp/)
└── work/           (Tomcat's compiled/translated files go here)

Understanding WEB-INF

Every JSP web application needs a WEB-INF folder inside its root directory. WEB-INF is special: everything inside it is protected from direct browser access - a request to a file inside WEB-INF will be rejected by the container. Only server-side code (like a Servlet forwarding a request) can reach files there.

Typical JSP project structure inside webapps/myapp/
myapp/
├── index.jsp                 (accessible directly in the browser)
├── welcome.jsp                (accessible directly in the browser)
└── WEB-INF/
    ├── web.xml                (deployment descriptor - configuration)
    ├── classes/                (compiled .class files for Servlets/helpers)
    └── lib/                    (JAR files/dependencies)
LocationDirectly Accessible by Browser?
myapp/index.jspYes
myapp/WEB-INF/web.xmlNo - blocked by container
myapp/WEB-INF/classes/No - blocked, but used internally to load Servlet classes
myapp/WEB-INF/views/dashboard.jspNo - must be reached via a Servlet forward
Why Hide JSP Files in WEB-INF?

A common real-world pattern is to place JSP view files inside WEB-INF/views/ so users cannot request them directly - they can only see a page after a Servlet has processed the request and forwarded to it. This enforces the controller-then-view flow from the previous lesson.

WAR Files vs Exploded Directories

There are two common ways to deploy a JSP application to Tomcat.

MethodDescription
Exploded directoryYou place the unpacked folder structure (like myapp/ shown above) directly inside webapps/. Good for local development - changes to .jsp files are picked up without redeploying.
WAR fileYou package the entire application into a single myapp.war archive (a zip file with a specific structure) and drop it into webapps/. Tomcat automatically extracts and deploys it. This is the standard way to ship an application to a production or test server.
Example WAR file structure (before Tomcat extracts it)
myapp.war
├── index.jsp
├── welcome.jsp
└── WEB-INF/
    ├── web.xml
    ├── classes/
    └── lib/

Build tools like Maven can package a project into a .war file automatically with a single command (mvn package), which is the standard workflow in real enterprise JSP projects rather than manually copying folders.

Common Mistakes

Avoid These Mistakes
  • Forgetting to set JAVA_HOME before starting Tomcat, which causes startup scripts to fail silently or with a cryptic error.
  • Placing JSP files that should be private (like admin dashboards) outside WEB-INF, making them directly accessible to anyone.
  • Assuming a WAR file and an exploded directory behave differently at runtime - once deployed, they behave identically.
  • Mixing Tomcat 9 (javax) and Tomcat 10+ (jakarta) dependencies in the same project, causing ClassNotFoundException errors.

Best Practices

  • Use an exploded directory during local development for faster iteration, and a WAR file for deployment.
  • Check the logs/ folder whenever Tomcat fails to start or a page throws an error - it almost always has the real error message.
  • Keep sensitive configuration files and internal JSP views inside WEB-INF.
  • Match your Tomcat version to the servlet/JSP API version your project depends on.

Frequently Asked Questions

Usually no. Tomcat automatically detects changes to .jsp files and re-translates/recompiles them on the next request. Changes to Java classes or web.xml typically do require a restart.

8080. It can be changed in conf/server.xml if it conflicts with another application on your machine.

The servlet specification requires containers to block direct access to WEB-INF for security - it is meant to store configuration, compiled classes, and protected views that should only be reached through server-side logic.

For local learning and development, an exploded folder is perfectly fine. Production and shared environments almost always use WAR files because they are a single, portable artifact.

Key Takeaways

  • Apache Tomcat is the standard servlet container used to run JSP applications.
  • Applications live inside Tomcat's webapps folder, one subfolder per application.
  • WEB-INF is a protected folder - its contents cannot be requested directly by a browser.
  • A JSP application can be deployed either as an exploded directory or a packaged WAR file.
  • Tomcat automatically detects and re-translates changed JSP files without a restart.

Summary

You now have Tomcat installed and understand how it expects a JSP application to be structured, including the protected WEB-INF folder and the difference between an exploded deployment and a WAR file. In the next lesson, you will put this knowledge to use by creating and deploying your very first JSP page.

Next Lesson →

Your First JSP Page