Document Ngrok for VA debugging / QA

[jilladams]

Description or Additional Context

NGrok is a tool that provides a URL where folks can reach test instances of code in development for verification. Public Websites uses this a lot, and we could document so others can take advantage.

This could / maybe should become a part of FE dev tools, https://depo-platform-documentation.scrollhelp.site/developer-docs/tools, so write up in ticket is fine, and then let's ask Plat to put it in their site.

Acceptance Criteria

• Write up "how to ngrok" and include
  • Set up steps
  • Use cases
• Cut a Plat docs ticket with details they can use to add ngrok docs to their site

[randimays]

How to use ngrok for testing local development builds

What is ngrok?

ngrok (pronounced en-grok) is an environment independent reverse proxy. One of the many conveniences it provides is the ability to demo or share a working build without deploying to a test or staging environment. Put simply: you can use ngrok for testing your code before it is merged to the main branch.

See “What is ngrok?" and "How does ngrok work?” for more detail.

When would I use ngrok?

If there are infrastructure hurdles or environment issues preventing you from sharing your local build, such as:

1. Review instances not working
2. Tugboat not working
3. Recipient does not have SOCKS access
4. Build must be tested on a mobile device

ngrok can be used as an alternative solution.

Note: A free ngrok account has usage limitations. See the Gotchas section below for more detail.

How do I use ngrok?

Refer to the Quickstart guide for installation instructions. You will need to create an account.

Running the ngrok server

1. Run your local vets-website build (e.g. yarn watch)
2. Run your local content-build build (e.g. yarn watch)
3. Verify that http://localhost:3002 loads successfully in your browser
4. In a different Terminal tab, run ngrok http 3002 (the port should match your current localhost port)

The ngrok command will produce a unique URL for you to navigate to on any device.

In the below example, the Forwarding address before the -> is what you'll use on the device. You can add any paths (e.g. /health-care) after this address to get where you need to go.

If you make changes to the code locally, you will need to:

1. Wait for your local vets-website build and content-build build to compile completely
2. Verify http://localhost:3002 loads successfully in your browser
3. Stop the ngrok server in your Terminal (ctrl+c / cmd+c)
4. Run the ngrok http 3002 command again (note: this will give you a new URL)

First time building content-build?

When you build content-build for the first time, it will pull all of the assets from Drupal (images, videos, templates). This can take upwards of 8 hours.

Reach out to the #sitewide-public-websites channel in Slack for some guidance on how to speed up a build (provided you can test your changes without some Drupal assets).

Gotchas

ngrok usage with a free account

Your free ngrok account will be limited in its monthly bandwidth, HTTP requests, tunnels, etc. See ngrok licensing information for specifics.

If at any point you receive an error message to this effect when trying to run ngrok commands, you will have to wait until the first day of following month for your counts to be reset and be able to run ngrok requests again.

Limited capability

1. ngrok does not work for the injected header/footer scenario.

2. ngrok does not work when only running vets-website locally (port 3001)

[randimays]

Created a ticket for Platform to review and possibly add our docs to theirs: department-of-veterans-affairs/va.gov-team#80225. Closing as complete.