From 09a1f818b9af8d3e28af6ed78caa40b64438f038 Mon Sep 17 00:00:00 2001
From: Oleksii Mozghovyi <oleksii.mozghovyi@pantheon.tech>
Date: Wed, 10 Feb 2021 20:45:11 +0200
Subject: [PATCH] Document usage of Karaf static distribution

The document adds information about the new parent project
"karaf-dist-static" for the static distribution and details on how it
can be used.

JIRA: ODLPARENT-251
Change-Id: Iac02a47dc8526a3f687e08987a1ff4b4b3c4ef66
Signed-off-by: Oleksii Mozghovyi <oleksii.mozghovyi@pantheon.tech>
---
 docs/developer-guide.rst | 78 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)

diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst
index a46dcea8b..aac907415 100644
--- a/docs/developer-guide.rst
+++ b/docs/developer-guide.rst
@@ -35,6 +35,9 @@ These parent projects are:
 -  ``karaf4-parent`` — the parent POM for Maven modules producing Karaf 4
    distributions
 
+-  ``karaf-dist-static`` - the parent POM for Maven modules producing Karaf 4
+   static distributions
+
 odlparent-lite
 ~~~~~~~~~~~~~~
 
@@ -348,6 +351,81 @@ purposes. Any runtime-scoped feature dependencies will be included in the
 distribution, and the ``karaf.localFeature`` property can be used to
 specify the boot feature (in addition to ``standard``).
 
+karaf-dist-static
+~~~~~~~~~~~~~~~~~
+
+This allows building a kind of immutable static distribution by adding
+this as a parent to your project's pom.xml. This pom file defines the static
+karaf framework alongside common OpenDaylight's components(branding,
+bouncycastle items, etc). The major difference to the dynamic distribution is
+that validation of features dependencies happens during the build phase and
+all of the dependencies are installed as *"reference:file:url"* into the
+*"etc/startup.properties"*. Static distribution might be the right choice when
+you need to to produce a lightweight and immutable package for your deployment.
+You can find a ``test-static`` project that inherits from ``karaf-dist-static``
+and demonstrates how this parent can be used.
+
+Generally speaking, to build a static distribution with selected for your
+purposes features, you have to follow the next two steps:
+
+1. Add features you want to be included in distribution under the
+   dependencies block.
+
+.. code:: xml
+
+    <dependencies>
+        <dependency>
+            <groupId>org.opendaylight.odlparent</groupId>
+            <artifactId>odl-dropwizard-metrics</artifactId>
+            <version>${project.version}</version>
+            <type>xml</type>
+            <classifier>features</classifier>
+        </dependency>
+        <dependency>
+            <groupId>org.opendaylight.odlparent</groupId>
+            <artifactId>odl-gson</artifactId>
+            <version>${project.version}</version>
+            <type>xml</type>
+            <classifier>features</classifier>
+        </dependency>
+    </dependencies>
+
+2. Put additional configuration for the karaf-maven-plugin about these features:
+
+.. code:: xml
+
+            <plugin>
+                <groupId>org.apache.karaf.tooling</groupId>
+                <artifactId>karaf-maven-plugin</artifactId>
+                <extensions>true</extensions>
+                <configuration>
+                    <startupFeatures combine.children="append">
+                        <feature>shell</feature>
+                    </startupFeatures>
+                    <bootFeatures combine.children="append">
+                        <feature>odl-dropwizard-metrics</feature>
+                        <feature>odl-gson</feature>
+                    </bootFeatures>
+                </configuration>
+            </plugin>
+
+.. note::  If you need to add something from the default karaf features
+           (like ``shell`` feature in our example), you should use
+           **<startupFeatures>** block, and not forget about
+           **combine.children="append"** attribute. Everything else can
+           be added to the bootFeatures block.
+
+
+**Known issues**
+
+* An issue with FeatureDeploymentListener.bundleChanged and NPE records in
+  log files. More details available here:
+  https://issues.apache.org/jira/browse/KARAF-6612
+
+* Some of the features might try to update configuration files, but that's
+  not supported by static distribution, so StaticConfigurationImpl.update
+  will throw UnsupportedOperationException.
+
 Features (for Karaf 3)
 ----------------------
 
-- 
2.36.6