docs: network architecture (#932)

adela-bytebase · tianzhou · Copilot · web-flow · commit 792cc3318d69 · 2025-11-14T16:08:53.000+08:00
* update ngrok usage,emphasize it's for testing purpose only

* Update mintlify/snippets/install/start-with-ngrok.mdx

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;

* Update mintlify/tutorials/gitops-gitlab-workflow.mdx

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;

* Update mintlify/tutorials/gitops-azure-devops-workflow.mdx

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;

* Update mintlify/tutorials/gitops-github-workflow.mdx

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;

* Update mintlify/tutorials/gitops-bitbucket-workflow.mdx

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;

* network architecture

* update more

* update

* update

* update

* update

* Update mintlify/snippets/tutorials/bytebase-setup-options.mdx

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;

---------

Co-authored-by: Tianzhou &lt;t@bytebase.com&gt;
Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;
Co-authored-by: boojack &lt;stevenlgtm@gmail.com&gt;
diff --git a/mintlify/docs.json b/mintlify/docs.json
@@ -36,6 +36,7 @@
                   "get-started/self-host/deploy-with-docker",
                   "get-started/self-host/deploy-with-kubernetes",
                   "get-started/self-host/external-postgres",
+                  "get-started/self-host/network-architecture",
                   "get-started/self-host/external-access",
                   "get-started/self-host/external-url",
                   "get-started/self-host/production-setup",
diff --git a/mintlify/get-started/self-host/network-architecture.mdx b/mintlify/get-started/self-host/network-architecture.mdx
@@ -0,0 +1,49 @@
+---
+title: Network Architecture and External Access
+---
+
+This guide explains the network connectivity options for Bytebase features that require external access, including GitOps workflows, SSO authentication, and webhooks.
+
+## Features Requiring External Access
+
+- **GitOps Workflows**: CI/CD platforms (GitHub Actions, GitLab CI, etc.) need to call Bytebase API
+- **SSO Authentication**: OAuth2/OIDC/SAML providers need callback access
+- **Webhooks**: External services sending events to Bytebase
+
+## Three Network Patterns
+
+### 1. Bytebase Cloud
+Use [Bytebase Cloud](https://hub.bytebase.com/) for instant setup without infrastructure management. External services connect directly.
+
+**Best for:** Quick testing, evaluation, and small teams
+
+### 2. Self-Hosted Bytebase (Production)
+
+Keep Bytebase inside your private network for security.
+
+**With cloud CI/CD** (GitHub.com, GitLab.com, Bitbucket, Azure DevOps):
+
+- Works without self-hosted runners
+- Cloud CI/CD can call Bytebase directly (or via the required exposed endpoint)
+
+**With self-hosted CI/CD** (GitHub Enterprise Server, self-hosted GitLab, Jenkins):
+
+- Install self-hosted runners/agents inside your network
+- Runners connect to your internal Bytebase without exposing it to the internet
+
+**Best for:** Production setups with strict network boundaries.
+
+### 3. Self-Hosted Local Testing with Reverse Proxy
+
+Temporarily expose local Bytebase for testing using reverse proxy tools such as:
+- [ngrok](https://ngrok.com/)
+- [VS Code port forwarding](https://code.visualstudio.com/docs/editor/port-forwarding)
+- Other tunneling services
+
+<Warning>
+Never use reverse proxy tools in production. They are for local testing only.
+</Warning>
+
+<Info>
+**Important for Self-Hosted:** Remember to configure the External URL in Bytebase **Settings > General** with your public URL for SSO callbacks and other integrations to work properly.
+</Info>
diff --git a/mintlify/gitops/installation.mdx b/mintlify/gitops/installation.mdx
@@ -1,10 +1,13 @@
 ---
 title: Installation
-description: Installation and setup guide for connecting Version Control Systems with Bytebase
 ---
 
 This guide covers the setup requirements for connecting Version Control Systems (VCS) with Bytebase.
 
+<Info>
+For understanding network patterns and external access options, see the [Network Architecture guide](/get-started/self-host/network-architecture).
+</Info>
+
 ## Bytebase Cloud
 
 **No installation required** for cloud VCS providers:
@@ -51,3 +54,10 @@ When using cloud VCS with self-hosted Bytebase, you need a self-hosted runner:
 - Network policies allow communication
 - If your GitLab runner lacks internet access, pre-load the bytebase-action Docker image
 
+## Local Testing
+
+To expose local Bytebase for testing with cloud VCS services, use reverse proxy tools like ngrok. See [Network Architecture guide](/get-started/self-host/network-architecture#3-self-hosted-local-testing-with-reverse-proxy) for setup details.
+
+<Warning>
+For development and testing only. Never use in production.
+</Warning>
diff --git a/mintlify/gitops/migration-based-workflow/overview.mdx b/mintlify/gitops/migration-based-workflow/overview.mdx
@@ -55,6 +55,16 @@ Open a pull/merge request. Automated SQL review runs in CI/CD.
 
 After merge, CI/CD triggers Bytebase to create a release and deploy to target databases.
 
+## Tutorials
+
+<Card title="Tutorial: Database GitOps with GitHub Actions" icon="github" href="/tutorials/gitops-github-workflow" horizontal />
+
+<Card title="Tutorial: Database GitOps with Azure DevOps Pipeline" icon="microsoft" href="/tutorials/gitops-azure-devops-workflow" horizontal />
+
+<Card title="Tutorial: Database GitOps with GitLab CI" icon="gitlab" href="/tutorials/gitops-gitlab-workflow" horizontal />
+
+<Card title="Tutorial: Database GitOps with Bitbucket Pipelines" icon="bitbucket" href="/tutorials/gitops-bitbucket-workflow" horizontal />
+
 ---
 
 ## Next Steps
diff --git a/mintlify/snippets/install/start-with-ngrok.mdx b/mintlify/snippets/install/start-with-ngrok.mdx
diff --git a/mintlify/snippets/tutorials/bytebase-setup-options.mdx b/mintlify/snippets/tutorials/bytebase-setup-options.mdx
@@ -0,0 +1,24 @@
+import TerminalDockerRunVolume from '/snippets/install/terminal-docker-run-volume.mdx';
+
+<Tabs>
+  <Tab title="Cloud">
+    Use [Bytebase Cloud](https://hub.bytebase.com/) for instant setup without infrastructure management. CI/CD services can connect immediately.
+    
+    **Best for:** Quick testing, evaluation, and small teams
+  </Tab>
+  <Tab title="Self-Hosted">
+    Run Bytebase in Docker within your infrastructure:
+    
+    <TerminalDockerRunVolume />
+    
+    **Network Access Options:**
+    
+    - **For testing:** Use tools such as [ngrok](https://ngrok.com/) or [VS Code port forwarding](https://code.visualstudio.com/docs/editor/port-forwarding) to temporarily expose your local Bytebase to cloud CI/CD services. After exposing, configure the **External URL** in Bytebase **Settings > General**.
+    
+    - **For production:** Use self-hosted CI/CD runners within your private network. Never expose production Bytebase to the internet.
+    
+    **Best for:** Organizations with security requirements or existing infrastructure
+  </Tab>
+</Tabs>
+
+See [Network Architecture guide](/get-started/self-host/network-architecture#2-self-hosted-bytebase-production).
diff --git a/mintlify/tutorials/github-action-data-masking-part1.mdx b/mintlify/tutorials/github-action-data-masking-part1.mdx
@@ -11,7 +11,6 @@ description: 'Learn how to automate semantic type and global masking rule using
 ---
 
 import ApiPreface from '/snippets/tutorials/api-preface.mdx';
-import StartWithNgrok from '/snippets/install/start-with-ngrok.mdx';
 import CreateServiceAccount from '/snippets/tutorials/create-service-account.mdx';
 
 <ApiPreface />
@@ -41,18 +40,17 @@ The complete code for this tutorial is available at: [example-database-security]
 
 ## Prerequisites
 
-Before you begin, make sure you have:
-
-- [Docker](https://www.docker.com/) installed
+- A Bytebase instance (Bytebase Cloud or self-hosted) with Enterprise Plan
+- For self-hosted version, you need [Docker](https://www.docker.com/) to run Bytebase
 - A [GitHub](https://github.com/) account
-- An [ngrok](http://ngrok.com/) account
-- Bytebase Enterprise Plan subscription (you can request a free trial)
 
 ## Setup Instructions
 
-### Step 1 - Start Bytebase in Docker and set the External URL generated by ngrok
+### Step 1 - Set up Bytebase
+
+import BytebaseSetupOptions from '/snippets/tutorials/bytebase-setup-options.mdx';
 
-<StartWithNgrok />
+<BytebaseSetupOptions />
 
 ### Step 2 - Create Service Account
 
@@ -72,7 +70,7 @@ Before you begin, make sure you have:
 
 1. Click **Settings** and then click **Secrets and variables > Actions**. Add the following secrets:
 
-   - `BYTEBASE_URL`: ngrok external URL
+   - `BYTEBASE_URL`: Your Bytebase instance URL (e.g., `https://bytebase.your-company.com` or your Bytebase Cloud URL)
    - `BYTEBASE_SERVICE_KEY`: `api-example@service.bytebase.com`
    - `BYTEBASE_SERVICE_SECRET`: service key copied in the previous step
 
diff --git a/mintlify/tutorials/gitops-azure-devops-workflow.mdx b/mintlify/tutorials/gitops-azure-devops-workflow.mdx
@@ -9,7 +9,6 @@ level: Advanced
 estimated_time: '40 mins'
 ---
 
-import StartWithNgrok from '/snippets/install/start-with-ngrok.mdx';
 import CreateServiceAccountGitOps from '/snippets/tutorials/create-service-account-gitops.mdx';
 import ConfigSQLReview from '/snippets/tutorials/config-sql-review.mdx';
 
@@ -34,14 +33,16 @@ This tutorial code repository is at [https://dev.azure.com/bytebase-hq/\_git/byt
 
 ## Prerequisites
 
-- [Docker](https://www.docker.com/) installed
-- An [ngrok](https://ngrok.com/) account
+- A Bytebase instance (Bytebase Cloud or self-hosted)
+- For self-hosted version, you need [Docker](https://www.docker.com/) to run Bytebase
 
 ## Automatic Rollout across environments
 
-### Step 1 - Start Bytebase with ngrok
+### Step 1 - Set up Bytebase
 
-<StartWithNgrok />
+import BytebaseSetupOptions from '/snippets/tutorials/bytebase-setup-options.mdx';
+
+<BytebaseSetupOptions />
 
 ### Step 2 - Create Service Account
 
@@ -60,7 +61,7 @@ This tutorial code repository is at [https://dev.azure.com/bytebase-hq/\_git/byt
 
 1. Go into `pipelines/sql-review.yml` and `pipelines/rollout-release.yml`. In the `env` section, replace the variable values with your own and commit the changes.
 
-   - **BYTEBASE_URL**: your ngrok url
+   - **BYTEBASE_URL**: Your Bytebase instance URL (e.g., `https://bytebase.your-company.com` or your Bytebase Cloud URL)
    - **BYTEBASE_SERVICE_ACCOUNT**: `api-example@service.bytebase.com` (the service account you created in the previous step)
    - **BYTEBASE_PROJECT**: `projects/project-sample` (the sample project in the Bytebase)
    - **BYTEBASE_TARGETS**: `instances/test-sample-instance/databases/hr_test,instances/prod-sample-instance/databases/hr_prod` (the two default databases in the sample project)
diff --git a/mintlify/tutorials/gitops-bitbucket-workflow.mdx b/mintlify/tutorials/gitops-bitbucket-workflow.mdx
@@ -9,7 +9,6 @@ level: Advanced
 estimated_time: '40 mins'
 ---
 
-import StartWithNgrok from '/snippets/install/start-with-ngrok.mdx';
 import CreateServiceAccountGitOps from '/snippets/tutorials/create-service-account-gitops.mdx';
 import ConfigSQLReview from '/snippets/tutorials/config-sql-review.mdx';
 
@@ -42,14 +41,16 @@ https://bitbucket.org/p0nyyy/cicd/
 
 ## Prerequisites
 
-- [Docker](https://www.docker.com/) installed
-- An [ngrok](https://ngrok.com/) account
+- A Bytebase instance (Bytebase Cloud or self-hosted)
+- For self-hosted version, you need [Docker](https://www.docker.com/) to run Bytebase
 
 ## Automatic Rollout across environments
 
-### Step 1 - Start Bytebase with ngrok
+### Step 1 - Set up Bytebase
 
-<StartWithNgrok />
+import BytebaseSetupOptions from '/snippets/tutorials/bytebase-setup-options.mdx';
+
+<BytebaseSetupOptions />
 
 ### Step 2 - Create Service Account
 
@@ -67,7 +68,7 @@ _Note: Usually we enable SQL review for `Prod` environment as above. In this dem
 
 1. Go into `bitbucket-pipelines.yml`, replace the variable in all 3 steps the values with your own and commit the changes.
 
-   - **BYTEBASE_URL**: your ngrok url
+   - **BYTEBASE_URL**: Your Bytebase instance URL (e.g., `https://bytebase.your-company.com` or your Bytebase Cloud URL)
    - **BYTEBASE_SERVICE_ACCOUNT**: `api-example@service.bytebase.com` (the service account you created in the previous step)
    - **BYTEBASE_SERVICE_ACCOUNT_SECRET**: the password of the service account
 
diff --git a/mintlify/tutorials/gitops-github-workflow.mdx b/mintlify/tutorials/gitops-github-workflow.mdx
@@ -9,7 +9,6 @@ level: Advanced
 estimated_time: '40 mins'
 ---
 
-import StartWithNgrok from '/snippets/install/start-with-ngrok.mdx';
 import CreateServiceAccountGitOps from '/snippets/tutorials/create-service-account-gitops.mdx';
 import ConfigSQLReview from '/snippets/tutorials/config-sql-review.mdx';
 
@@ -46,14 +45,16 @@ https://github.com/bytebase/example-gitops-github-flow
 
 ## Prerequisites
 
-- [Docker](https://www.docker.com/) installed
-- An [ngrok](https://ngrok.com/) account
+- A Bytebase instance (Bytebase Cloud or self-hosted)
+- For self-hosted version, you need [Docker](https://www.docker.com/) to run Bytebase.
 
 ## Automatic Rollout across environments
 
-### Step 1 - Start Bytebase with ngrok
+### Step 1 - Set up Bytebase
 
-<StartWithNgrok />
+import BytebaseSetupOptions from '/snippets/tutorials/bytebase-setup-options.mdx';
+
+<BytebaseSetupOptions />
 
 ### Step 2 - Create Service Account
 
@@ -73,7 +74,7 @@ https://github.com/bytebase/example-gitops-github-flow
 
 1. Go into `.github/workflows/release-action.yml` and `.github/workflows/sql-review-action.yml`. In the `env` section, replace the variable values with your own and commit the changes.
 
-   - **BYTEBASE_URL**: your ngrok url
+   - **BYTEBASE_URL**: Your Bytebase instance URL (e.g., `https://bytebase.your-company.com` or your Bytebase Cloud URL)
    - **BYTEBASE_SERVICE_ACCOUNT**: `api-example@service.bytebase.com` (the service account you created in the previous step)
    - **BYTEBASE_PROJECT**: `projects/project-sample` (the sample project in the Bytebase)
    - **BYTEBASE_TARGETS**: `instances/test-sample-instance/databases/hr_test,instances/prod-sample-instance/databases/hr_prod` (the two default databases in the sample project)
@@ -182,7 +183,7 @@ Team members can trigger deployments by commenting `/migrate <environment>` on a
 
 1. Go into `.github/workflows/chatops-migrate.yml`. In the `env` section, replace the variable values with your own:
 
-   - **BYTEBASE_URL**: your ngrok url
+   - **BYTEBASE_URL**: Your Bytebase instance URL (e.g., `https://bytebase.your-company.com` or your Bytebase Cloud URL)
    - **BYTEBASE_SERVICE_ACCOUNT**: `api-example@service.bytebase.com`
    - **BYTEBASE_PROJECT**: `projects/project-sample`
    - **FILE_PATTERN**: `migrations-semver/*.sql`
diff --git a/mintlify/tutorials/gitops-gitlab-workflow.mdx b/mintlify/tutorials/gitops-gitlab-workflow.mdx
@@ -10,7 +10,6 @@ estimated_time: '40 mins'
 featured: true
 ---
 
-import StartWithNgrok from '/snippets/install/start-with-ngrok.mdx';
 import CreateServiceAccountGitOps from '/snippets/tutorials/create-service-account-gitops.mdx';
 import ConfigSQLReview from '/snippets/tutorials/config-sql-review.mdx';
 
@@ -43,14 +42,16 @@ https://gitlab.com/bytebase-sample/gitops-example
 
 ## Prerequisites
 
-- [Docker](https://www.docker.com/) installed
-- An [ngrok](https://ngrok.com/) account
+- A Bytebase instance (Bytebase Cloud or self-hosted)
+- For self-hosted version, you need [Docker](https://www.docker.com/) to run Bytebase
 
-## Enable Automatic Rollout Across Environments
+## Automatic Rollout across environments
 
-### Step 1 - Start Bytebase with ngrok
+### Step 1 - Set up Bytebase
 
-<StartWithNgrok />
+import BytebaseSetupOptions from '/snippets/tutorials/bytebase-setup-options.mdx';
+
+<BytebaseSetupOptions />
 
 ### Step 2 - Create Service Account
 
@@ -72,7 +73,7 @@ _Note: Usually we enable SQL review for `Prod` environment as above. In this dem
 
 1. Go into `bytebase-review.yml` and `bytebase-rollout.yml`. In the `env` section, replace the variable values with your own and commit the changes.
 
-   - **BYTEBASE_URL**: your ngrok url
+   - **BYTEBASE_URL**: Your Bytebase instance URL (e.g., `https://bytebase.your-company.com` or your Bytebase Cloud URL)
    - **BYTEBASE_SERVICE_ACCOUNT**: `api-example@service.bytebase.com` (the service account you created in the previous step)
    - **BYTEBASE_SERVICE_ACCOUNT_SECRET**: the password of the service account
 
diff --git a/mintlify/tutorials/sql-review-api.mdx b/mintlify/tutorials/sql-review-api.mdx
@@ -9,8 +9,6 @@ level: Intermediate
 estimated_time: '30 mins'
 ---
 
-import StartWithNgrok from '/snippets/install/start-with-ngrok.mdx';
-
 When modifying data in the database, it's crucial to ensure that the changes are both safe and accurate. Bytebase offers a feature called [SQL Review](/sql-review/review-policy/), which allows you to evaluate your SQL changes before they are applied to the database. SQL Review can be invoked from the Bytebase GUI, CI or API.
 
 This is one of the tutorial series of SQL Review:
@@ -30,9 +28,9 @@ This tutorial will walk you through using SQL Review in Bytebase with Bytebase A
 
 Make sure you have completed the previous tutorial [SQL Review with Bytebase GUI](/tutorials/sql-review-gui/).
 
-If you want to test the SQL Review API locally, you may need to configure ngrok.
-
-<StartWithNgrok />
+<Info>
+If you want to test the SQL Review API locally with cloud CI/CD services, you'll need to expose your local Bytebase instance. See [Network Architecture guide](/get-started/self-host/network-architecture) for options like ngrok or VS Code port forwarding.
+</Info>
 
 ## API Examples
 
