Setting up a project

Requirements

Java 8 (or later) is required to build and run an application based on Armeria.

tip

Use Java 19 (or later) if you are a contributor who tries to build Armeria itself. See CONTRIBUTING.md for more information.

Choosing the artifacts

All Armeria JARs are available in Maven Central Repository under group ID com.linecorp.armeria so that you can fetch them easily using your favorite build tool. Add the Armeria artifacts that provide the desired functionality to your project dependencies. The following is the list of major Armeria artifacts which might interest you:

Artifact ID	Description
`armeria`	The core library.
`armeria-brave`	Distributed tracing with Brave. See Zipkin integration.
`armeria-bucket4j`	Support Bucket4j based `ThrottlingStrategy`.
`armeria-consul`	Consul based service discovery. See Consul service discovery and Consul service registration.
`armeria-dropwizard2`	Provides a Dropwizard 2 Bundle around `armeria-jetty9`. See Using Armeria with Dropwizard.
`armeria-eureka`	Eureka based service discovery. See Eureka service discovery and Eureka service registration.
`armeria-graphql`	GraphQL service support. See Running a GraphQL service.
`armeria-grpc` and `armeria-grpc-kotlin`	gRPC client and server support. See Running a gRPC service and Calling a gRPC service.
`armeria-jetty11`	Embedded Jetty 11 Servlet container. See Embedding a servlet container.
`armeria-kafka`	Enables sending access logs to Kafka
`armeria-kotlin`	Kotlin support. See Kotlin coroutines support.
`armeria-logback14`	Provides Logback `Appender` implementation that adds request information. See Logging contextual information.
`armeria-oauth2`	Support OAuth 2.0.
`armeria-protobuf`	Support Protocol Buffers in annotated service.
`armeria-retrofit2`	Allows using Armeria instead of OkHttp as transport layer when using Retrofit2. See Retrofit integration.
`armeria-reactor3`	Project Reactor plugin
`armeria-resilience4j2`	Support Resilience4j Circuit Breaker integration.
`armeria-resteasy`	Support RESTEasy integration.
`armeria-rxjava3`	RxJava 3 plugin
`armeria-saml`	SAML support
`armeria-scalapb_2.12` and `armeria-scalapb_2.13`	Support ScalaPB for gRPC and annotated service.
`armeria-spring-boot3-actuator`	Spring Boot 3 Actuator integration. See Actuator support.
`armeria-spring-boot3-autoconfigure`	Spring Boot 3 integration. See Spring Boot integration.
`armeria-spring-boot3-webflux-autoconfigure`	Spring Boot 3 WebFlux integration. See Using Armeria with Spring WebFlux.
`armeria-thrift0.18`	Thrift 0.18 client and server support. See Running a Thrift service and Calling a Thrift service.
`armeria-tomcat10`	Embedded Tomcat 10 Servlet container. See Embedding a servlet container.
`armeria-zookeeper3`	ZooKeeper 3 based service discovery. See ZooKeeper service discovery and ZooKeeper service registration.

Setting up with a build system

You might want to use the following build file as a starting point when you set up a new project:

Gradle
Gradle (Kotlin)
Maven

build.gradle

  apply plugin: 'java'
  apply plugin: 'idea'
  apply plugin: 'eclipse'

  repositories {
      mavenCentral()
  }

  dependencies {
      // Adjust the list as you need.
      ['armeria',
      'armeria-brave',
      'armeria-grpc',
      'armeria-jetty11',
      'armeria-kafka',
      'armeria-logback12',
      'armeria-retrofit2',
      'armeria-rxjava3',
      'armeria-saml',
      'armeria-thrift0.18',
      'armeria-tomcat10',
      'armeria-zookeeper3'].each {
          implementation "com.linecorp.armeria:${it}:1.35.0"
      }

      // Logging
      runtimeOnly 'ch.qos.logback:logback-classic:1.5.23'
  }
  

