line/armeria: a microservice framework built on Netty, for any protocol you already use

The problem Armeria solves: one Java service, several protocols

A Java backend that speaks HTTP to browsers, gRPC to internal services and Thrift to a legacy system usually ends up with three stacks. Each has its own server bootstrap, its own client, its own thread model and its own way of reporting errors. Armeria's premise is that this is one problem, not three. The README describes it as a microservice framework where you can build any type of microservice using gRPC, Thrift, Kotlin, Retrofit, Reactive Streams, Spring Boot or Dropwizard. The audience is JVM teams that already know which protocols they need and want a single runtime underneath them.

The project comes from the creator of Netty and colleagues at LINE Corporation, and it is open-sourced under Apache-2.0. That provenance matters for the kind of reader this is for: someone who is comfortable reading Netty documentation and does not want the event loop hidden. If you want a framework that abstracts the network away entirely, this is not the pitch.

How the pieces fit: core, protocol modules and integrations

The repository layout shows the design more clearly than the README does. There is a core/ directory, and around it a ring of protocol and integration modules: grpc/, grpc-kotlin/, grpc-protocol/, thrift modules, graphql/, graphql-protocol/, jsonrpc/, protobuf/, kotlin/, reactor3/, spring-boot-minimal/, dropwizard2/, jetty/ and kafka/. The README's technology list maps onto these directories, so the README is a summary of the module graph rather than a separate claim.

The second ring is operational: consul/, eureka/, nacos/, kubernetes/, zookeeper-style service discovery and registry integrations, oauth2/, athenz/ and saml-service-provider/ for authentication and authorization, micrometer-context/ and prometheus1/ for metrics, brave/ for tracing, bucket4j/ for rate limiting, logback/ for logging, and native-image-config/ for GraalVM native image builds. There is also an annotation-processor/ module and a junit5/ module, which suggests both compile-time code generation and test support are first-class parts of the project rather than afterthoughts.

The practical consequence is that Armeria is closer to a platform than a library. A team adopting it is choosing a set of module boundaries, not a single jar, and the dependency tree grows with each integration enabled.

Installing Armeria and running a first annotated service

The README states the requirement plainly: Java 8 or later if you are a user. It does not give installation steps, so the entry point is Maven Central, where the badge in the README points at the com.linecorp.armeria group. The most recent release listed in the repository is armeria-1.41.1, published on 2026-09-01, preceded by armeria-1.41.0 on 2026-08-07 and armeria-1.40.0 on 2026-06-18.

A Gradle build declares the core artifact like this:

dependencies {
    implementation 'com.linecorp.armeria:armeria:1.41.1'
}

After a dependency refresh, the core module and its transitive Netty dependencies should appear on the compile classpath. The repository ships an examples/annotated-http-service/ directory alongside a Kotlin variant, examples/annotated-http-service-kotlin/, which is the shortest path from a fresh checkout to a running server. The examples/README.md is the index for the whole set, including proxy-server/, server-sent-events/ and the spring-boot-minimal/ variants.

For a first real use, start the annotated HTTP example rather than writing a server from scratch. The point of that example is to show the annotation-driven style, where methods are mapped to routes without a separate router object. Once it runs, the next step is to add a second protocol. The grpc/ and thrift/ modules are separate dependencies, so enabling one is a build change, and that is where the single-runtime claim either holds up for your service or does not.

Where Armeria is the wrong choice

The Java 8 baseline is the first constraint. The README states it as a user requirement, and the repository carries a native-image-config/ module, so GraalVM native image is a supported target. Neither of those helps a team running Go, Rust or Node services. Armeria is a JVM framework; the polyglot story is limited to JVM languages, which is why the repository has kotlin/ and grpc-kotlin/ modules but no equivalent for other runtimes.

The second constraint is surface area. The module list is long: service discovery, auth, metrics, tracing, rate limiting, GraphQL, JSON-RPC, Kafka, Jetty, Dropwizard, Spring Boot. Every integration you switch on is code you now depend on and eventually have to upgrade. A team that only needs a plain HTTP server with a handful of routes is paying for a platform to get a library. The examples/ directory is a useful sanity check here: if none of the example directories resembles your service, the framework is probably larger than your problem.

The third is documentation depth. The README is short and points to armeria.dev for everything substantive. It does not document rollback, version compatibility between modules, or what changes between minor releases. Release notes exist for 1.40.0, 1.41.0 and 1.41.1, but the README itself gives no upgrade guidance. That gap matters more for a framework with this many modules than it would for a single-purpose library, because a minor bump can move several of them at once.

Armeria compared with plain Netty or Spring Boot

The obvious alternative is Netty directly. Armeria is built on Netty by Netty's creator, so the difference is not performance philosophy; it is the layer above. With Netty you assemble the HTTP/2 handling, the route dispatch, the client pool and the metrics yourself. Armeria's modules are that assembly, pre-packaged, with gRPC and Thrift as first-class citizens rather than add-ons. If you already have a working Netty pipeline and a small team that understands it, replacing it with Armeria buys you less than the migration costs.

The other comparison is Spring Boot. A team on Spring Boot already has an HTTP server, dependency injection, configuration and a large ecosystem. The repository acknowledges this by shipping examples/spring-boot-minimal/, examples/spring-boot-jetty/, examples/spring-boot-tomcat/, examples/spring-boot-webflux/ and examples/spring-cloud-config-xds/. Those examples imply Armeria is often adopted inside a Spring application rather than instead of one, which changes the question from replacement to insertion. The difference in approach is that Armeria owns the transport and protocol layer, while Spring owns the application wiring. If your reason for looking at Armeria is gRPC or Thrift on the same port as HTTP, the insertion path is the relevant one.

Maintenance, release cadence and licence terms

The repository is not archived, and the last push was on 2026-09-22, one day before this writing. The release history shows a steady cadence: 1.40.0 on 2026-06-18, 1.41.0 on 2026-08-07 and 1.41.1 on 2026-09-01. That is roughly a minor release every six to eight weeks with patch releases in between, which is a real upgrade cost for a framework whose modules are versioned together. A team pinning to 1.41.1 should expect to evaluate a new minor every couple of months, and the README provides no compatibility matrix to make that evaluation cheap.

Armeria is licensed under Apache-2.0, and the repository carries LICENSE.txt and NOTICE.txt at the top level. Apache-2.0 permits commercial and closed-source use and includes a patent grant. The NOTICE file exists because the project bundles or depends on other work, and that file is what a compliance review will want to read. This is a description of the licence text, not legal advice; a team with a formal open source review process should route LICENSE.txt and NOTICE.txt through it, along with the licences of the transitive Netty and protocol dependencies that the chosen modules pull in.

Editorial conclusion

Adopt Armeria if you already run Java services and want HTTP, gRPC and Thrift handled by one server and client stack instead of three. Do not adopt it if you need a non-JVM runtime, or if you want a framework that hides the transport layer; Armeria exposes it. Before committing, verify the published 1.41.1 artifacts on Maven Central, confirm which repository modules (grpc, thrift, spring-boot-minimal, proxy-server) map to your use case, and check that the Java 8 baseline matches your build toolchain.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. line/armeria on GitHub
3. Project website
4. README
5. Releases