Micronaut Launch

Generates Micronaut applications

Version:

1 Introduction

This project implements a project generator for Micronaut as is both a Command Line (CLI) application and an API that can be run as a HTTP server, deployed to a Servlet container or executed on a Serverless platform (Google Cloud Run, Google Cloud Function, AWS Lambda or Azure Function).

2 Installation

2.1 Install with SDKman

The best way to install Micronaut on Unix systems is with SDKMAN which greatly simplifies installing and managing multiple Micronaut versions.

Before updating make sure you have latest version of SDKMAN installed. If not, run

$ sdk update

In order to install Micronaut, run following command:

$ sdk install micronaut

You can also specify the version to the sdk install command.

$ sdk install micronaut {project-version}

You can find more information about SDKMAN usage on the SDKMAN Docs

You should now be able to run the Micronaut CLI.

$ mn
| Starting interactive mode...
| Enter a command name to run. Use TAB for completion:
mn>

2.2 Install with Homebrew

In order to install Micronaut, run following command:

$ brew cask install micronaut-projects/tap/micronaut

You can find more information about Homebrew usage on their homepage.

You should now be able to run the Micronaut CLI.

$ mn
| Starting interactive mode...
| Enter a command name to run. Use TAB for completion:
mn>

2.3 Install with Chocolatey

If using Windows, you can use Chocolatey to install the Micronaut CLI:

$ choco install micronaut

Check the micronaut package page for more information.

You should now be able to run the Micronaut CLI from the command prompt or Powershell by running mn:

$ mn
| Starting interactive mode...
| Enter a command name to run. Use TAB for completion:
mn>

3 Release History

2.0.0.M3

  • Initial Milestone Release

4 Available commands

Name

mn - Micronaut CLI command line interface for generating projects and services.

Synopsis

mn [-hvVx] [COMMAND]

Description

Micronaut CLI command line interface for generating projects and services. Application generation commands are:

  • create-app NAME

  • create-cli-app NAME

  • create-function-app NAME

  • create-grpc-app NAME

  • create-messaging-app NAME

Options

-h, --help

Show this help message and exit.

-v, --verbose

Create verbose output.

-V, --version

Print version information and exit.

-x, --stacktrace

Show full stack trace when exceptions occur.

Commands

create-app

Creates an application

create-cli-app

Creates a CLI application

create-function-app

Creates a Cloud Function

create-grpc-app

Creates a gRPC application

create-messaging-app

Creates a messaging application

create-app

Name

mn-create-app - Creates an application

Synopsis

mn create-app [-hivVx] [--list-features] [-b=BUILD-TOOL] [--jdk=<javaVersion>] [-l=LANG] [-t=TEST] [-f=FEATURE[,FEATURE…​]]…​ [NAME]

Description

Creates an application

Options

-b, --build=BUILD-TOOL

Which build tool to configure. Possible values: gradle, maven.

-f, --features=FEATURE[,FEATURE…​]

The features to use. Possible values: jdbc-dbcp, jdbc-hikari, jdbc-tomcat, jdbc-ucp, flyway, dekorate-prometheus, graalvm, views-handlebars, nats, postgres, micrometer-ganglia, oracle, hibernate-jpa, vertx-pg-client, data-jdbc, dekorate-kubernetes, jib, cassandra, logback, asciidoctor, tracing-zipkin, h2, oracle-function, mongo-reactive, security-ldap, mysql, micrometer-influx, micrometer-kairos, micrometer-azure-monitor, micrometer-elastic, micrometer-atlas, jrebel, vertx-mysql-client, google-cloud-function, acme, rxjava1, jackson-xml, dekorate-servicecatalog, multi-tenancy-gorm, micrometer-cloudwatch, discovery-consul, cache-infinispan, hibernate-gorm, security, gcp-cloud-trace, netflix-archaius, aws-alexa, aws-lambda, slf4j-simple, micrometer-datadog, security-jwt, micrometer-dynatrace, cache-caffeine, aws-lambda-custom-runtime, discovery-eureka, config-kubernetes, micrometer-prometheus, micrometer-appoptics, tracing-jaeger, http-client, multi-tenancy, ktor, dekorate-openshift, rxjava3, reactor, micrometer-jmx, redis-lettuce, tomcat-server, neo4j-gorm, undertow-server, mongo-sync, mongo-gorm, mariadb, micrometer-graphite, knative, elasticsearch, jetty-server, cache-hazelcast, sql-jdbi, graphql, security-oauth2, kotlin-extension-functions, micrometer-signalfx, rss, data-jpa, views-velocity, views-soy, kafka-streams, aws-v2-sdk, testcontainers, cache-ehcache, neo4j-bolt, spring-web, micrometer-wavefront, spring-data-jdbc, management, spring, jooq, oracle-cloud-sdk, azure-function, log4j2, micrometer-new-relic, spring-boot, netflix-hystrix, config-consul, rss-itunes-podcast, sqlserver, gcp-pubsub, spring-data-jpa, kubernetes, views-thymeleaf, openapi, dekorate-halkyon, views-rocker, micrometer-humio, dekorate-knative, micrometer-statsd, netty-server, shade, views-freemarker, hibernate-validator, security-session, jax-rs, jmx, liquibase, dekorate-jaeger, kafka, micrometer-stackdriver, rabbitmq, springloaded, netflix-ribbon, config4k, properties

