diff --git a/dev-tools/src/main/openshift/kapua-template.yml b/dev-tools/src/main/openshift/kapua-template.yml
index 8818aea3d36..106e6083cfb 100644
--- a/dev-tools/src/main/openshift/kapua-template.yml
+++ b/dev-tools/src/main/openshift/kapua-template.yml
@@ -547,3 +547,17 @@ objects:
       name: kapua-api
     port:
       targetPort: http
+
+- apiVersion: v1
+  kind: Service
+  metadata:
+    name: mqtt-ingress
+  spec:
+    ports:
+    - name: mqtt-tcp
+      port: 1883
+      nodePort: 31883
+    type: NodePort
+    selector:
+      app: kapua-broker
+      deploymentconfig: kapua-broker
diff --git a/docs/developer-guide/en/running.md b/docs/developer-guide/en/running.md
index 01ea13bc10f..ffcbd48b096 100644
--- a/docs/developer-guide/en/running.md
+++ b/docs/developer-guide/en/running.md
@@ -65,6 +65,26 @@ then you can also install Grafana for Hawkular to visualize your data:
 
     oc new-app -f https://raw.githubusercontent.com/hawkular/hawkular-grafana-datasource/master/docker/openshift/openshift-template-ephemeral.yaml
 
+### External access
+
+In order to enable devices to access Kapua we need to allow external access to the broker's MQTT connector. In the default deployment there are two ways to achieve this.
+
+First, the broker exposes MQTT over WebSocket transport. As WebSocket is based on HTTP we can define a router inside the Openshift to get those device connections to the broker.
+For example, if your Openshift deployment is running at the address `192.168.64.2`, you can connect the [Kura Simulator](../user-manual/simulator.md) like this
+
+```
+java -jar target/kapua-simulator-kura-*-SNAPSHOT-app.jar --broker ws://kapua-broker:kapua-password@broker-eclipse-kapua.192.168.64.2.nip.io:80
+```
+
+Not all MQTT clients have WebSocket support, so we need to enable direct MQTT over TCP access to the broker as well. By default, Kapua comes with the NodePort service that routes all traffic from port `31883` to the broker.
+So you can connect your MQTT clients directly to this service. For the simulator example similar to the above, that would look something like
+
+```
+java -jar target/kapua-simulator-kura-0.2.0-SNAPSHOT-app.jar --broker tcp://kapua-broker:kapua-password@192.168.64.2:31883
+```
+
+This is suitable only for the local deployments. In the cloud or production environments, you should deploy a proper LoadBalancer Openshift service to enable external traffic flow to the broker.
+
 ### Ensuring enough entropy
  
  It may happen that firing up docker containers and starting up application which use
diff --git a/docs/user-manual/en/simulator.md b/docs/user-manual/en/simulator.md
index 18e56b091ae..3c6e36c90d5 100644
--- a/docs/user-manual/en/simulator.md
+++ b/docs/user-manual/en/simulator.md
@@ -13,7 +13,7 @@ for this.
 The default main class is `org.eclipse.kapua.kura.simulator.main.SimulatorRunner`. It can be run after
 the module was built by be executing e.g. (which will print out some basic help):
 
-    java -jar target/kapua-simulator-kura-*-shaded.jar -?
+    java -jar target/kapua-simulator-kura-*-app.jar -?
 
 Once properly started the simulator will keep running (other forever or until the specified time elapsed)
 and then exit. While it is running it will try to stay connected to the broker. For more details about the
@@ -411,5 +411,5 @@ To start simulator with an example simulation configuration, run:
 
 ```
 export KSIM_SIMULATION_CONFIGURATION=$(curl -s https://raw.githubusercontent.com/eclipse/kapua/develop/simulator-kura/src/test/resources/example1.json)
-java -jar target/kapua-simulator-kura-*-shaded.jar
+java -jar target/kapua-simulator-kura-*-app.jar
 ```