# Connect remote sites and apps to Snowplow Micro
> Test remote websites and apps with Micro using ngrok or localtunnel for public access, or use local domain resolution to receive first-party cookies. Configure HTTPS and match collector settings.
> Source: https://docs.snowplow.io/docs/testing/snowplow-micro/local/remote-usage/
> Documentation index: https://docs.snowplow.io/llms.txt

If you are not running your website or app locally but would still like to use Micro for local testing and debugging, there are two options:

|                                         | Option 1 [Exposing Micro via a public domain name](#exposing-micro-via-a-public-domain-name) | Option 2 [Locally resolving an existing domain name to Micro](#locally-resolving-an-existing-domain-name-to-micro) |
| --------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Requires control over the tracking code | Yes                                                                                          | No                                                                                                                 |
| Accessible from multiple devices        | Yes                                                                                          | No                                                                                                                 |
| Micro receives first-party cookies      | No                                                                                           | Yes                                                                                                                |
| Micro receives external IP addresses    | Yes                                                                                          | No                                                                                                                 |

## Exposing Micro via a public domain name

> **Tip: Micro in Console**
>
> This method is for running Micro locally. You can also [run Micro through Console](/docs/testing/snowplow-micro/console/), which automatically gives you a public endpoint.

This method allows you to get a publicly accessible URL for your Micro, which you can point your tracking code to. You can also send this URL to colleagues for them to inspect the results in the [dashboard](/docs/testing/snowplow-micro/ui/) (since version 2.0.0) or via the [API](/docs/api-reference/snowplow-micro/api/).

```mermaid
flowchart LR
  website(Website or app)
  tracking(Tracking code)
  url(URL like <code>https://22d8-....ngrok.app</code>)
  tunnel{{"<i>Tunneling magic</i> 🪄"}}
  micro(Micro on your machine)

  website --> tracking --> url --> tunnel --> micro
```

The easiest way to achieve this is with a tool like [ngrok](https://ngrok.com/) or [localtunnel](https://theboroer.github.io/localtunnel-www/).

> **Note: Cookies and IP addresses**
>
> Either tool will take care of HTTPS and the required certificates. However, the resulting URL will not be under your domain, so you will not be able to set or receive first-party cookies this way.
>
> You will, however, receive external IP addresses (not something like `192.168.0.42`) when you or others browse the website or app pointing to Micro. This might be useful for testing certain enrichments.

After running Micro as usual, you just need to expose the port (by default, `9090`):

**ngrok:**

[Sign up](https://dashboard.ngrok.com/signup), [download](https://ngrok.com/download) ngrok and follow the instructions to authenticate your client. Then run this command:

```bash
ngrok http 9090
```

You will see the publicly available URL in the output.

**localtunnel:**

Install:

```bash
npm install -g localtunnel
```

Then run this command:

```bash
lt --port 9090
```

You will see the publicly available URL in the output. Before use, visit this URL in your web browser and click “Continue”.

***

## Locally resolving an existing domain name to Micro

This method only works on your machine, but it allows you to connect any website or app to your Micro, even if you don’t control the tracking code.

```mermaid
flowchart LR
  website(Website or app)
  tracking(Tracking code)
  url(Existing collector URL like <code>c.example.com</code>)
  collector(Actual collector)
  micro(Micro on your machine)

  url -.-x collector
  website --> tracking --> url -- "<i>Custom local domain<br/>resolution rule</i>" --> micro
```

Let’s say you have a website `example.com` with Snowplow tracking that points to a Collector hosted at `c.example.com`.

> **Note: Cookies and IP addresses**
>
> With this approach, because Micro is “pretending” to be behind the actual Collector domain (`c.example.com`), it will receive first-party cookies set for that domain.
>
> However, you will only get local IP addresses (like `192.168.0.42`) in your data, because the traffic never leaves your machine. This might be relevant for testing some enrichments.
>
> If you are using a web browser to test your site or app, you can spoof a specific IP address using a browser plugin that sets an `X-Forwarded-For` header. For example, here are plugins for [Chrome](https://chrome.google.com/webstore/detail/x-forwarded-for-header/hkghghbnihliadkabmlcmcgmffllglin/) and [Firefox](https://addons.mozilla.org/en-US/firefox/addon/x-forwarded-for-injector/). Install the plugin and set the IP address to your liking.

### Generate a local SSL/TLS certificate

Chances are that the website in question uses HTTPS. If so, you will need to configure Micro to [enable HTTPS](/docs/testing/snowplow-micro/local/advanced-usage/#enabling-https). Otherwise, feel free to skip this step.

First, install [`mkcert`](https://github.com/FiloSottile/mkcert). This tool allows you to easily generate SSL/TLS certificates that your machine trusts.

Now, run the following commands in a terminal (make sure to substitute your Collector domain for `c.example.com`):

```bash
# one-time setup
mkcert -install

# generate a certificate
mkcert -pkcs12 c.example.com
```

You should now have a local file called `c.example.com.p12` with the default password `changeit`.

### Match the Collector configuration

To make sure your Micro behaves the same way as the Collector it’s “pretending” to be, copy the relevant parts of your Collector configuration and [pass them to Micro](/docs/testing/snowplow-micro/local/advanced-usage/#adding-custom-collector-and-enrich-configuration).

The two most important settings are the cookie name (you can set it with `-Dcollector.cookie.name` as shown on the page linked above) and any custom paths (via a configuration file).

### Run Micro

You will need to run Micro as usual, with a few changes:

- [Enable HTTPS](/docs/testing/snowplow-micro/local/advanced-usage/#enabling-https), if needed
- Use port `80` instead of `9090`
- If HTTPS is enabled, also use port `443` instead of `9543`

If you don’t need HTTPS:

```bash
docker run -p 80:9090 snowplow/snowplow-micro:4.6.2
```

If you need HTTPS (substitute your Collector domain for `c.example.com`):

```bash
docker run -p 80:9090 -p 443:9543 \
--mount type=bind,source=$(pwd)/c.example.com.p12,destination=/config/ssl-certificate.p12 \
-e MICRO_SSL_CERT_PASSWORD=changeit \
snowplow/snowplow-micro:4.6.2
```

### Modify the hosts file

To conclude the setup, you will have to modify your [hosts file](https://en.wikipedia.org/wiki/Hosts_\(file\)) (`/etc/hosts` on Linux/macOS, `C:\Windows\System32\drivers\etc\hosts` on Windows) to point `c.example.com` — the Collector domain — to your local machine. Add these lines:

```text
127.0.0.1 c.example.com
```

_With this change, whenever your system tries to send data to `c.example.com`, it will send it to your Micro instead._ Done!

> **Tip:** Don’t forget to revert the hosts file change once no longer necessary.