Rashed Talukder

Ngrok: Warp Speed for Your Integration Iterations

Blog Post created by Rashed Talukder on Sep 15, 2015




There's really no other way to describe what ngrok did for my Simple Stream App Integration development cycles other than amazing. It's so good that we're writing about it twice for those of us that missed it the first time! Instead of removing an add-on, reinstalling to the Jive instance, then installing the integration to the group and creating a new activity every time I made any little code change, I can just make the edits on my local machine and host them externally. Setting everything up is incredibly easy and allows me to hit refresh on my browser while viewing the external object/app and pulls the files from my \apps\[app name]\ directory.


With Nitrous.io no longer having a free option, this is the perfect (and IMO better) replacement tool to develop/iterate with on your Jive instance.



Ngrok is a small client application that punches a hole in your firewall and securely routes data to your local machine. Once the service is running, you're given a unique URL that can tunnel through HTTP and HTTPS. Ngrok also has a feature for authentication for access protection and you can inspect all the traffic going through the tunnels (http://localhost:4040). The best parts is that it's FREE and incredibly simple to have up and running. Each time you run ngrok, you'll be given a new subdomain which you'll have to change in your add-on—unless you are on a paid account—but will usually retain the endpoint if you don't close that window or close your ngrok session.


File Modified

  • \jiveclientconfiguration.json



Installing and Running Ngrok


Installation is relatively very simple. You need to download ngrok, unzip it to a location of your choosing, then sign up for an ngrok account. After logging in, Dashboard > Main > [Copy] "Your Tunnel Authtoken," then we're going to open terminal/command line, go into the folding containing ngrok and enter the following:

./ngrok authtoken [paste your authtoken]

ngrok authoken [paste your authtoken]



Starting Ngrok

Loading up an ngrok in terminal/command line is incredibly simple. You just need to set which port you'll be using for your app, which will be port 8090.

./ngrok http 8090

ngrok http 8090

Screen Shot 2015-09-14 at 10.47.39 AM.png

Be sure to copy your secure endpoint (https://xxxxxxxx.ngrok.io), we'll be needing that in the next steps.



Configuring Your Simple Stream App with Ngrok

Configuring your add-on to use ngrok and thus your local machine to host the app externally is incredibly simple and only requires modification to the \jiveclientconfiguration.json file.



Modify the following lines in your jiveclientconfiguration.json file:

"clientUrl": "https://[your unique ngrok subdomain].ngrok.io",
"clientUrlExcludesPort": true,
"port": "8090",
"suppressAddonRegistration" : true,



Building Your Externally Hosted App with Jive SDK

Go to the root directory of your integration in terminal/command line and run jive-sdk build --apphosting="self".

After the add-on is built and zipped together, install it into your Jive instance, install it to a group and push an activity to be created. Then when you go to view the external activity, you will see the app files get pulled from your local machine and requests/status' displaced in your ngrok terminal window.  At this point, you can do all your app development iteration from your local machine without having to do additional add-on deploys to Jive.  If JS/CSS assets appear to get cached, you should be able to simply stop and start your local node service, which takes about 1-2 seconds, and you should see the assets get refreshed!

In the event your app.xml changes, you will need to uninstall/reinstall the add-on for those changes to take affect.  It is recommended, that you lock in your app.xml contributions and features prior to iterating on your app.  See:  App Action Contribution Reference



Switching Back to Jive App Hosting with Jive SDK

Once you have refined your application and are ready to bundle the resources back into your Jive add-on, all you need to do is execute the following command to instruct the Jive SDK to bundle the app resources into the /public directory in the add-on:

jive-sdk build --apphosting="jive"


Simply uninstall / reinstall the add-on one more time, and you should be good to go!

Note:  In most cases, it is not necessary to change the clientUrl within jiveclientconfiguration.json back to http:  or http://localhost.



What's Next?