From 1177afe887bb382bcefb4b51de67305e2d7f93e8 Mon Sep 17 00:00:00 2001 From: Arnout Engelen Date: Fri, 14 Jun 2019 11:30:53 +0200 Subject: [PATCH] Consolidate 'fat jar' docs (#24248) This moves the Maven documentation from the 'configuration' section to the 'deploy' section, and adds documentation for Gradle. A further improvement would be to split up the current 'deploy' docs and separate 'bundling' from 'deploying', but that is for a future PR. --- .../src/main/paradox/additional/deploy.md | 91 ++++++++++++++++++- .../src/main/paradox/general/configuration.md | 49 +--------- 2 files changed, 90 insertions(+), 50 deletions(-) diff --git a/akka-docs/src/main/paradox/additional/deploy.md b/akka-docs/src/main/paradox/additional/deploy.md index 14cbd846b2..76a7945658 100644 --- a/akka-docs/src/main/paradox/additional/deploy.md +++ b/akka-docs/src/main/paradox/additional/deploy.md @@ -1,12 +1,21 @@ # How can I deploy Akka? -Akka can be used in different ways: +The simplest way to use Akka is as a regular library, adding the Akka jars you +need to your classpath (in case of a web app, in `WEB-INF/lib`). - * As a library: used as a regular JAR on the classpath and/or in a web app, to -be put into `WEB-INF/lib` - * As an application packaged with [sbt-native-packager](https://github.com/sbt/sbt-native-packager) +Sometimes it can be useful to bundle your application into a single 'fat jar'. +If you do that, some additional configuration is needed, because each Akka jar +contains a `reference.conf` resource with default values, and these must be +merged. + +How to make sure reference.conf resources are merged depends on the tooling you +are using to create the fat jar: + + * When using sbt: as an application packaged with [sbt-native-packager](https://github.com/sbt/sbt-native-packager) + * When using Maven: as an application packaged with a bundler such as jarjar, onejar or assembly + * When using Gradle: using the Jar task from the Java plugin -## Native Packager +## sbt: Native Packager [sbt-native-packager](https://github.com/sbt/sbt-native-packager) is a tool for creating distributions of any type of application, including Akka applications. @@ -25,6 +34,78 @@ addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "1.1.5") Follow the instructions for the `JavaAppPackaging` in the [sbt-native-packager plugin documentation](http://sbt-native-packager.readthedocs.io/en/latest/archetypes/java_app/index.html). +## Maven: jarjar, onejar or assembly + +You can use the [Apache Maven Shade Plugin](http://maven.apache.org/plugins/maven-shade-plugin) +support for [Resource Transformers](http://maven.apache.org/plugins/maven-shade-plugin/examples/resource-transformers.html#AppendingTransformer) +to merge all the reference.confs on the build classpath into one. + +The plugin configuration might look like this: + +``` + + org.apache.maven.plugins + maven-shade-plugin + 1.5 + + + package + + shade + + + true + allinone + + + *:* + + + + + reference.conf + + + + akka.Main + + + + + + + +``` + + +## Gradle: the Jar task from the Java plugin + +When using Gradle, you would typically use the +[Jar task from the Java plugin](https://www.baeldung.com/gradle-fat-jar) +to create the fat jar. + +To make sure the `reference.conf` resources are correctly merged, you might +use the [Shadow plugin](https://imperceptiblethoughts.com/shadow/), which might +look something like this: + +``` +import com.github.jengelman.gradle.plugins.shadow.transformers.AppendingTransformer + +plugins { + id 'java' + id "com.github.johnrengelman.shadow" version "5.0.0" +} + +shadowJar { + transform(AppendingTransformer) { + resource = 'reference.conf' + } + with jar +} +``` + ## In a Docker container You can use both Akka remoting and Akka Cluster inside of Docker containers. But note diff --git a/akka-docs/src/main/paradox/general/configuration.md b/akka-docs/src/main/paradox/general/configuration.md index 550675a5f0..252fa995ae 100644 --- a/akka-docs/src/main/paradox/general/configuration.md +++ b/akka-docs/src/main/paradox/general/configuration.md @@ -67,56 +67,15 @@ of the JAR file. @@@ warning Akka's configuration approach relies heavily on the notion of every -module/jar having its own reference.conf file, all of these will be +module/jar having its own `reference.conf` file. All of these will be discovered by the configuration and loaded. Unfortunately this also means that if you put/merge multiple jars into the same jar, you need to merge all the -reference.confs as well. Otherwise all defaults will be lost and Akka will not function. +`reference.conf` files as well: otherwise all defaults will be lost. @@@ -If you are using Maven to package your application, you can also make use of -the [Apache Maven Shade Plugin](http://maven.apache.org/plugins/maven-shade-plugin) support for [Resource -Transformers](http://maven.apache.org/plugins/maven-shade-plugin/examples/resource-transformers.html#AppendingTransformer) -to merge all the reference.confs on the build classpath into one. - -The plugin configuration might look like this: - -``` - - org.apache.maven.plugins - maven-shade-plugin - 1.5 - - - package - - shade - - - true - allinone - - - *:* - - - - - reference.conf - - - - akka.Main - - - - - - - -``` +See the @ref[deployment documentation](../additional/deploy.md) +for information on how to merge the `reference.conf` resources while bundling. ## Custom application.conf