Github user geomacy commented on a diff in the pull request:
https://github.com/apache/brooklyn-docs/pull/44#discussion_r59375726
--- Diff: guide/misc/osgi.md ---
@@ -0,0 +1,63 @@
+---
+title: FAQ
+layout: website-normal
+---
+
+# Running Apache Brooklin inside Karaf container
+
+The Apache Brooklyn Karaf based distribution lives in
brooklyn-server/karaf/apache-brooklyn folder.
+
+## Building
+
+{% highlight bash %}
+cd brooklyn-server
+mvn clean install
+cd karaf/apache-brooklyn/target
+tar -zxvf apache-brooklyn-{{ site.brooklyn-version }}.tar.gz
+cd apache-brooklyn-{{ site.brooklyn-version }}
+{% endhighlight %}
+
+## Running
+
+Start the instance using the following command
+
+{% highlight bash %}
+bin/karaf
+{% endhighlight %}
+
+To start in debug mode use
+
+{% highlight bash %}
+bin/karaf debug
+{% endhighlight %}
+
+and connect to port 5005 using your debugger.
+
+To pause startup until the debugger is connected you can use
+
+{% highlight bash %}
+JAVA_DEBUG_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE
-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005' bin/karaf debug
+{% endhighlight %}
+
+## Configuring
+
+You can use the standard ~/.brooklyn/brooklyn.properties file to configure
Brooklyn. Alternatively
+create etc/brooklyn.cfg inside the distribution folder (same file format).
The keys in the former override
+those in the latter.
--- End diff --
I'd reword this to say 'use <install-dir>/etc/brooklyn.cfg' but making a
note that ~/.brooklyn/brooklyn.properties is still supported for backward
compatibility. But also explain that values in brooklyn.cfg can be viewed and
managed dynamically via the OSGI configuration admin commands in Karaf, e.g.
config:property-set, so this is better suited for working in an OSGI
environment.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
