From 4ad2852276bfe0c9bdf3ef79fb98d24ce8801319 Mon Sep 17 00:00:00 2001 From: Raj Joshi Date: Mon, 16 Sep 2024 13:44:42 -0700 Subject: [PATCH] chore(ngrok): Move Ngrok Docs to Centralized Place (#11214) --- develop-docs/backend/development-server.mdx | 27 +---- .../development/database-migrations/index.mdx | 2 + .../development/environment/index.mdx | 37 +----- develop-docs/development/ngrok.mdx | 111 ++++++++++++++++++ 4 files changed, 115 insertions(+), 62 deletions(-) create mode 100644 develop-docs/development/ngrok.mdx diff --git a/develop-docs/backend/development-server.mdx b/develop-docs/backend/development-server.mdx index 35f3fa5574983..ce5a0bb8c0636 100644 --- a/develop-docs/backend/development-server.mdx +++ b/develop-docs/backend/development-server.mdx @@ -28,30 +28,5 @@ This will do literally nothing except bring up the web workers. You are now resp Use `sentry run --help` to see what you might be missing by not running devserver. +To run the development server with ngrok, see [Developing with Ngrok](/development/ngrok/). -## 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: -tunnels: - acme-org - proto: http - hostname: .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=.ngrok.dev -``` diff --git a/develop-docs/development/database-migrations/index.mdx b/develop-docs/development/database-migrations/index.mdx index 33aaa83ecd660..8d82470f34003 100644 --- a/develop-docs/development/database-migrations/index.mdx +++ b/develop-docs/development/database-migrations/index.mdx @@ -409,6 +409,8 @@ There is a script in both sentry & getsentry that are functionally equivalent. I The `split-silo-database` scripts use silo annotations on models to selectively dump your monolith database into the siloed databases. +You might need to set `SENTRY_MONOLITH_REGION="us"` in your sentry config in order to successfully update the organization mappings. + ### Apply Migrations to siloed databases You have two options for maintaining siloed databases: diff --git a/develop-docs/development/environment/index.mdx b/develop-docs/development/environment/index.mdx index a7c9ef4465373..59f03da7f760a 100644 --- a/develop-docs/development/environment/index.mdx +++ b/develop-docs/development/environment/index.mdx @@ -160,42 +160,7 @@ 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 multiple domains in ngrok, and create a configuration file for ngrok: - -```yaml -version: '2' -authtoken: -tunnels: - acme-org: - proto: http - hostname: acme..ngrok.dev - addr: 8000 - control-silo: - proto: http - hostname: .ngrok.dev - host_header: 'rewrite' - addr: 8000 - region-silo: - proto: http - hostname: us..ngrok.dev - addr: 8010 - host_header: 'rewrite' -``` - -Then run all the required servers - -```shell -# Run a control silo with ngrok -sentry devserver --silo=control --ngrok .ngrok.dev - -# Run a region silo without ngrok -sentry devserver --silo=region --ngrok .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. 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 developement server. +Refer to ngrok docs. ### Siloed Django Shell diff --git a/develop-docs/development/ngrok.mdx b/develop-docs/development/ngrok.mdx new file mode 100644 index 0000000000000..9d66122c807db --- /dev/null +++ b/develop-docs/development/ngrok.mdx @@ -0,0 +1,111 @@ +--- +title: Developing with Ngrok +description: This document explains how to use ngrok with the development server. +sidebar_title: Ngrok +sidebar_order: 30 +--- + +# 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. + +It is recommended to use `getsentry` while working with integrations as it will automatically set up the correct configurations for you. + +Note, if the following instructions aren't working and you are using `getsentry`, check if there is some configuration that is set for your environment that is updating the following options and configs: +``` +SENTRY_OPTIONS["system.url-prefix"] +SENTRY_OPTIONS["system.base-hostname"] +SENTRY_FEATURES["system:multi-region"] + +CSRF_TRUSTED_ORIGINS +ALLOWED_HOSTS +SESSION_COOKIE_DOMAIN +CSRF_COOKIE_DOMAIN +SUDO_COOKIE_DOMAIN +``` +`dev.py` in `getsentry` should automatically set the correct values for these configurations. + +## Ngrok in Monolith mode + +The following steps will setup ngrok in `monolith` mode: + +### Step 1: Create Ngrok Config File +Start off by defining a configuration file for `ngrok`, for example `ngrok.yml`: + +```yaml +version: '2' +authtoken: +tunnels: + acme-org: + proto: http + hostname: .ngrok.io + addr: 8000 + host_header: "rewrite" +``` + +You can grab your auth token from https://dashboard.ngrok.com/get-started/your-authtoken + +### Step 2: Start Ngrok +Next start up ngrok with your configuration file: +```shell +ngrok start --all --config ngrok.yml +``` + +### Step 3: Start Devserver +When starting the devserver, use the `--ngrok` flag: +```shell +getsentry devserver --ngrok=.ngrok.io +``` + +## Ngrok in Silo mode + +To debug issues related to integration middleware as well as issues relating to latency induced by RPC calls, you can run your local environment in silo mode. + +To learn more about how silo mode works in the dev environment, refer to Running Siloed Instances. + + +### Step 1: Split Local DB into Silos +By default `sentry devserver` will run a monolith mode application server. You can also run ``devserver`` with siloed application instances. Before you do, you need to create split silo databases. + + +### Step 2: Create Ngrok Config File +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: +tunnels: + acme-org: + proto: http + hostname: acme-org..ngrok.io + addr: 8000 + control-silo: + proto: http + hostname: .ngrok.io + host_header: "rewrite" + addr: 8000 + region-silo: + proto: http + hostname: us..ngrok.io + addr: 8010 + host_header: "rewrite" +``` + +### Step 3: Start Ngrok +Next start up ngrok with your configuration file: +```shell +ngrok start --all --config region.yml +``` + +### Step 4: Start Devserver +In two separate terminal windows, start the devserver for the control and region silos: + +```shell +getsentry devserver --ngrok .ngrok.io --workers --celery-beat --silo=region +getsentry devserver --ngrok .ngrok.io --workers --celery-beat --silo=control +``` + +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. + +### Setting up integrations +When setting up integrations for your local environment and the above setup, you should add the secrets and configurations for the integrations in the `getsentry/conf/settings/devlocal.py` file.