Ngrok

Ngrok (pronounced en-grok) is a useful tool for making your local Totara site accessible publicly on the web. This is especially handy when testing intergrations with Totara, such as the mobile app, or external services such as Microsoft Teams, LinkedIn Learning, or even if you simply want to make your site available for someone else to look at.

Requirements

To use Ngrok, you'll need to do the following:

1. Sign up for an Ngrok account
2. Follow the installation instructions
3. Ensure your site is using the template config.php that comes with docker-dev
4. Ensure your hosts are up to date by runnining the set_hosts.sh script (located in ~/totara-docker-dev/tools/set_hosts.sh or wherever you cloned docker-dev)

Usage

Once ngrok is set up, you can use the tngrok command to use it with Totara.

For example, if you want to make your integration site publically accessible using PHP 8.3, you would run tngrok integration.totara83

You would then see this (or similar) in your terminal:

ngrok                                                                                                                                                                                (Ctrl+C to quit)

🔀 Route traffic by anything: https://ngrok.com/r/iep

Session Status                online
Account                       markmetcalfetotara (Plan: Free)
Version                       3.18.4
Region                        Australia (au)
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://2536-219-89-13-234.ngrok-free.app -> https://integration.totara83:8443

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Now you can access the site using the url shown in "Forwarding", in this example https://2536-219-89-13-234.ngrok-free.app. The url is accessible publicly so make sure you shutdown ngrok if you don't use it anymore (Ctrl-C).

Permanent URL

If your ngrok account is on a pro subscription, you can also specify what you want the URL to be, instead of getting a random one every time. This is especially helpful when setting up complex integrations (such as with Microsoft Teams) that you don't want to have to set up again every time you restart ngrok.

Example command:

tngrok yoursite.totara83 my-public-totara-site

Which will give you a publicly accessible URL at https://my-public-totara-site.ngrok.app.

XDebug & Ngrok

XDebug and Ngrok work together out of the box! This means that you can debug any external connections coming into your Totara site from an external source, such as an OAuth2 authentication request coming from an external integration for example.

As long as you have XDebug integrated with PHPStorm/your IDE of choice, you can simply specify a .debug URL for your host like this:

tngrok yoursite.totara83.debug

And just make sure you are listening for connections in your IDE. Simple really!