diff --git a/docs/developer-guide/gateway-tunnelling-setup.md b/docs/developer-guide/gateway-tunnelling-setup.md index 7413a95..b7d7365 100644 --- a/docs/developer-guide/gateway-tunnelling-setup.md +++ b/docs/developer-guide/gateway-tunnelling-setup.md @@ -39,3 +39,38 @@ This guide describes the steps necessary to setup the gateway tunnelling functio * Set TCP port range in sish service (to allow raw TCP tunnelling) * Allow inbound access to port `2222` and to the TCP port range exposed on the instance * Generate or select existing SSH private key and add this to the deployment image and set SISH variable: `--private-keys-directory` + +# Gateway Tunnelling Development Setup + +To run the manager locally as an edge gateway, to test the gateway tunnelling functionality, two different docker compose profiles need to be running: +* The central instance profile (e.g. `docker-compose.central.yml`) needs to be running to provide the sish server functionality, with the correctly configured environment variables +* The testing (unproxied) development profile needs to be running to allow the manager to run properly in the IDE. + +You need to setup the SSH keys as described in the "Edge Instance Setup" section above. + +For the **central instance** profile: + +Run the main `docker-compose.yml` file with `OR_HOSTNAME=localhost`, and add the following: +* In the proxy service: + * SISH_PORT: 8090 + * SISH_HOST: sish +* In the manager service: + * Add `8008:8008` to allow attaching the debugger from the IDE + * Optionally, set the manager to be built from context `./manager/build/install/manager`, so that code changes are reflected during Docker image rebuild (after running `./gradlew clean installDist`) + * Add `OR_JAVA_OPTS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8008"` to allow remote debugging from the IDE + * `OR_METRICS_ENABLED: false` + * `OR_GATEWAY_TUNNEL_SSH_HOSTNAME: "localhost"` + * `OR_GATEWAY_TUNNEL_SSH_PORT: 2222` + * `OR_GATEWAY_TUNNEL_TCP_START: 9000` + * `OR_GATEWAY_TUNNEL_HOSTNAME: "localhost"` + * `OR_GATEWAY_TUNNEL_AUTO_CLOSE_MINUTES: 2` +* Add the `sish` service, as found in `deploy.yml`, and modify: + * Add volume `./deployment:/deployment` so that you can map the SSH keys that were generated above + +The routing of requests from the central instance to the gateway looks like this: Central Instance --> Sish --> Gateway Proxy --> Keycloak/Manager + +For the "Sish --> Gateway Proxy" requests to be routed correctly, we need to edit the local `/etc/hosts` file to route the `.` to localhost, like this: +``` +127.0.0.1 gw-5fj1sxvwwfp7wvgqgve91n.localhost +``` +The above setup should make the **`org.openremote.test.gateway.GatewayTest#Gateway Tunnelling Edge Gateway Integration test`** pass when run from the IDE or via Gradle. \ No newline at end of file