# Undertow: a Java non-blocking web server for embedded and WildFly deployments

> Undertow is a Java web server built on non-blocking IO, with a core HTTP server, a Servlet 4.0/5.0/6.0 implementation and a JSR-356/Jakarta 2.0 WebSocket implementation. It fits teams that want an embeddable server rather than a standalone container.

**undertow-io/undertow** — High performance non-blocking webserver

- Repository: https://github.com/undertow-io/undertow
- Website: https://undertow.io
- Stars: 3,760 · Forks: 1,050
- Language: Java
- License: Apache-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/undertow-io-undertow

## What Undertow is, and who the repository is written for

Undertow is a Java web server based on non-blocking IO. The README splits it into three parts: a core HTTP server that supports both blocking and non-blocking IO, a Servlet 4.0/5.0/6.0 implementation, and a JSR-356/Jakarta 2.0 compliant WebSocket implementation. That three-part split is the whole pitch. You are not getting a product with an admin console and a startup script. You are getting libraries that a Java application embeds.

The audience follows from that. If you are writing a service that needs an HTTP listener inside its own process, or you are maintaining something that runs on WildFly, Undertow is the layer underneath. The topics list on the repository includes jboss, wildfly and jakartaee10, which tells you where the main consumer is. The project lead is Flavia Rainone at Red Hat, and the issue tracker lives on Red Hat's Jira rather than GitHub Issues. Support questions go to a Google Group or a Zulip stream, not a Discord. This is enterprise Java infrastructure with enterprise Java habits.

The README is thin. It names the parts, gives the website, the issue tracker, the mailing list, the chat and a security contact, and stops. There is no quickstart, no configuration reference and no deployment guide. For an engineer evaluating adoption, that means the README answers what Undertow is and almost nothing about how you operate it. The examples/ directory and the module directories are where the real information sits.

## The non-blocking core and how the blocking path fits beside it

The distinguishing mechanism stated in the README is that the core HTTP server supports both blocking and non-blocking IO. Most Java HTTP servers pick one model and make the other awkward. Undertow's design lets a single server accept connections on non-blocking IO and then hand a request to a worker thread when the handler needs to block, which is what the Servlet layer requires. That is why the same core can back a raw low-level handler and a Servlet deployment.

The repository layout reflects the separation. core/ holds the HTTP server. servlet/ holds the Servlet implementation. websockets-jsr/ holds the JSR-356 and Jakarta WebSocket layer. There is also an ajp topic, so the AJP protocol used by front-end web servers is part of the surface area, and a karaf/ directory for the OSGi container. dist/ collects distribution artifacts. benchmarks/ exists as a top-level directory, which suggests performance work is tracked in-tree, though the README makes no performance claim and none should be inferred from the presence of that directory.

The practical consequence for an architect is that Undertow is assembled, not configured. You choose which modules to depend on. If you only need an HTTP listener and WebSockets, you do not need the servlet module in your dependency graph at all. That granularity is the main reason to pick Undertow over a monolithic container, and it is also the reason the README cannot give you a single install command that covers every case.

## Getting Undertow into a build and a first handler

The README gives no install steps, so the entry point is the build system the repository uses: a top-level pom.xml, which means Maven artifacts. The repository layout also shows a dist/ directory and a karaf/ directory, and the examples/ directory contains a pom.xml and a src/ tree, so an example project is the closest thing to a starting point in the tree. The README does not name a groupId, an artifactId or a version, so this article will not invent one. Check the pom.xml files in the repository and the release tags to find the coordinates for the version you intend to use.

The same caution applies to a first program. The README does not show a handler, a listener, a port or a builder call, so any snippet printed here would be written from memory rather than copied from the project. The honest instruction is to open examples/pom.xml and examples/src/, which the repository ships precisely so that a runnable arrangement exists, and to read core/ for the HTTP server itself. If you need servlets or JSR-356 WebSockets, servlet/ and websockets-jsr/ are the modules to look at, and examples/conf/ holds configuration.

What the README does tell you is where to ask. The Undertow Dev Group is a Google Group, and there is a Zulip stream at wildfly.zulipchat.com under #undertow. For a project with no quickstart in its README, those channels are the practical substitute. Security-relevant bugs go to Red Hat SecAlert with a copy to the project lead rather than into a public issue.

## Where Undertow is the wrong choice

Undertow does not ship as an application you start and administer. There is no documented command-line launcher, no admin console and no server-level configuration file described in the README. If your operational model assumes you install a server, drop a WAR into a directory and restart it, Undertow is not that. WildFly is that, and Undertow is a component inside it.

The documentation gap is the second limitation, and it is real rather than cosmetic. The README has no configuration reference, no list of tunables, no upgrade notes and no rollback guidance. Release information comes from the release list, and the README does not describe what changed between 2.4.0.Final and 2.4.1.Final. An engineer who needs to justify a version bump to a change board will not find the answer in the README; the release notes are the place to look, and the README does not point at them.

