I got tired of heavyweight frameworks, so I built my own web server in Java

Most Java web projects start with Spring Boot. You add the dependency, and suddenly you have an entire ecosystem loaded into memory before your first route is even registered. For a lot of use cases that's totally fine. But I wanted something I could drop a JAR into a folder, double-click, and have a running web server in under three seconds — no config ceremony, no classpath drama.

So I built Aurelius.

What is it?

Aurelius is a lightweight, minimalist Java web server designed for developers who want to get a site or a small API running without pulling in a full framework. It runs on Java 8+, ships as a single executable JAR (or .exe on Windows), and is built on top of Netty for the networking layer.

The core idea: drop the JAR in a folder, launch it, put your HTML files in the right place, and you have a running server. That's it.

Project structure

When Aurelius starts, it expects this layout:

my-project/
├── aurelius.jar
├── settings.yml
├── app/
│   └── main.html        ← served at /
│   └── about/
│       └── main.html    ← served at /about
├── containers/
│   └── button.html
│   └── section.html
└── public/
    └── logo.png
    └── data.json

Every folder under app/ becomes a route. main.html in a folder is the index for that route. Files under public/ are served statically and accessible from any HTML file via /public/filename.

The container system

This is the part I'm most proud of. Instead of reaching for a templating engine, I built a simple component system directly into the server.

You define a reusable HTML fragment in the containers/ folder:

<!-- containers/button.html -->
<button class="btn btn-primary">{text}</button>

Then you use it anywhere in your pages with a custom tag:

<container.button text="Click me"></container.button>

Aurelius processes the tag at serve time, injects the attribute values into the fragment, and sends the assembled HTML to the client. No JavaScript required, no build step, no npm.

You can nest containers, pass multiple attributes, and compose entire page sections from reusable fragments. It's not React — it's intentionally much simpler — but for static-ish sites it removes a lot of repetition.

Placeholder system

For site-wide variables, Aurelius has a placeholders.yml file:

title: "My Site"
author: "Mustafa"
version: "1.2"

Anywhere in your HTML you write %title% and Aurelius substitutes it at serve time:

<head>
  <title>%title% — Home</title>
</head>

This is useful for things like site name, meta descriptions, or any string you'd otherwise duplicate across dozens of pages.

RESTful API support via addons

Aurelius isn't just for serving HTML. You can register REST endpoints programmatically through the addon system:

// GET /api/hello
AddonManager.registerRestFulService(
    new RestFulResponseStructure.Builder("hello")
        .setRestFulResponse((body, helper) -> {
            return "Hello, world! Path: " + Arrays.toString(helper.getPathData());
        })
        .setRequestType(RestFulRequestType.GET)
        .build()
);

For structured request/response bodies, you implement the RestFulResponse<Output, Input> interface and Aurelius handles JSON deserialization automatically:

public class UserController implements RestFulResponse<UserDto, UserRequest> {

    @Override
    public UserDto response(UserRequest request, RestFulResponseHelper helper) {
        UserDto dto = new UserDto();
        dto.setUsername(request.getUsername());
        return dto;
    }

    @Override
    public UserRequest convert(String body) throws Exception {
        return (UserRequest) AddonManager.convertFromBodyJson(body, UserRequest.class);
    }
}

Cookies are also supported through the helper:

CookieStructure cookie = new CookieStructure();
cookie.setCookieName("session");
cookie.setCookieValue(UUID.randomUUID().toString());
cookie.setFeatures(Arrays.asList(new CFMaxAge(3600), new CFHttpOnly()));
helper.sendCookie(cookie);

Configuration

All server settings live in settings.yml:

server:
  port: 8080
  threadSize: 4
  ui: true

ui: true enables a built-in management panel where you can start, stop, and reload the server without touching the terminal. Useful if you're deploying somewhere without a great CLI experience.

Framework support

Because Aurelius just serves HTML, it works with any CSS framework that can be loaded from a CDN. Tailwind, Bootstrap, Bulma — just drop the <link> tag in your HTML and it works.

Who is this for?

Aurelius is a good fit if you:

Want a zero-dependency web server for a small internal tool or personal site
Are learning Java web development and want to see how a server works without framework magic hiding everything
Need to prototype a REST API quickly without standing up a Spring application
Want to understand Netty's HTTP handling without writing the boilerplate yourself

It's not the right tool for large production applications with complex routing, authentication middleware, or ORM integration. For those, reach for Spring Boot or Quarkus.

What's next

The main thing on my list is proper test coverage — the container parsing and placeholder substitution logic especially need unit tests. I'm also thinking about WebSocket support and a simple session management API.

11 releases in, Aurelius handles the basics solidly. If you're the kind of developer who likes understanding what's running under the hood, give it a try.

推荐订阅源

DEV Community