build.gradle.kts

  apply(plugin = "java")
  apply(plugin = "idea")
  apply(plugin = "eclipse")

  repositories {
      mavenCentral()
  }

  dependencies {
      // Adjust the list as you need.
      listOf(
          "armeria",
          "armeria-brave",
          "armeria-grpc",
          "armeria-jetty9",
          "armeria-kafka",
          "armeria-logback",
          "armeria-retrofit2",
          "armeria-rxjava3",
          "armeria-saml",
          "armeria-thrift0.13",
          "armeria-tomcat9",
          "armeria-zookeeper3").forEach {
          implementation("com.linecorp.armeria:${it}:1.35.0")
      }

      // Logging
      runtimeOnly("ch.qos.logback:logback-classic:1.5.23")
  }
  

pom.xml

  <project xmlns="http://maven.apache.org/POM/4.0.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>myproject</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>
    <name>myproject</name>
    <url>https://example.com/</url>

    <properties>
      <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
      <dependency>
        <groupId>com.linecorp.armeria</groupId>
        <artifactId>armeria</artifactId>
        <version>1.35.0</version>
      </dependency>
      <dependency>
        <groupId>com.linecorp.armeria</groupId>
        <artifactId>armeria-brave</artifactId>
        <version>1.35.0</version>
      </dependency>
      <dependency>
        <groupId>com.linecorp.armeria</groupId>
        <artifactId>armeria-grpc</artifactId>
        <version>1.35.0</version>
      </dependency>
      <dependency>
        <groupId>com.linecorp.armeria</groupId>
        <artifactId>armeria-jetty9</artifactId>
        <version>1.35.0</version>
      </dependency>
      <dependency>
        <groupId>com.linecorp.armeria</groupId>
        <artifactId>armeria-kafka</artifactId>
        <version>1.35.0</version>
      </dependency>
      <dependency>
        <groupId>com.linecorp.armeria</groupId>
        <artifactId>armeria-logback</artifactId>
        <version>1.35.0</version>
      </dependency>
      <dependency>
        <groupId>com.linecorp.armeria</groupId>
        <artifactId>armeria-retrofit2</artifactId>
        <version>1.35.0</version>
      </dependency>
      <dependency>
        <groupId>com.linecorp.armeria</groupId>
        <artifactId>armeria-rxjava3</artifactId>
        <version>1.35.0</version>
      </dependency>
      <dependency>
        <groupId>com.linecorp.armeria</groupId>
        <artifactId>armeria-saml</artifactId>
        <version>1.35.0</version>
      </dependency>
      <dependency>
        <groupId>com.linecorp.armeria</groupId>
        <artifactId>armeria-thrift0.13</artifactId>
        <version>1.35.0</version>
      </dependency>
      <dependency>
        <groupId>com.linecorp.armeria</groupId>
        <artifactId>armeria-tomcat9</artifactId>
        <version>1.35.0</version>
      </dependency>
      <dependency>
        <groupId>com.linecorp.armeria</groupId>
        <artifactId>armeria-zookeeper3</artifactId>
        <version>1.35.0</version>
      </dependency>
      <!-- Logging -->
      <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.5.23</version>
        <scope>runtime</scope>
      </dependency>
    </dependencies>
  </project>
  

Configure `-parameters` javac option

You can configure your build tool to add -parameters javac option as follows.

Gradle
Gradle (Kotlin)
Maven

build.gradle

  tasks.withType(JavaCompile) {
      options.compilerArgs += '-parameters'
  }
  

build.gradle.kts

  tasks.withType<JavaCompile> {
      options.compilerArgs.add("-parameters")
  }
  

pom.xml

  <project>
    <build>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <configuration>
            <compilerArgs>
              <arg>-parameters</arg>
            </compilerArgs>
          </configuration>
        </plugin>
      </plugins>
    </build>
  </project>
  

IntelliJ IDEA

Go to Preferences > Build, Execution, Deployment > Compiler > Java Compiler and add -parameters to Additional command line parameters.

Using Maven BOM for simpler dependency management

You can import com.linecorp.armeria:armeria-bom into your build rather than specifying Armeria versions in more than one place. See this article for Gradle and this article for Maven to learn more about what Maven BOM is and how to use it.

Requirements​

Choosing the artifacts​

Setting up with a build system​

Configure -parameters javac option​

IntelliJ IDEA​

Using Maven BOM for simpler dependency management​