-h, --help

Show this help message and exit.

-i, --inplace

Create a service using the current directory

--jdk, --java-version=<javaVersion>

The JDK version the project should target

-l, --lang=LANG

Which language to use. Possible values: java, groovy, kotlin.

--list-features

Output the available features and their descriptions

-t, --test=TEST

Which test framework to use. Possible values: junit, spock, kotest.

-v, --verbose

Create verbose output.

-V, --version

Print version information and exit.

-x, --stacktrace

Show full stack trace when exceptions occur.

Arguments

[NAME]

The name of the application to create.

create-cli-app

Name

mn-create-cli-app - Creates a CLI application

Synopsis

mn create-cli-app [-hivVx] [--list-features] [-b=BUILD-TOOL] [--jdk=<javaVersion>] [-l=LANG] [-t=TEST] [-f=FEATURE[, FEATURE…​]]…​ [NAME]

Description

Creates a CLI application

Options

-b, --build=BUILD-TOOL

Which build tool to configure. Possible values: gradle, maven.

-f, --features=FEATURE[,FEATURE…​]

The features to use. Possible values: jdbc-dbcp, jdbc-hikari, jdbc-tomcat, jdbc-ucp, flyway, graalvm, nats, postgres, oracle, hibernate-jpa, vertx-pg-client, data-jdbc, jib, cassandra, logback, asciidoctor, h2, mongo-reactive, security-ldap, mysql, jrebel, vertx-mysql-client, rxjava1, jackson-xml, multi-tenancy-gorm, cache-infinispan, hibernate-gorm, security, gcp-cloud-trace, slf4j-simple, security-jwt, cache-caffeine, http-client, multi-tenancy, rxjava3, reactor, redis-lettuce, neo4j-gorm, mongo-sync, mongo-gorm, mariadb, elasticsearch, cache-hazelcast, sql-jdbi, graphql, security-oauth2, kotlin-extension-functions, data-jpa, kafka-streams, aws-v2-sdk, testcontainers, cache-ehcache, neo4j-bolt, spring-data-jdbc, spring, jooq, oracle-cloud-sdk, log4j2, spring-boot, netflix-hystrix, sqlserver, gcp-pubsub, spring-data-jpa, shade, hibernate-validator, security-session, liquibase, kafka, rabbitmq, springloaded, netflix-ribbon, config4k, properties

-h, --help

Show this help message and exit.

-i, --inplace

Create a service using the current directory

--jdk, --java-version=<javaVersion>

The JDK version the project should target

-l, --lang=LANG

Which language to use. Possible values: java, groovy, kotlin.

--list-features

Output the available features and their descriptions

-t, --test=TEST

Which test framework to use. Possible values: junit, spock, kotest.

-v, --verbose

Create verbose output.

-V, --version

Print version information and exit.

-x, --stacktrace

Show full stack trace when exceptions occur.

Arguments

[NAME]

The name of the application to create.

create-function-app

Name

mn-create-function-app - Creates a Cloud Function

Synopsis

mn create-function-app [-hivVx] [--list-features] [-b=BUILD-TOOL] [--jdk=<javaVersion>] [-l=LANG] [-t=TEST] [-f=FEATURE[, FEATURE…​]]…​ [NAME]

Description

Creates a Cloud Function

Options

-b, --build=BUILD-TOOL

Which build tool to configure. Possible values: gradle, maven.

-f, --features=FEATURE[,FEATURE…​]