The third constraint is version alignment. The README states Servlet 4.0/5.0/6.0 and JSR-356/Jakarta 2.0 support without mapping those to specific Undertow versions. If your application is compiled against a particular Servlet or Jakarta WebSocket API level, you have to verify the pairing yourself against the release you pick. Nothing in the README does that mapping for you, and guessing it is how you end up with a NoSuchMethodError at startup.

## Undertow against Tomcat and Jetty

The obvious comparison is Tomcat, and the difference is architectural rather than cosmetic. Tomcat is a servlet container you can also embed. Undertow is a non-blocking HTTP server that also implements servlets. In Tomcat the servlet container is the centre and the connector is attached to it. In Undertow the README describes the core HTTP server first and the Servlet implementation as a separate part, so the server exists without the servlet layer. That ordering matters if you want HTTP and WebSockets with no servlet API on the classpath.

Jetty sits closer to Undertow in model, since it is also an embeddable Java server with a non-blocking core and a servlet layer. The README does not compare Undertow to either project, so any detailed claim about relative throughput, memory or thread behaviour would be invented. What can be said from the repository is structural: Undertow's parts are split into core/, servlet/ and websockets-jsr/ with a separate karaf/ integration and an AJP topic, and the project is the HTTP layer for WildFly. Choose on that basis, and benchmark on your own workload rather than on a comparison nobody in this repository has published.

## Maintenance, releases and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-16. Releases are tagged with the .Final suffix typical of Red Hat projects: 2.4.0.Beta1 on 2026-02-18, then 2.4.0.Final and 2.4.1.Final both on 2026-05-20. The gap between the two Final releases is minutes, which suggests 2.4.1.Final is a follow-up to 2.4.0.Final rather than a long-running development cycle. Beta and Final tags indicate a staged release process, so you should expect to track a beta line if you want features before they are finalised.

Upgrade cost is the part the README does not address. There is no migration guide, no deprecation list and no statement about API stability between minor versions. For a server library that other projects embed, that is a gap worth naming. The practical mitigation is to pin an exact version, read the release notes for the version you are moving to, and check whether the Servlet or Jakarta WebSocket API level you depend on changed.

The licence is Apache-2.0, stated in LICENSE.txt at the repository root. That is a permissive licence with an explicit patent grant, and it is compatible with embedding in closed-source products. This is not legal advice; if you redistribute Undertow inside a product, have your own counsel review the NOTICE and attribution requirements that Apache-2.0 carries. There is also a dco.txt file, which indicates a Developer Certificate of Origin requirement for contributions, and a CODEOWNERS file for review routing.

## Conclusion

Adopt Undertow when you need an embeddable Java HTTP server with blocking and non-blocking paths, servlet support and JSR-356/Jakarta WebSockets in one dependency tree, and when the Apache-2.0 licence suits your distribution. Do not adopt it if you want a standalone server binary with its own CLI and admin console, or if you expect the README to walk you through deployment. Before committing, verify which Servlet and Jakarta WebSocket versions your target release ships, confirm the release cadence against your upgrade window, and read core/, servlet/ and websockets-jsr/ in the repository rather than relying on the README, which documents none of the runtime configuration.

## FAQ

### How do I use Undertow in Spring Boot?

Spring Boot support is not described in the README or the repository layout, so nothing here confirms how the integration is wired. What the README does establish is that Undertow is a Java web server based on non-blocking IO with a core HTTP server, a Servlet implementation and a JSR-356/Jakarta 2.0 WebSocket implementation, which is the layer any framework integration would sit on.

### How does Undertow work?

The README states that Undertow is based on non-blocking IO and that its core HTTP server supports both blocking and non-blocking IO. Around that core it provides a Servlet 4.0/5.0/6.0 implementation and a JSR-356/Jakarta 2.0 compliant WebSocket implementation, with the parts separated into the core/, servlet/ and websockets-jsr/ directories.

### How do I get Undertow from Maven?

The repository is built with Maven, as shown by the top-level pom.xml, and the examples/ directory ships its own pom.xml and src/ tree. The README does not name a groupId, an artifactId or a version, so read the pom.xml files and the release tags to find the coordinates for the version you intend to use.

### Which Undertow version should I pick?

The most recent release listed is 2.4.1.Final, published on 2026-05-20, with 2.4.0.Final published the same day and 2.4.0.Beta1 before that on 2026-02-18. The README does not map specific Undertow versions to specific Servlet or Jakarta WebSocket API levels, so that pairing has to be checked against the release you choose.

### Is Undertow a standalone server I can install and run?

The README describes Undertow as a Java web server made of a core HTTP server, a Servlet implementation and a WebSocket implementation, and gives no launcher, admin console or server configuration file. It is used as the HTTP layer in WildFly, and the repository ships Maven artifacts rather than a standalone distribution you start directly.

## Sources

- [License: Apache-2.0](https://github.com/undertow-io/undertow/blob/main/LICENSE)
- [Project website](https://undertow.io)
- [README](https://github.com/undertow-io/undertow/blob/main/README.md)
- [Releases](https://github.com/undertow-io/undertow/releases)
- [undertow-io/undertow on GitHub](https://github.com/undertow-io/undertow)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/undertow-io-undertow