Use HarperDB + ngrok to enable Global Availability

Intro

When developing a backend locally, a common challenge is when you need to make your application available to another service via a secure, encrypted, https connection.
‍

This problem occurred to me most recently while developing a fullstack Shopify analytics application. First, we needed to use Shopify’s Oauth authentication service to allow users to connect their Shopify eCommerce stores. But Shopify requires an https connection to our localhost for this to work during development. To allow me to quickly develop and test things out, I needed to find a way to use https with localhost.
‍

This is where ngrok came in: using ngrok, we could create a secure “tunnel” to our localhost. Basically, once signed up to ngrok, we can use ngrok to create a url that will forward requests securely to our localhost – effectively making our localhost securely available to anyone in the world.
‍

Using ngrok was also essential for me to test out Shopify’s webhooks during development. For example, if we needed to subscribe to Shopify’s “products update” webhook so that whenever a store owner updates one of their products (e.g. they change the price of a product), Shopify sends us a webhook request (a POST request with the product’s info) to our application. But again, Shopify requires a https connection – and ngrok came to the rescue again.
‍

As you can see, ngrok made my life much easier as I could painlessly and swiftly test things out during localhost development, without having to do something like push the app to a staging site to test things out or mess with network settings, which would’ve took longer and took focus away from developing the app’s business logic. So, ngrok is a very important tool for backend developers to have in their arsenal!
‍

In this article, I’m going to show you how you can get a fullstack HarperDB (api routes + database) project up and running, and use ngrok to painlessly make it available via https to anyone with internet access.
‍

And if you’ve not used HarperDB before, HarperDB is a distributed application and database platform that allows you to lower latency and improve the performance of any dataset and any application. Basically, it provides you with a database and allows you to create api routes, and the database and routes can be distributed globally, moving your application and data closer to your users, and making your application lightning fast!
‍

Installing HarperDB locally

I’m on Mac, so to install HarperDB I opened a terminal and entered:

$ npm install -g harperdb

‍

This installed HarperDB instance on my Mac is located at the destination: /Users/danadams/hdb Server with:

Listening port: 9925
Username for HDB_ADMIN: HDB_ADMIN
Password: whatever_you_set_this_to_during_installation

‍

We can now start HarperDB with the command:

$ harperdb

Now we can use HarperDB locally!

‍

Creating a HarperDB custom functions project

Now we have HarperDB installed locally, we can create a new custom functions project. Custom functions are simply just Fastify API routes that can very quickly access data from the HarperDB database. To do this, open up a new terminal and cd (“change directory”) into the custom functions of your local HarperDB instance:


cd hdb
cd custom_functions

‍

You can check that you’re in the correct directory by entering `pwd` (“print working directory”). Currently, I’m here: `/Users/danadams/hdb/custom_functions`.

Now we’re in the right place, we need to actually create a new custom functions project. We could do all of this from scratch, or we can just clone HarperDB’s custom functions starter template to get us going quickly: https://github.com/HarperDB/harperdb-custom-functions-template. So, let’s clone this into our custom_functions folder:

git clone https://github.com/HarperDB/harperdb-custom-functions-template

If you know enter `ls` (“list files and directories”), you should see `harperdb-custom-functions-template` listed.

‍

Let’s rename this folder to `ngrok-project`:

mv harperdb-custom-functions-template ngrok-project

Alright, let’s open up this project in VS Code:

code ngrok-project

Creating a test route

Let’s now create a super simple route. In the routes folder, create a file called `test.routes.js`:

‍

‍

Then, in `test.routes.js`, copy the following code to create a simple test route:

export default async (server, { hdbCore, logger }) => {
  // Just a quick test route
  server.route({
    url: '/test',
    method: 'GET',
    handler: () => {
      return 'Hello World!';
    },
  });
};

Before we can access our custom function routes via web browser, you need to start up the HarperDB server. Open up your terminal, and enter `harperdb`. This will start up the server.

‍

By default, HarperDB runs on port 9926. So, to view our route, let’s make a GET request to http://localhost:9926/ngrok-project/test:

‍

Awesome!

‍

Now let’s set up ngrok so that we can make a secure tunnel to this route, making it accessible to anyone in the world.

Setting up ngrok

First, you need to download ngrok for the operating system you’re using: https://ngrok.com/download. I’m on Mac, so I simply entered `brew install ngrok/ngrok/ngrok` from the terminal.

You then need to create your ngrok account: https://dashboard.ngrok.com/signup.
‍

Once signed in, you need to connect up your local download of ngrok by adding in your authtoken. You can find this here: https://dashboard.ngrok.com/get-started/setup. Add your auth token to the ngrok.yml file (your local ngrok configuration file) with the following command:

ngrok config add-authtoken YOUR_TOKEN_HERE

Now for the exciting bit: making our local custom function route accessible to the world!

Creating an ngrok secure tunnel to our HarperDB custom functions

Enter the following command to create an ngrok secure tunnel to your localhost at port 9926:

ngrok http 9926

From the terminal output (below), you can see that ngrok has created a url, https://4ef4ad4c7023.ngrok.app, that forwards to our localhost at port 9926, http://localhost:9926.

‍

Note that every time we create a secure tunnel, ngrok will create a new random url that forwards to our localhost. So, if I go to the route that we created earlier, https://4ef4ad4c7023.ngrok.app/ngrok-project/test, we get:

‍

‍

Our little HarperDB custom function route is now accessible via a secure https connection from anywhere in the world!

Need proof? Try accessing that url from a different device – like your mobile or tablet. Here’s how things look from my iPhone:

‍

‍

Now anyone can access your HarperDB custom functions project from anywhere in the world -- how cool is that!

Conclusion

You now know how to set up a local HarperDB custom functions project, and make it accessible anywhere in the world by using ngrok to create a secure https tunnel to your localhost at port 9926. This is super useful when developing locally and you need to interact with services that require a https connection.

‍

For more from me, give me a sub on YouTube or follow me on Twitter.

‍

Thanks for reading!

‍

Dev Center

Our Story