Skip to content
Microserver is a Java 8 native, zero configuration, standards based, battle hardened library to run Java Rest Microservices via a standard Java main class. Supporting pure Microservice or Micro-monolith styles.
Java Groovy
Branch: master
Clone or download

Latest commit

Latest commit 310c178 Oct 29, 2019


Type Name Latest commit message Commit time
Failed to load latest commit information.
gradle/wrapper Add gradle-wrapper.jar for proper gradle version use. Nov 1, 2017
micro-application-register fix compile error Jul 1, 2019
micro-async-data-loader fix compile errors Nov 11, 2018
micro-async-data-writer fix compile errors Nov 11, 2018
micro-boot Code review changes Jul 1, 2019
micro-client increase conneciton timeout: Oct 27, 2019
micro-core Merge pull request #399 from aol/pathFix Oct 27, 2019
micro-cors Impl for #402 Nov 10, 2018
micro-couchbase fix compile errors Nov 11, 2018
micro-curator Impl for #402 Nov 10, 2018
micro-dbcp Impl for #402 Nov 10, 2018
micro-dist-lock Impl for #402 Nov 10, 2018
micro-elasticache Impl for #402 Nov 10, 2018
micro-error-codes fix compile errors Nov 11, 2018
micro-event-metrics change correlation id to string Jul 11, 2019
micro-events change correlation id to string Jul 11, 2019
micro-general-exception-mapper Impl for #402 Nov 10, 2018
micro-grizzly-with-jersey Merge pull request #399 from aol/pathFix Oct 27, 2019
micro-grizzly Merge pull request #399 from aol/pathFix Oct 27, 2019
micro-guava upgrade to latest cyclops 10.3.0 May 17, 2019
micro-hibernate remove spring data Nov 19, 2018
micro-hikaricp Impl for #402 Nov 10, 2018
micro-ip-tracker Impl for #402 Nov 10, 2018
micro-jackson-configuration add cyclops JSON Serialization and Deserialization May 17, 2019
micro-jdbc Impl for #402 Nov 10, 2018
micro-jersey Adding unit test for test GzipEncoder and Encoding filter registration Oct 24, 2019
micro-jmx-metrics Impl for #402 Nov 10, 2018
micro-log-streamer Impl for #402 Nov 10, 2018
micro-log4j Impl for #402 Nov 10, 2018
micro-logback Impl for #402 Nov 10, 2018
micro-machine-stats fix tests Oct 27, 2019
micro-manifest-comparator move to oathGroupId Nov 6, 2017
micro-metrics-datadog fix link in micro-metrics-datadog/ Apr 26, 2019
micro-metrics Impl for #402 Nov 10, 2018
micro-mysql fix compile errors Nov 11, 2018
micro-reactive fix compile errors Nov 11, 2018
micro-s3 factored to avoid code duplication Oct 29, 2019
micro-spring-boot debug test Jul 15, 2019
micro-swagger Impl for #402 Nov 10, 2018
micro-tomcat-with-jersey remove spring data Nov 19, 2018
micro-tomcat Merge pull request #399 from aol/pathFix Oct 27, 2019
micro-transactions wip Nov 12, 2018
micro-tutorial change correlation id to string Jul 11, 2019
.editorconfig Change java indentation to 4 spaces. Nov 2, 2017
.gitignore Add gradle-wrapper.jar for proper gradle version use. Nov 1, 2017
.gradletasknamecache fixed unit tests Mar 30, 2017
.travis.yml Update .travis.yml Oct 25, 2019
LICENSE Add .editorconfig to define code style. Add license. Clean gradle fil… Nov 1, 2017 Update Jul 18, 2019
build.gradle wip Nov 12, 2018 update version to 1.2.3 Oct 29, 2019
gradlew wip Nov 12, 2018
gradlew.bat wip Nov 12, 2018
settings.gradle build passing Nov 13, 2018


Build Status Join the chat at

A convenient modular engine for Microservices. Microserver plugins offer seamless integration with Spring (core), Jersey, Guava, Tomcat, Grizzly, reactive programming, Hibernate (& Spring Data), Spring Boot, Codahale Metrics, Swagger and more to come!

screen shot 2016-05-06 at 12 30 26 pm

Microserver plugins video

Getting started video

Quick start

Install Microserver with Grizzly, Jackson and Jersey (Gradle config below)

    compile group: 'com.oath.microservices', name:'micro-grizzly-with-jersey', version:'x.yz'

Install Microserver with Tomcat, Jackson and Jersey (Gradle config below)

   compile group: 'com.oath.microservices', name:'micro-tomcat-with-jersey', version:'x.yz'    