The features to use. Possible values: jdbc-dbcp, jdbc-hikari, jdbc-tomcat, jdbc-ucp, flyway, graalvm, nats, postgres, oracle, hibernate-jpa, vertx-pg-client, data-jdbc, jib, cassandra, logback, asciidoctor, tracing-zipkin, h2, oracle-function, mongo-reactive, security-ldap, mysql, jrebel, vertx-mysql-client, google-cloud-function, rxjava1, jackson-xml, multi-tenancy-gorm, discovery-consul, cache-infinispan, hibernate-gorm, security, gcp-cloud-trace, netflix-archaius, aws-alexa, aws-lambda, slf4j-simple, security-jwt, cache-caffeine, aws-lambda-custom-runtime, discovery-eureka, tracing-jaeger, http-client, multi-tenancy, rxjava3, reactor, redis-lettuce, neo4j-gorm, mongo-sync, mongo-gorm, mariadb, elasticsearch, cache-hazelcast, sql-jdbi, graphql, security-oauth2, kotlin-extension-functions, data-jpa, kafka-streams, aws-v2-sdk, testcontainers, cache-ehcache, neo4j-bolt, spring-data-jdbc, spring, jooq, oracle-cloud-sdk, azure-function, log4j2, spring-boot, netflix-hystrix, config-consul, sqlserver, gcp-pubsub, spring-data-jpa, shade, hibernate-validator, security-session, liquibase, kafka, rabbitmq, springloaded, netflix-ribbon, config4k, properties

-h, --help

Show this help message and exit.

-i, --inplace

Create a service using the current directory

--jdk, --java-version=<javaVersion>

The JDK version the project should target

-l, --lang=LANG

Which language to use. Possible values: java, groovy, kotlin.

--list-features

Output the available features and their descriptions

-t, --test=TEST

Which test framework to use. Possible values: junit, spock, kotest.

-v, --verbose

Create verbose output.

-V, --version

Print version information and exit.

-x, --stacktrace

Show full stack trace when exceptions occur.

Arguments

[NAME]

The name of the application to create.

create-grpc-app

Name

mn-create-grpc-app - Creates a gRPC application

Synopsis

mn create-grpc-app [-hivVx] [--list-features] [-b=BUILD-TOOL] [--jdk=<javaVersion>] [-l=LANG] [-t=TEST] [-f=FEATURE[, FEATURE…​]]…​ [NAME]

Description

Creates a gRPC application

Options

-b, --build=BUILD-TOOL

Which build tool to configure. Possible values: gradle, maven.

-f, --features=FEATURE[,FEATURE…​]

The features to use. Possible values: jdbc-dbcp, jdbc-hikari, jdbc-tomcat, jdbc-ucp, flyway, dekorate-prometheus, graalvm, nats, postgres, oracle, hibernate-jpa, vertx-pg-client, data-jdbc, dekorate-kubernetes, jib, cassandra, logback, asciidoctor, tracing-zipkin, h2, mongo-reactive, security-ldap, mysql, jrebel, vertx-mysql-client, rxjava1, jackson-xml, dekorate-servicecatalog, multi-tenancy-gorm, discovery-consul, cache-infinispan, hibernate-gorm, security, gcp-cloud-trace, netflix-archaius, slf4j-simple, security-jwt, cache-caffeine, discovery-eureka, config-kubernetes, tracing-jaeger, http-client, multi-tenancy, dekorate-openshift, rxjava3, reactor, redis-lettuce, neo4j-gorm, mongo-sync, mongo-gorm, mariadb, knative, elasticsearch, cache-hazelcast, sql-jdbi, graphql, security-oauth2, kotlin-extension-functions, data-jpa, kafka-streams, aws-v2-sdk, testcontainers, cache-ehcache, neo4j-bolt, spring-data-jdbc, spring, jooq, oracle-cloud-sdk, log4j2, spring-boot, netflix-hystrix, config-consul, sqlserver, gcp-pubsub, spring-data-jpa, kubernetes, dekorate-halkyon, dekorate-knative, shade, hibernate-validator, security-session, liquibase, dekorate-jaeger, kafka, rabbitmq, springloaded, netflix-ribbon, config4k, properties

-h, --help

Show this help message and exit.

-i, --inplace

Create a service using the current directory

--jdk, --java-version=<javaVersion>

The JDK version the project should target

-l, --lang=LANG

Which language to use. Possible values: java, groovy, kotlin.

--list-features

Output the available features and their descriptions

-t, --test=TEST

Which test framework to use. Possible values: junit, spock, kotest.

-v, --verbose

Create verbose output.

-V, --version

Print version information and exit.

-x, --stacktrace

Show full stack trace when exceptions occur.

Arguments

[NAME]

The name of the application to create.

create-messaging-app

Name

mn-create-messaging-app - Creates a messaging application

Synopsis

mn create-messaging-app [-hivVx] [--list-features] [-b=BUILD-TOOL] [--jdk=<javaVersion>] [-l=LANG] [-t=TEST] [-f=FEATURE[, FEATURE…​]]…​ [NAME]

