From dad186014fd26cdc6124463a9559b907fc90da7d Mon Sep 17 00:00:00 2001
From: Mark Story <mark@mark-story.com>
Date: Tue, 25 Jun 2024 10:23:12 -0400
Subject: [PATCH] fix: Improve ngrok setup docs (#1317)

Clarify how ngrok should be setup for siloed and non-siloed modes.

Refs getsentry/sentry#14423
---
 src/docs/backend/development-server.mdx | 28 +++++++++++++++++++++++++
 src/docs/environment/index.mdx          | 16 ++++++++------
 2 files changed, 38 insertions(+), 6 deletions(-)

diff --git a/src/docs/backend/development-server.mdx b/src/docs/backend/development-server.mdx
index a2e22790b4..35f3fa5574 100644
--- a/src/docs/backend/development-server.mdx
+++ b/src/docs/backend/development-server.mdx
@@ -27,3 +27,31 @@ This will do literally nothing except bring up the web workers. You are now resp
 * Starting Celery workers using `sentry run worker` to run most kinds of background jobs.
 
 Use `sentry run --help` to see what you might be missing by not running devserver.
+
+
+## Using ngrok
+
+The development server can be operated behind ngrok for when you need to receive traffic from the outside world. This comes up frequently when working with integrations. Start off by defining a configuration file for `ngrok`:
+
+```yaml
+version: '2'
+authtoken: <YOUR-NGROK-AUTHTOKEN>
+tunnels:
+  acme-org
+    proto: http
+    hostname: <yourname>.ngrok.dev
+    addr: 8010
+    host_header: 'rewrite'
+```
+
+Next start up ngrok with your configuration file:
+
+```shell
+ngrok start --all --config ngrok.yml`
+```
+
+When starting devserver provide your ngrok domain
+
+```shell
+sentry devserver --ngrok=<yourname>.ngrok.dev
+```
diff --git a/src/docs/environment/index.mdx b/src/docs/environment/index.mdx
index d3fdb6ef3f..5e2b05de67 100644
--- a/src/docs/environment/index.mdx
+++ b/src/docs/environment/index.mdx
@@ -72,20 +72,24 @@ In the above setup your local environment will use org slug domains, and send re
 
 ### Ngrok and siloed servers
 
-To combine ngrok and local development servers you’ll need to reserve two domains in ngrok, and create a configuration file for ngrok:
+To combine ngrok and local development servers you’ll need to reserve multiple domains in ngrok, and create a configuration file for ngrok:
 
 ```yaml
 version: '2'
 authtoken: <YOUR-NGROK-AUTHTOKEN>
 tunnels:
+  acme-org:
+    proto: http
+    hostname: acme.<yourname>.ngrok.dev
+    addr: 8000
   control-silo:
     proto: http
-    hostname: $yourname.ngrok.dev
+    hostname: <yourname>.ngrok.dev
     host_header: 'rewrite'
     addr: 8000
   region-silo:
     proto: http
-    hostname: us.$yourname.ngrok.dev
+    hostname: us.<yourname>.ngrok.dev
     addr: 8010
     host_header: 'rewrite'
 ```
@@ -94,16 +98,16 @@ Then run all the required servers
 
 ```shell
 # Run a control silo with ngrok
-sentry devserver --silo=control --ngrok $yourname.ngrok.dev
+sentry devserver --silo=control --ngrok <yourname>.ngrok.dev
 
 # Run a region silo without ngrok
-sentry devserver --silo=region --ngrok $yourname.ngrok.dev
+sentry devserver --silo=region --ngrok <yourname>.ngrok.dev
 
 # Run ngrok
 ngrok start --all --config regions.yml
 ```
 
-This setup will result in both the region and control servers responding to different domains, and CORS will work similar to production.
+This setup will result in both the region and control servers responding to different domains. The multi-region setup with ngrok also enables customer-domains and you'll need ngrok domains for each organization you plan on using. In this configuration, CORS will work similar to production. For ngrok setup with non-siloed development server see <Link to="/backend/development-server/">developement server</Link>.
 
 ### Siloed Django Shell