From 2181731d64c30210c5c834e2bc4c5fd9141e7d61 Mon Sep 17 00:00:00 2001 From: Robbie Date: Wed, 3 Jan 2024 01:00:38 +1100 Subject: [PATCH] docs: Add Tunnelmole as an open source alternative to ngrok (#12925) * doc: Add Tunnelmole as an open source alternative to ngrok plus minor grammar fixes * Update README.md --------- Co-authored-by: Peer Richelsen Co-authored-by: Keith Williams --- apps/ai/README.md | 12 +++++--- packages/features/ee/organizations/README.md | 30 +++++++++++++++++++- 2 files changed, 37 insertions(+), 5 deletions(-) diff --git a/apps/ai/README.md b/apps/ai/README.md index fdba31f370..306bf07906 100644 --- a/apps/ai/README.md +++ b/apps/ai/README.md @@ -48,17 +48,21 @@ Here is the full architecture: ### Email Router -To expose the AI app, run `ngrok http 3005` (or the AI app's port number) in a new terminal. You may need to install [nGrok](https://ngrok.com/). +To expose the AI app, you can use either [Tunnelmole](https://github.com/robbie-cahill/tunnelmole-client), an open source tunnelling tool; or [nGrok](https://ngrok.com/), a popular closed source tunnelling tool. + +For Tunnelmole, run `tmole 3005` (or the AI app's port number) in a new terminal. Please replace `3005` with the port number if it is different. In the output, you'll see two URLs, one http and a https (we recommend using the https url for privacy and security). To install Tunnelmole, use `curl -O https://install.tunnelmole.com/8dPBw/install && sudo bash install`. (On Windows, download [tmole.exe](https://tunnelmole.com/downloads/tmole.exe)) + +For nGrok, run `ngrok http 3005` (or the AI app's port number) in a new terminal. You may need to install nGrok first. To forward incoming emails to the serverless function at `/agent`, we use [SendGrid's Inbound Parse](https://docs.sendgrid.com/for-developers/parsing-email/setting-up-the-inbound-parse-webhook). 1. Ensure you have a [SendGrid account](https://signup.sendgrid.com/) 2. Ensure you have an authenticated domain. Go to Settings > Sender Authentication > Authenticate. For DNS host, select `I'm not sure`. Click Next and add your domain, eg. `example.com`. Choose Manual Setup. You'll be given three CNAME records to add to your DNS settings, eg. in [Vercel Domains](https://vercel.com/dashboard/domains). After adding those records, click Verify. To troubleshoot, see the [full instructions](https://docs.sendgrid.com/ui/account-and-settings/how-to-set-up-domain-authentication). -3. Authorize your domain for email with MX records: one with name `[your domain].com` and value `mx.sendgrid.net.`, and another with name `bounces.[your domain].com` and value `feedback-smtp.us-east-1.amazonses.com`, both with priority `10` if prompted. +3. Authorize your domain for email with MX records: one with name `[your domain].com` and value `mx.sendgrid.net.`, and another with name `bounces.[your domain].com` and value `feedback-smtp.us-east-1.amazonses.com`. Set the priority to `10` if prompted. 4. Go to Settings > [Inbound Parse](https://app.sendgrid.com/settings/parse) > Add Host & URL. Choose your authenticated domain. -5. In the Destination URL field, use the nGrok URL from above along with the path, `/api/receive`, and one param, `parseKey`, which lives in [this app's .env](/apps/ai/.env.example) under `PARSE_KEY`. The full URL should look like `https://abc.ngrok.io/api/receive?parseKey=ABC-123`. +5. In the Destination URL field, use the Tunnelmole or ngrok URL from above along with the path, `/api/receive`, and one param, `parseKey`, which lives in [this app's .env](/apps/ai/.env.example) under `PARSE_KEY`. The full URL should look like `https://abc.tunnelmole.net/api/receive?parseKey=ABC-123` or `https://abc.ngrok.io/api/receive?parseKey=ABC-123`. 6. Activate "POST the raw, full MIME message". -7. Send an email to `[anyUsername]@example.com`. You should see a ping on the nGrok listener and server. +7. Send an email to `[anyUsername]@example.com`. You should see a ping on the Tunnelmole or ngrok listener and server. 8. Adjust the logic in [receive/route.ts](/apps/ai/src/app/api/receive/route.ts), save to hot-reload, and send another email to test the behaviour. Please feel free to improve any part of this architecture! diff --git a/packages/features/ee/organizations/README.md b/packages/features/ee/organizations/README.md index 53b0a3872b..4723fb73a9 100644 --- a/packages/features/ee/organizations/README.md +++ b/packages/features/ee/organizations/README.md @@ -37,7 +37,35 @@ Browsers do not allow camera/mic access on any non-HTTPS hosts except for localh For eg:- Use `http://localhost:3000/video/nAjnkjejuzis99NhN72rGt` instead of `http://app.cal.local:3000/video/nAjnkjejuzis99NhN72rGt`. -You can also use `ngrok` or you can generate SSL certificate for your local domain using `mkcert`. +To get an HTTPS URL for localhost, you can use a tunneling tool such as `ngrok` or [Tunnelmole](https://github.com/robbie-cahill/tunnelmole-client) . Alternatively, you can generate an SSL certificate for your local domain using `mkcert`. Turn off any SSL certificate validation in your HTTPS client (be sure to do this for local only, otherwise its a security risk). + +#### Tunnelmole - Open Source Tunnelling Tool: + +To install Tunnelmole, execute the command: + +``` +curl -O https://install.tunnelmole.com/8dPBw/install && sudo bash install +``` + +After a successful installation, you can run Tunnelmole using the following command, replacing `8000` with your actual port number if it is different: + +``` +tmole 8000 +``` + +In the output, you'll see two URLs, one HTTP and an HTTPS URL. For privacy and security reasons, it is recommended to use the HTTPS URL. + +View the Tunnelmole [README](https://github.com/robbie-cahill/tunnelmole-client) for additional information and other installation methods such as `npm` or building your own binaries from source. + +#### ngrok - Closed Source Tunnelling Tool: + +ngrok is a popular closed source tunneling tool. You can run ngrok using the same port, using the format `ngrok http ` replacing `` with your actual port number. For example: + +``` +ngrok http 8000 +``` + +This will generate a public URL that you can use to access your localhost server. ## DNS setup