Description

Creates a messaging application

Options

-b, --build=BUILD-TOOL

Which build tool to configure. Possible values: gradle, maven.

-f, --features=FEATURE[,FEATURE…​]

The features to use. Possible values: jdbc-dbcp, jdbc-hikari, jdbc-tomcat, jdbc-ucp, flyway, graalvm, nats, postgres, oracle, hibernate-jpa, vertx-pg-client, data-jdbc, jib, cassandra, logback, asciidoctor, tracing-zipkin, h2, mongo-reactive, security-ldap, mysql, jrebel, vertx-mysql-client, rxjava1, jackson-xml, multi-tenancy-gorm, discovery-consul, cache-infinispan, hibernate-gorm, security, gcp-cloud-trace, netflix-archaius, slf4j-simple, security-jwt, cache-caffeine, discovery-eureka, config-kubernetes, tracing-jaeger, http-client, multi-tenancy, rxjava3, reactor, redis-lettuce, neo4j-gorm, mongo-sync, mongo-gorm, mariadb, elasticsearch, cache-hazelcast, sql-jdbi, graphql, security-oauth2, kotlin-extension-functions, data-jpa, kafka-streams, aws-v2-sdk, testcontainers, cache-ehcache, neo4j-bolt, spring-data-jdbc, spring, jooq, oracle-cloud-sdk, log4j2, spring-boot, netflix-hystrix, config-consul, sqlserver, gcp-pubsub, spring-data-jpa, shade, hibernate-validator, security-session, liquibase, kafka, rabbitmq, springloaded, netflix-ribbon, config4k, properties

-h, --help

Show this help message and exit.

-i, --inplace

Create a service using the current directory

--jdk, --java-version=<javaVersion>

The JDK version the project should target

-l, --lang=LANG

Which language to use. Possible values: java, groovy, kotlin.

--list-features

Output the available features and their descriptions

-t, --test=TEST

Which test framework to use. Possible values: junit, spock, kotest.

-v, --verbose

Create verbose output.

-V, --version

Print version information and exit.

-x, --stacktrace

Show full stack trace when exceptions occur.

Arguments

[NAME]

The name of the application to create.

5 Micronaut Launch

The core functionality of the project generator is contained within the micronaut-starter-core subproject:

implementation("io.micronaut.starter:micronaut-starter-core:2.1.2")
<dependency>
    <groupId>io.micronaut.starter</groupId>
    <artifactId>micronaut-starter-core</artifactId>
    <version>2.1.2</version>
</dependency>

5.1 CLI Application

The subproject starter-cli provides an implementation that can be run as a Command Line Application (CLI).

Building Locally

From the project root:

./gradlew clean micronaut-cli:assemble

Now you can run the following the start the CLI in interactive mode:

java -jar starter-cli/build/libs/micronaut-cli-2.1.2-all.jar

Building a Native Image

Install GraalVM and Native Image. Follow the steps in the previous section to build the CLI and then run:

native-image --no-fallback -cp starter-cli/build/libs/micronaut-cli-2.1.2-all.jar

This will produce the mn executable which you can start with:

./mn

5.2 OpenAPI Specification

This project uses Micronaut’s OpenAPI support to generate an OpenAPI specification; a broadly adopted industry standard to describe APIs.

Run:

$ ./gradlew starter-api:classes

You can open the OPEN API specification in YAML format:

$ open starter-api/build/classes/java/main/META-INF/swagger/micronaut-starter-1.0.yml

5.3 Web API Application

The subproject starter-web-netty provides an implementation that runs on Netty.

Running the Application locally

From the project root:

./gradlew clean starter-web-netty:run

You can view the Swagger UI definition at:

Or with RapiDoc:

Deploying the Application

You can build the WAR file with:

./gradlew clean starter-web-netty:shadowJar

A runnable JAR file will be located in starter-web-servlet/build/libs:

$ java -jar starter-web-netty/build/libs/starter-web-netty-2.1.2-all.jar

5.4 Micronaut Launch React UI

The UI for Micronaut Launch is written in React and the sources can be found here as a separate project.

5.5 WAR Deployment

The subproject starter-web-servlet provides an implementation that can be deployed to any recent Servlet 4+ container (Tomcat 9, Jetty 9 etc.).

Running the Application locally

From the project root:

./gradlew clean starter-web-servlet:run

You can view the Swagger UI definition at:

Or with RapiDoc:

Deploying the Application

You can build the WAR file with:

./gradlew clean starter-web-servlet:assemble

