Github user sjcorbett commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/354#discussion_r21001306
--- Diff: docs/dev/build/debugging-remote-brooklyn.md ---
@@ -0,0 +1,135 @@
+---
+layout: page
+title: Brooklyn Remote Debugging
+toc: /toc.json
+---
+
+Usually during development, you will be running Brooklyn from your IDE
(see [IDE Setup](ide.html)), in which case
+debugging is as simple as setting a breakpoint. There may however be times
when you need to debug an existing remote
+Brooklyn instance (often referred to as Resident Brooklyn, or rBrooklyn)
on another machine, usually in the cloud.
+
+Thankfully, the tools are available to do this, and setting it up is quite
straightforward. The steps are as follows:
+
+* [Getting the right source code version](#sourceCodeVersion)
+* [Starting Brooklyn with a debug listener](#startingBrooklyn)
+* [Creating an SSH tunnel](#sshTunnel)
+* [Connecting your IDE](#connectingIDE)
+
+## <a name="sourceCodeVersion"></a>Getting the right source code version
+The first step is to ensure that your local copy of the source code is at
the version used to build the remote Brooklyn
+instance. The git commit that was used to build Brooklyn is available via
the REST API:
+
+```
+http://<remote-address>:<remote-port>/v1/server/version
+```
+
+This should return details of the build as a JSON string similar to the
following (formatted for clarity):
+
+```JSON
+{
+ version: "0.7.0-SNAPSHOT",
+ buildSha1: "c0fdc15291702281acdebf1b11d431a6385f5224",
+ buildBranch: "UNKNOWN"
+}
+```
+
+The value that we're interested in is `buildSha1`. This is the git commit
that was used to build Brooklyn. We can now
+checkout and build the Brooklyn code at this commit by running the
following in the root of your Brooklyn repo:
+
+```
+git checkout c0fdc15291702281acdebf1b11d431a6385f5224
+mvn clean install -DskipTests
+```
+
+Whilst building the code isn't strictly necessary, it can help prevent
some IDE issues.
+
+## <a name="startingBrooklyn"></a>Starting Brooklyn with a debug listener
+By default, Brooklyn does not listen for a debugger to be attached,
however this behaviour can be set by setting JAVA_OPTS,
+which will require a restart of the Brooklyn node. To do this, SSH to the
remote Brooklyn node and run the following in the
+root of the Brooklyn installation:
+
+```
+kill `cat pid_java`
+export JAVA_OPTS="-Xms256m -Xmx1g -XX:MaxPermSize=256m
-agentlib:jdwp=transport=dt_socket,address=127.0.0.1:8888,server=y,suspend=n"
+bin/brooklyn launch &
+```
+
+If `JAVA_OPTS` is not set, Brooklyn will automatically set it to
`"-Xms256m -Xmx1g -XX:MaxPermSize=256m"`, which is why
+we have prepended the agentlib settings with these values here.
+
+You should see the following in the console output:
+
+```
+Listening for transport dt_socket at address: 8888
+```
+
+This will indicate the Brooklyn is listening on port 8888 for a debugger
to be attached.
+
+## <a name="sshTunnel"></a>Creating an SSH tunnel
+If port 8888 is accessible on the remote Brooklyn server, then you can
skip this step and simply use the address of the
+server in place of 127.0.0.1 in the [Connecting your IDE](#connectingIDE)
section below. It will normally be possible to
+make the port accessible by configuring Security Groups, iptables,
endpoints etc., but for a quick ad-hoc connection it's
+usually simpler to create an SSH tunnel. This will create an open SSH
connection that will redirect traffic from a port
+on a local interface via SSH to a port on the remote machine. To create
the tunnel, run the following on your local
+machine:
+
+```
+REMOTE_HOST=<remote-address> # replace this with the address or IP of the
remote Brooklyn node
--- End diff --
I think this section would be easier to read if the comments were on the
preceding lines.
---
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.
---
