diff --git a/mintlify/docs.json b/mintlify/docs.json index c50e7f72a..34efbe3ea 100644 --- 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 new file mode 100644 index 000000000..d397e4e96 --- /dev/null +++ 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 + + +Never use reverse proxy tools in production. They are for local testing only. + + + +**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. + diff --git a/mintlify/gitops/installation.mdx b/mintlify/gitops/installation.mdx index 77b51b337..d56d1acf7 100644 --- 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. + +For understanding network patterns and external access options, see the [Network Architecture guide](/get-started/self-host/network-architecture). + + ## 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. + + +For development and testing only. Never use in production. + \ No newline at end of file diff --git a/mintlify/gitops/migration-based-workflow/overview.mdx b/mintlify/gitops/migration-based-workflow/overview.mdx index 4c30ab331..f359a8af3 100644 --- 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 + + + + + + + + + --- ## Next Steps diff --git a/mintlify/snippets/install/start-with-ngrok.mdx b/mintlify/snippets/install/start-with-ngrok.mdx deleted file mode 100644 index de9beb2bf..000000000 --- a/mintlify/snippets/install/start-with-ngrok.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Start with ngrok ---- - -import TerminalDockerRunVolume from '/snippets/install/terminal-docker-run-volume.mdx'; - -[ngrok](https://ngrok.com/) is a reverse proxy tunnel that provides a public network address to access Bytebase. We use ngrok here for demonstration purposes. - - ![ngrok-reverse-proxy](/content/docs/get-started/start-with-ngrok/ngrok-reverse-proxy.webp) - -1. Run Bytebase in [Docker](https://www.docker.com/) with the following command: - - - -1. Once Bytebase is running in Docker, you can access it at `localhost:8080`. - -1. Log in to the [ngrok Dashboard](https://dashboard.ngrok.com/get-started/setup) and complete the **Getting Started** steps to install and configure ngrok. To use a consistent domain, navigate to **Universal Gateway > Endpoints** to find your assigned domain: `<>.ngrok-free.app`. - -1. Start ngrok with your domain by running: - - ```bash - ngrok http --url=<>.ngrok-free.app 8080 - ``` - - You should see output similar to this: - - ![terminal-ngrok](/content/docs/get-started/start-with-ngrok/ngrok-terminal.webp) - -1. You can now access Bytebase at `https://<>.ngrok-free.app`. - -1. (Optional) To configure SSO (Entra/SCIM), log in to Bytebase, click **Settings > General** in the left sidebar. Scroll to the **Network** section, set `https://<>.ngrok-free.app` as the **External URL** and click **Confirm and update**. - - ![external-url](/content/docs/get-started/start-with-ngrok/bb-external-url.webp) diff --git a/mintlify/snippets/tutorials/bytebase-setup-options.mdx b/mintlify/snippets/tutorials/bytebase-setup-options.mdx new file mode 100644 index 000000000..43c9225f1 --- /dev/null +++ b/mintlify/snippets/tutorials/bytebase-setup-options.mdx @@ -0,0 +1,24 @@ +import TerminalDockerRunVolume from '/snippets/install/terminal-docker-run-volume.mdx'; + + + + 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 + + + Run Bytebase in Docker within your infrastructure: + + + + **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 + + + +See [Network Architecture guide](/get-started/self-host/network-architecture#2-self-hosted-bytebase-production). \ No newline at end of file diff --git a/mintlify/tutorials/github-action-data-masking-part1.mdx b/mintlify/tutorials/github-action-data-masking-part1.mdx index d424adb41..e92e6ace6 100644 --- 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'; @@ -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'; - + ### 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 index 9830d266a..74279a730 100644 --- 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 - +import BytebaseSetupOptions from '/snippets/tutorials/bytebase-setup-options.mdx'; + + ### 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 index 70161f4bd..001224ef0 100644 --- 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 - +import BytebaseSetupOptions from '/snippets/tutorials/bytebase-setup-options.mdx'; + + ### 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 index 1251cec2e..cfad88b58 100644 --- 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 - +import BytebaseSetupOptions from '/snippets/tutorials/bytebase-setup-options.mdx'; + + ### 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 ` 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 index 428e2bbf7..aa58dd5f1 100644 --- 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 - +import BytebaseSetupOptions from '/snippets/tutorials/bytebase-setup-options.mdx'; + + ### 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 index 7be32ae00..02f8a000f 100644 --- 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. - - + +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. + ## API Examples