The WAR file will be located in starter-web-servlet/build/libs and can be deployed to any modern Servlet container (example Jetty 9 or Tomcat 9).

5.6 Google Cloud Run

The subproject starter-web-netty provides an implementation that can be continuously deployed to Cloud Run as a GraalVM native image.

Running the Application Locally

Install GraalVM and the native image tool and then run:

$ docker build . -t micronaut-starter -f DockerfileCloudRun
$ docker run -p 8080:8080 micronaut-starter

Continuous Deployment

Micronaut Starter is continuously deployed to Google Cloud Run as a native GraalVM application using Github Actions.

The Snapshot to GCR Workflow (defined by .github/workflows/gcr-snapshot.yml) deploys the application on each commit and the application can be accessed at the following URL:

Deploying the Application

To build and deploy the project yourself install setup the Google Cloud CLI then from the project root build the docker image and push it to Google Container Registry:

$ docker build . -t micronaut-starter -f DockerfileCloudRun
$ docker tag micronaut-starter gcr.io/[PROJECT ID]/micronaut-starter
$ docker push gcr.io/[PROJECT ID]/micronaut-starter

You are now ready to deploy your application:

$ gcloud beta run deploy --image gcr.io/[PROJECT ID]/micronaut-starter

Where [PROJECT ID] is replaced for your project ID. You should see output like the following:

Service name: (micronaut-starter):
Deploying container to Cloud Run service [micronaut-starter] in project [PROJECT_ID] region [us-central1]

✓ Deploying... Done.
  ✓ Creating Revision...
  ✓ Routing traffic...
Done.
Service [micronaut-starter] revision [micronaut-starter-00004] has been deployed and is serving traffic at https://micronaut-starter-xxxxxxx-uc.a.run.app

The URL is the URL of your Cloud Run application.

5.7 Google Cloud Function

The subproject starter-gcp-function provides a function that can be deployed to Google Cloud Function.

Running the Function Locally

To run the function locally run:

./gradlew clean starter-gcp-function:runFunction

Continuous Deployment

Micronaut Starter API is continuously deployed to Google Cloud Function as a Serverless Java application.

The Snapshot to GCF Workflow (defined by .github/workflows/gcf-snapshot.yml) deploys the application on each commit and the API can be accessed at the following URL:

Deploying the Function Yourself

To deploy the function first build the function with:

$ ./gradlew clean starter-gcp-function:shadowJar

Then cd into the starter-gcp-function/build/libs directory (deployment has to be done from the location where the JAR lives):

$ cd starter-gcp-function/build/libs

Now run:

$ gcloud alpha functions deploy micronaut-starter --entry-point io.micronaut.gcp.function.http.HttpFunction --runtime java11 --trigger-http

Choose unauthenticated access if you don’t need auth.

To obtain the trigger URL do the following:

$ YOUR_HTTP_TRIGGER_URL=$(gcloud alpha functions describe micronaut-starter --format='value(httpsTrigger.url)')

You can then use this variable to test the function invocation:

$ curl -i $YOUR_HTTP_TRIGGER_URL/create/app/example -o application.zip

5.8 AWS Lambda

The subproject starter-aws-lambda provides a function that can be deployed to AWS Lambda as a GraalVM native image.

Running the Lambda Locally

From the root of the project run:

$ docker build . -f DockerfileLambda -t micronaut-starter
$ mkdir -p build
$ docker run --rm --entrypoint cat micronaut-starter  /home/application/function.zip > build/function.zip

Then start the function with SAM (https://github.com/awslabs/aws-sam-cli).

$ sam local start-api --template sam-local.yml

Continuous Deployment

The Micronaut Starter API is continuously deployed by Github Actions to AWS Lambda as a Serverless GraalVM native application using a custom AWS Lambda Runtime .

The Snapshot to AWS Lambda Workflow (defined by .github/workflows/gcf-snapshot.yml) deploys the application on each commit and the API can be accessed at the following URL:

5.9 Microsoft Azure

The subproject starter-azure-function provides a function that can be deployed to Microsoft Azure.

Running the Function Locally

First uncomment the Azure plugin from starter-azure-function/build.grade:

./gradlew clean starter-azure-function:azureFunctionsRun

Continuous Deployment

Micronaut Starter API is continuously deployed to Azure Function as a Serverless Java application.

The Snapshot to Azure Workflow (defined by .github/workflows/azure-function-snapshot.yml) deploys the application on each commit and the API can be accessed at the following URL:

Deploying the Function Yourself

First uncomment the Azure plugin from starter-azure-function/build.grade then run:

./gradlew clean starter-azure-function:azureFunctionsDeploy