Setting up a project

Requirements

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

Note

Use Java 11 (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-grpc	gRPC client and server support. See Running a gRPC service and Calling a gRPC service.
armeria-jetty	Embedded Jetty Servlet container. See Embedding a servlet container.
armeria-kafka	Enables sending access logs to Kafka
armeria-logback	Provides Logback Appender implementation that adds request information. See Logging contextual information.
armeria-retrofit2	Allows using Armeria instead of OkHttp as transport layer when using Retrofit. See Retrofit integration.
armeria-rxjava	RxJava plugin
armeria-saml	SAML support
armeria-spring-boot-autoconfigure	Spring Boot integration
armeria-spring-boot-webflux-autoconfigure	Spring Boot WebFlux integration. See Using Armeria with Spring WebFlux.
armeria-thrift	Thrift client and server support. See Running a Thrift service and Calling a Thrift service.
armeria-tomcat	Embedded Tomcat Servlet container. See Embedding a servlet container.
armeria-zipkin	Zipkin distributed tracing support. See Zipkin integration.
armeria-zookeeper	ZooKeeper-based service discovery. See Service discovery with ZooKeeper.

Setting up with Gradle

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

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

repositories {
    mavenCentral()
}

dependencies {
    // Adjust the list as you need.
    ['armeria',
     'armeria-grpc',
     'armeria-jetty',
     'armeria-kafka',
     'armeria-logback',
     'armeria-retrofit2',
     'armeria-rxjava',
     'armeria-saml',
     'armeria-thrift',
     'armeria-tomcat',
     'armeria-zipkin',
     'armeria-zookeeper'].each {
        compile "com.linecorp.armeria:${it}:0.88.0"
    }

    // Logging
    runtime 'ch.qos.logback:logback-classic:1.2.3'
    runtime 'org.slf4j:log4j-over-slf4j:1.7.26'
}

Setting up with Maven

You might want to use the following pom.xml as a starting point when you set up a new project:

<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>0.88.0</version>
    </dependency>
    <dependency>
      <groupId>com.linecorp.armeria</groupId>
      <artifactId>armeria-grpc</artifactId>
      <version>0.88.0</version>
    </dependency>
    <dependency>
      <groupId>com.linecorp.armeria</groupId>
      <artifactId>armeria-jetty</artifactId>
      <version>0.88.0</version>
    </dependency>
    <dependency>
      <groupId>com.linecorp.armeria</groupId>
      <artifactId>armeria-kafka</artifactId>
      <version>0.88.0</version>
    </dependency>
    <dependency>
      <groupId>com.linecorp.armeria</groupId>
      <artifactId>armeria-logback</artifactId>
      <version>0.88.0</version>
    </dependency>
    <dependency>
      <groupId>com.linecorp.armeria</groupId>
      <artifactId>armeria-retrofit2</artifactId>
      <version>0.88.0</version>
    </dependency>
    <dependency>
      <groupId>com.linecorp.armeria</groupId>
      <artifactId>armeria-rxjava</artifactId>
      <version>0.88.0</version>
    </dependency>
    <dependency>
      <groupId>com.linecorp.armeria</groupId>
      <artifactId>armeria-saml</artifactId>
      <version>0.88.0</version>
    </dependency>
    <dependency>
      <groupId>com.linecorp.armeria</groupId>
      <artifactId>armeria-thrift</artifactId>
      <version>0.88.0</version>
    </dependency>
    <dependency>
      <groupId>com.linecorp.armeria</groupId>
      <artifactId>armeria-tomcat</artifactId>
      <version>0.88.0</version>
    </dependency>
    <dependency>
      <groupId>com.linecorp.armeria</groupId>
      <artifactId>armeria-zipkin</artifactId>
      <version>0.88.0</version>
    </dependency>
    <dependency>
      <groupId>com.linecorp.armeria</groupId>
      <artifactId>armeria-zookeeper</artifactId>
      <version>0.88.0</version>
    </dependency>

    <!-- Logging -->
    <dependency>
      <groupId>ch.qos.logback</groupId>
      <artifactId>logback-classic</artifactId>
      <version>1.2.3</version>
      <scope>runtime</scope>
    </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>log4j-over-slf4j</artifactId>
      <version>1.7.26</version>
      <scope>runtime</scope>
    </dependency>
  </dependencies>
</project>

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 to learn more about what Maven BOM is and how to use it.