Embedding Tomcat in a Spring Boot Application: A Step‑by‑Step Tutorial

1. Discover the Built‑in Tomcat

Opening a SpringBoot project reveals a Tomcat dependency inside spring-boot-starter-web. By navigating the Maven coordinates you can locate the exact version (2.1.0 in the example) and view the Tomcat libraries that are pulled in automatically.

Further inspection of the spring-boot-starter-web pom shows the Tomcat artifact and its version.

2. Create a Maven Project

(Details omitted for brevity.)

3. Add the Tomcat Dependency

Use the embedded Tomcat version 8.5.16:

<!-- Java language operates Tomcat -->
<dependency>
  <groupId>org.apache.tomcat.embed</groupId>
  <artifactId>tomcat-embed-core</artifactId>
  <version>8.5.16</version>
</dependency>

4. Create a Servlet: IndexServlet

public class IndexServlet extends HttpServlet {
    private static final long serialVersionUID = 1L;
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        doPost(req, resp);
    }
    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        resp.getWriter().print("IndexServletIndexServletIndexServletIndexServletIndexServletIndexServlet");
    }
}

In a traditional web.xml you would map this servlet, but with an embedded container we will configure it programmatically.

5. Build and Run an Embedded Tomcat

5.1 Define Servlet Configuration Parameters

Set servlet name and URL mapping (shown in the following diagram).

5.2 Common Embedded Tomcat API

Key classes and methods:

org.apache.catalina.startup.Tomcat

Tomcat tomcatServer = new Tomcat();

void setPort(int port);

void setPath(String path);

void addLifecycleListener(LifecycleListener listener);

Wrapper addServlet(String contextPath, String servletName, Servlet servlet);

void addServletMappingDecoded(String pattern, String name);

void start() throws LifecycleException;

Server getServer();

void getServer().await();

5.3 Create Tomcat and Add Servlet

public class TestTomcat {
    private static int PORT = 8080;
    private static String CONTEX_PATH = "/demosevlet";
    private static String SERVLET_NAME = "index";
    private static String MAPPING = "index";
    public static void main(String[] args) throws LifecycleException, InterruptedException {
        System.out.println("Starting Tomcat...");
        Tomcat tomcatServer = new Tomcat();
        tomcatServer.setPort(PORT);
        tomcatServer.getHost().setAutoDeploy(false);
        StandardContext standardContex = new StandardContext();
        standardContex.setPath(CONTEX_PATH);
        standardContex.addLifecycleListener(new FixContextListener());
        tomcatServer.getHost().addChild(standardContex);
        tomcatServer.addServlet(CONTEX_PATH, SERVLET_NAME, new IndexServlet());
        standardContex.addServletMappingDecoded("/" + MAPPING, SERVLET_NAME);
        tomcatServer.start();
        System.out.println("Tomcat started.");
        tomcatServer.getServer().await();
    }
}

5.4 Run the Main Method

Executing the main method launches Tomcat on port 8080 and creates a tomcat.8080 directory.

5.5 Access the IndexServlet

Open a browser and navigate to http://127.0.0.1:8080/demosevlet/index to see the servlet response.

The article also contains promotional sections for a “Top‑Level Architect” community and a copyright notice, which are not part of the technical tutorial.