Create and run a simple app

   public class SimpleApp {

   	public static void main(String[] args){
   		new MicroserverApp(()->"test-app").run();
   	public String myEndPoint(){
   		return "hello world!";

Browse to http://localhost:8080/test-app/test

See the response hello world!

Add plugins by adding them to your build file - rerun the app to get new end points, Spring beans and more!

Easy to use async NIO based REST

Return any reactive-streams Publisher from your REST end point to make them execute asynchronously automatically.

E.g. Using Future from cyclops-react

   public Future<String> myEndPoint(){
          return Future.of(()->{
                                        return "hello world!";
                                        }, Executors.newFixedThreadPool(1));

Would be equivalent to the following code

 public void myEndPoint(@Suspended AsyncResponse asyncResponse){
                                           asyncResponse.resume("hello world!");
                                           return 1;
		}, Executors.newFixedThreadPool(1));

Why Microserver?

Microserver is a plugin engine for building Spring and Spring Boot based microservices. Microserver supports pure microservice and micro-monolith development styles. The micro-monolith style involves packaging multiple services into a single deployment - offering developers the productivity of microservice development without the operational risk. This can help teams adopt a Microservices architecture on projects that are currently monoliths.

Microserver plugins are orthogonal to Microservices. They solve a common problem in Microservice development whereby services are broken up and deployed separately but the code remains entangled in a monolithic common library. By making use of a plugin system that follows the same modular architectural principals as microservice development, teams can keep cross-service concerns and infrastructure in properly size, coherent and cohesive plugin modules.

Tutorial and overview


Tutorial code

Note on Fat Jars

Microserver (& Cyclops) have a plugin architecture and make use of the Java Service Loader mechanism. Make sure your Fat Jar implementation is configured to aggregate services. With the Gradle Shadow Jar you do this with

   shadowJar {

Quick start youtube video

Getting started video

Note the main launch class has been changed from MicroServerStartup to MicroserverApp


Microserver is a zero configuration, standards based, battle hardened library to run Java Rest Microservices via a standard Java main class. It has been used in production in AOL since July 2014.

Get Microserver

Build health

  • micro-grizzly-with-jersey Maven Central
  • micro-tomcat-with-jersey Maven Central
  • micro-core Maven Central
  • micro-boot : Microserver driving Spring Boot Maven Central
  • micro-spring-boot : Spring Boot driving Microserver Maven Central



Google Group

Example Apps : Microserver Core with Grizzly and Jersey

Example Apps : Microserver Boot

Java Doc : Microserver Core

Java Doc : Microserver Boot

Maven dependency

Microserver Grizzly with Jersey


Microserver Spring Boot


Gradle dependency

Microserver core

    compile group: 'com.oath.microservices', name:'micro-core', version:'x.yz'

Microserver Spring Boot

     compile group: 'com.oath.microservices', name:'micro-spring-boot', version:'x.yz'

Tech Stack

Microserver core is a lightweight server configuration engine built using Spring, Cyclops and Jackson.

Zero Configuration

No directory structure is imposed by the server and no XML is required. There is no framework config. Just a jar file and your application. You can, of course, configure your application without limit.

Example working application :-

The main class :-

     public class AppRunnerTest {

		public static void main(String[] args) throws InterruptedException {
			new MicroserverApp(() -> "test-app").run();


This will deploy a REST server on port 8080 (configurable by test-app.port in, it will also automagically capture any Rest end points (Spring & Jersey annotations) that implement the tag interface RestResource (see below for an example).

A rest end point

public class StatusResource {

    public String ping() {
        return "ok";


Configuration Options

If you find you need configuration options for your application you have two options.

  1. Override some of the available options on the Module interface (ConfigurableModule provides a builder mechanism for this)
  2. Implement a custom plugin (the cleanest option, which also promotes reuse across services).

Application configuration (for Grizzly with Jersey)

The core of Microserver is a Spring 4.x Dependency Injection container which is used to store all the main classes of your Microservice (s). The Spring Dependency Injection container can be configured by the @Microservice Annotation on your main class, or by the Config object (optionally passed as a parameter to startup).

Micro-monolith Architectural Overview

Each Microservice is a Jersey REST Application, these can be deployed independently as pure Microservices or together as a micro-monolith. Multiple Microservices can run on the same server, by adding them to the classpath at runtime. They share a common Spring Dependency Injection container (as they are smaller services, we feel it makes sense to share resources such as ThreadPools, Datasources etc), but act as totally separate Rest applications.

When creating embedded Microservices (multiple services colocated on the same JVM and Spring container), the development project should be independent, but the colocated instances should be tested as they will be deployed in production. There will be more info to follow on the wiki, on how and why we have implemented and scaled this pattern (the goal is to achieve both the benefits of a full Microservice architecture, but minimise the costs as articulated by Robert (Uncle Bob) C. Martin and others - e.g. here: Microservices and Jars .

Jersey REST Applications are configured by the Module interface (at least one of which must be specified on startup).

high level architecture

Rest configuration

The configuration of your Rest endpoints can be managed via the Module interface. The Module interface has a number of Java 8 default methods and a single abstract method (getContext). It behaves as a functional interface, and can be defined by a lambda expression. When used in this way the lambda represents the context the Microserver will create Rest end points on.


   new MicroserverApp(() -> "context").start();

() -> "context" is a Module!

Configurable Options

Module provides the following default methods, that clients can override

   default Map<String,String> getPropertyOverrides(){
   	return Maps.newHashMap();
   default Set<Class> getSpringConfigurationClasses(){
   	return Sets.newHashSet(Classes.CORE_CLASSES.getClasses());
   default List<Class> getRestResourceClasses() {
   	return Arrays.asList(RestResource.class);
   default List<Class> getRestAnnotationClasses() {
   	return Arrays.asList(Rest.class);
   default List<String> getDefaultJaxRsPackages(){
   	return Arrays.asList("com.wordnik.swagger.sample.resource",
   			"com.wordnik.swagger.sample.util"	);
   default List<Class> getDefaultResources(){
   	return Arrays.asList(JacksonFeature.class, 
   default List<ServletContextListener> getListeners(ServerData data){
   	return ImmutableList.of(new ContextLoaderListener(data
   			new JerseySpringIntegrationContextListener(data),
   			new SwaggerInitializer(data));
   default Map<String,Filter> getFilters(ServerData data) {
   	return ImmutableMap.of("/*",new QueryIPRetriever());
   default Map<String,Servlet> getServlets(ServerData data) {
   	return ImmutableMap.of();
   default  String getJaxWsRsApplication(){
   	return JerseyRestApplication.class.getCanonicalName();
   default String getProviders(){
   	return "";

RestResource class defines the tag interface used to identify Rest end points for this module.

Filters provides a map of Servlet filters and the paths to which they should be applied

Providers allows client code to change the Jersey Providers packages

JaxWsRsApplication allows client code to completely override the Microserver

Property file configuration

Microserver supports auto-discovery of Microserver will assume a default file name of ''. Microserver will check for a properties in the following order

  1. System property '' and if present will load the property file from disk using that.

  2. Otherwise, Microserver will look for a System Property 'application.env' and will load the application property file from the classpath using the resource name 'application-${application.env}.properties.

  3. Alternatively, Microserver will load directly from the classpath.

  4. If still not found Microserver will load from disk in the current directory

The default file name can be configured by exception (use PropertyFileConfig.setApplicationPropertyFileName(String filename).

Microserver application properties loading is configured by the class PropertyFileConfig. You can replace this with your own Spring configuration file to load property files by a different set of rules (by passing in your class to the constructor of Microserver).

Embed and colocate Microservices

Microserver supports the embedding of multiple microservices within a single Microserver, this is not the default mode of operation and involves a little more work to setup. All Microservices will share a single Spring context, so some care needs to be taken when authoring such Microservices to avoid conflicts. This does mean that they can share resources (such as database connections) where it makes sense to do so.

Embedded microservices should be collated at '''runtime only'''. There should be no compile time dependency between embedded microservices (otherwise you are not building microservices but a monolithic application).

Embedding microservices is an optimisation that allows better performance, enhanced robustness and reliability and easier management of microservices - while still maintaining the advantages of horizontal scalability offered by the microservices approach.

Embedded Microservices example

This example will start two different Rest endpoints - one on context "test-app" and another on context "alternative-app". "test-app" will automagically wire in any Jersey endpoints that implement TestAppRestResource. "alternative-app" will automagically wire in any Jersey endpoints that implement AltAppRestResource.

   public class EmbeddedAppRunnerTest {
   	public static void main(String[] args) throws InterruptedException {
   		new MicroserverApp(EmbeddedAppRunnerTest.class, 
   				new EmbeddedModule(TestAppRestResource.class,"test-app"),
   				new EmbeddedModule(AltAppRestResource.class,"alternative-app")).start();

Building a 'fat' Jar

We recommend the Gradle plugin Shadow Jar. For Gradle 2.0 simply define it in your plugins section ->

plugins {
 id 'java' // or 'groovy' Must be explicitly applied
 id 'com.github.johnrengelman.shadow' version '1.2.0'

Maven users can use Shade plugin or equivalent (Maven assembly plugin).

Thanks to our Sponsors

You can’t perform that action at this time.