25th June 2019

ngrok and Craft CMS

Have you ever found yourself working locally on a Craft project – be it a site or plugin – and needed to access it remotely, but didn't want to go through the hassle of getting it hosted somewhere? Then boy do we have the secure introspectable tunneling app for you: ngrok!

We'll talk a bit more about what ngrok is below, but first let's get to why you're probably here.

How to: ngrok and Craft 3

We're going to jump straight in and assume you know at least the basics of using ngrok (if not, you can checkout their docs to get started).

First, setup your general.php file to account for ngrok's URL:

	<?php

	$isNgrok = array_key_exists('HTTP_X_ORIGINAL_HOST', $_SERVER) && strpos($_SERVER['HTTP_X_ORIGINAL_HOST'], 'ngrok');
	$host = $isNgrok ? ('https://' . $_SERVER['HTTP_X_ORIGINAL_HOST'] . '/') : getenv('DEFAULT_SITE_URL');

	return [
	'*' => [
	// ...

	'siteUrl' => $host,
	'baseCpUrl' => $host,
	'aliases' => [
	'web' => $host,
	],
	],

	// ...
	];

Next, run ngrok.

Here we're setting our region to EU (since that's where we are), and the host header to our local URL. We're also setting the port to 443 since our local environment has self-signed SSL. If yours doesn't have SSL, you'll want to set the port to 80.

ngrok http -region=eu -host-header=my-dev-domain.local 443

What is ngrok?

Chances are if you're here you already know what ngrok is, but if you don't here's a quick rundown.

Ngrok is a simple way to create public URLs via secure tunnels to localhost. This means you're able to create a public URL that allows anyone with that URL to view and interact with a site or application you're running locally on your machine.

We use it at Ether as a way to share our local dev environments with clients and each other, and for easy testing across devices. It also comes in handy when testing integrations with services that require secure public URLs. This recently came up while developing our new MailChimp Craft Commerce plugin where testing required us to have a valid site URL that MailChimp could access. It's also great when browsers require HTTPS to use certain features, such as web payments (we have a Plugin for that too)!