raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 10

Merge pull request #27144 from akka/bundling

Browse source 
Consolidate 'fat jar' docs
This commit is contained in:
Patrik Nordwall 2019-06-17 13:05:15 +02:00 • committed by GitHub
commit 51789515f2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 90 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

91
akka-docs/src/main/paradox/additional/deploy.md
View file

@ -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:
```
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>1.5</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<shadedArtifactAttached>true</shadedArtifactAttached>
<shadedClassifierName>allinone</shadedClassifierName>
<artifactSet>
<includes>
<include>*:*</include>
</includes>
</artifactSet>
<transformers>
<transformer
implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
<resource>reference.conf</resource>
</transformer>
<transformer
implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<manifestEntries>
<Main-Class>akka.Main</Main-Class>
</manifestEntries>
</transformer>
</transformers>
</configuration>
</execution>
</executions>
</plugin>
```
## 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

49
akka-docs/src/main/paradox/general/configuration.md
View file

@ -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:
```
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>1.5</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<shadedArtifactAttached>true</shadedArtifactAttached>
<shadedClassifierName>allinone</shadedClassifierName>
<artifactSet>
<includes>
<include>*:*</include>
</includes>
</artifactSet>
<transformers>
<transformer
implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
<resource>reference.conf</resource>
</transformer>
<transformer
implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<manifestEntries>
<Main-Class>akka.Main</Main-Class>
</manifestEntries>
</transformer>
</transformers>
</configuration>
</execution>
</executions>
</plugin>
```
See the @ref[deployment documentation](../additional/deploy.md)
for information on how to merge the `reference.conf` resources while bundling.
## Custom application.conf