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

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? # 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 Sometimes it can be useful to bundle your application into a single 'fat jar'.
be put into `WEB-INF/lib` If you do that, some additional configuration is needed, because each Akka jar
* As an application packaged with [sbt-native-packager](https://github.com/sbt/sbt-native-packager) contains a `reference.conf` resource with default values, and these must be
merged.
## Native Packager 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
## sbt: Native Packager
[sbt-native-packager](https://github.com/sbt/sbt-native-packager) is a tool for creating [sbt-native-packager](https://github.com/sbt/sbt-native-packager) is a tool for creating
distributions of any type of application, including Akka applications. 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). 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 ## In a Docker container
You can use both Akka remoting and Akka Cluster inside of Docker containers. But note 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 @@@ warning
Akka's configuration approach relies heavily on the notion of every 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 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 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 See the @ref[deployment documentation](../additional/deploy.md)
the [Apache Maven Shade Plugin](http://maven.apache.org/plugins/maven-shade-plugin) support for [Resource for information on how to merge the `reference.conf` resources while bundling.
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>
```
## Custom application.conf ## Custom application.conf