docs: update guide for running builder against local CDK changes (#14…

…997)

airbyte-connector-builder-server/README.md

@@ -8,55 +8,65 @@ we deprecated the old server and all image versions from `0.45.20` onward are ba
 
 ### Install CDK dependencies
 
-The Connector Builder API server sends commands to an entrypoint of the Airbyte CDK. Therefore, to build the Connector Builder server, an installation of the CDK needs to be available and the `CDK_VERSION` environment needs to be set to a compatible version of the CDK. The earliest compatible version of the CDK is 0.31.1.
+The Connector Builder API server sends commands to an entrypoint of the Airbyte CDK.
 
-To set up a local CDK environment, navigate to the airbyte-cdk/python folder in your local airbyte repo and create your CDK environment:
+To set up a local CDK environment, navigate to the `airbyte_cdk` folder in your local `airbyte-python-cdk` repo and create your CDK environment:
 
 ```bash
+pyenv local 3.10  # use the python version compatible with the CDK
+poetry config --local virtualenvs.in-project true  # optional - this creates the .venv folder in the repo's directory
+poetry env use $(pyenv which python)
 poetry install
 ```
 
 If `poetry` cannot be found, run `pip install poetry` first.
 
-You will need to add the path to this environment in the next steps. You can run `poetry show -v` to verify it.
-
-#### Setting your Python version
-
-The Python CDK is not currently compatible with the latest versions of Python. If you are using an incompatible version Python, we recommend using `pyenv` to manage the Python version locally:
+If you run into permission issues, you may need to run `poetry install` as root.
 
-```bash
-pyenv local 3.10
-poetry env use $(pyenv which python)
-poetry install
-```
+You will need to add the path to this environment in the next steps. You can run `poetry show -v` to verify it.
 
-### Compile, build and run the server
+### Compile, build and run the Builder server
 
-From the root folder of your local airbyte-platform-internal repo, run the build command:
+From the root folder of your local `airbyte-platform-internal` repo, run the build command:
 
 ```bash
 ./gradlew :oss:airbyte-connector-builder-server:build
 ```
 
-To develop the server locally (without Docker), the `CDK_PYTHON` and `CDK_ENTRYPOINT` environment variables need to be set, where `CDK_PYTHON` is the path to the python interpreter you want to use, i.e. in which the CDK is installed, and `CDK_ENTRYPOINT` is the path to the Connector Builder entrypoint, located at <CDK directory/connector_builder/main.py>.
+To develop the server locally (without Docker), the `CDK_PYTHON` and `CDK_ENTRYPOINT` environment variables need to be set, where `CDK_PYTHON` is the path to the python interpreter you want to use, i.e. in which the CDK is installed, and `CDK_ENTRYPOINT` is the path to the Connector Builder entrypoint, located at `<CDK directory>/connector_builder/main.py`.
 
 ```bash
 export CDK_PYTHON=<path_to_CDK_virtual_environment>
 export CDK_ENTRYPOINT=<path_to_CDK_connector_builder_main.py>
 ```
 
+The `CDK_PYTHON` path can be found by running `poetry show -v` in your local python CDK directory, and appending `/bin/python` to the end of it. 
+
 Example commands:
 ```
-export CDK_PYTHON=~/code/airbyte/airbyte-cdk/python/.venv/bin/python
-export CDK_ENTRYPOINT=~/code/airbyte/airbyte-cdk/python/airbyte_cdk/connector_builder/main.py
+export CDK_PYTHON=~/code/airbyte-python-cdk/.venv/bin/python
+export CDK_ENTRYPOINT=~/code/airbyte-python-cdk/airbyte_cdk/connector_builder/main.py
 ```
 
-Then run the server (You can also do this w/o build)
+Then run the server (you can also do this w/o build), from the root of your local `airbyte-platform-internal` repo:
 
 ```bash
 ./gradlew :oss:airbyte-connector-builder-server:run
 ```
 
+A successfully running server will look like this in the terminal (it stays at `99% EXECUTING` forever):
+```bash
+2025-01-13 19:15:35,152 [main]  INFO        i.m.r.Micronaut(start):101 - Startup completed in 6229ms. Server Running: http://localhost:8080
+<============-> 99% EXECUTING [47m 43s]
+> IDLE
+> IDLE
+> IDLE
+> IDLE
+> IDLE
+> :oss:airbyte-connector-builder-server:run
+> IDLE
+```
+
 If you experience any issues, try running the full command as:
 
 ```bash
@@ -68,9 +78,9 @@ The server is now reachable on localhost:8080
 
 ### Run the full platform locally
 
-If you want to run the full platform locally using your local python CDK code, first follow the steps laid out above to get a locally-running gradle builder server pointing at your local CDK code. 
+If you want to run the full platform locally using your local python CDK code, e.g. in order to point your local Builder UI at your local CDK, first follow the steps laid out above to get a locally-running gradle builder server pointing at your local CDK code. 
 
-You must then make two changes:
+You must then make two changes to your local `airbyte-platform-internal` repo:
 1. The `airbyte-server` makes requests to the builder server (e.g. read_stream), so these must be redirected to the locally-running gradle builder server by editing the `oss/charts/airbyte/templates/env-configmap.yaml` as follows:
     ```bash
     # replace this
@@ -98,9 +108,14 @@ You must then make two changes:
     pnpm start oss-k8s
     ```
 
-If you then go to https://localhost:3000/ in your browser, and navigate to the connector builder, all requests directed toward the connector builder server will now be sent to your locally-running gradle builder server that uses your local CDK code.
+If you then go to https://localhost:3000/ in your browser, and navigate to the connector builder, all requests directed toward the connector builder server will now be sent to your locally-running gradle builder server that uses your local CDK code, and the UI will use your local airbyte-webapp code.
+
+With this setup, testing local changes end-to-end is much faster and easier:
+1. To test a python CDK change with the Builder UI, simply edit the desired python files in the `airbyte_cdk` folder and the changes will be immediately reflected in any requests that are sent from the Builder UI.
+2. To test a builder-server change, edit the desired java/kotlin files in the `airbyte-connector-builder-server` folder, then cancel the currently-running `./gradlew :oss:airbyte-connector-builder-server:run` gradle command and re-run it. Once the server is running again, the changes will be reflected in any requests that are sent from the Builder UI.
+3. To test a change to the Builder UI itself, simply edit the desired typescript file in the `airbyte-webapp` folder, and the saved changes will be immediately reflected in the browser.
 
-From this point forward, you can simply edit python files under the `airbyte-cdk/python` directory, and those changes will immediately be reflected in any requests that are sent from the Builder UI.
+---
 
 ### Running the platform with support for custom components