From baf170cf5c7fac086cb12e8b87d624a0cde8f726 Mon Sep 17 00:00:00 2001 From: Alexander Darby <63904626+osintalex@users.noreply.github.com> Date: Mon, 27 May 2024 15:05:26 +0100 Subject: [PATCH 1/7] feat: skaffold yaml working --- skaffold.yaml | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 skaffold.yaml diff --git a/skaffold.yaml b/skaffold.yaml new file mode 100644 index 0000000000..bed633e0f2 --- /dev/null +++ b/skaffold.yaml @@ -0,0 +1,36 @@ +apiVersion: skaffold/v4beta11 +kind: Config +metadata: + name: browsertrix +build: + artifacts: + - image: docker.io/webrecorder/browsertrix-backend + context: backend + docker: + dockerfile: Dockerfile + sync: + manual: + - src: 'btrixcloud/**/*' + dest: . + - image: docker.io/webrecorder/browsertrix-frontend + context: frontend + docker: + dockerfile: Dockerfile + sync: + manual: + - src: 'src/**/*' + dest: . +deploy: + helm: + releases: + - name: btrix + chartPath: chart + valuesFiles: + - chart/values.yaml + # local must come after since it overrides stuff in values.yaml + - chart/local.yaml + # See https://skaffold.dev/docs/deployers/helm/ + # must do this to make skaffold use local images with helm + setValues: + backend_image: docker.io/webrecorder/browsertrix-backend + frontend_image: docker.io/webrecorder/browsertrix-frontend \ No newline at end of file From 66f7a581732fa13d45093466c7f9e74928a8f984 Mon Sep 17 00:00:00 2001 From: Alexander Darby <63904626+osintalex@users.noreply.github.com> Date: Mon, 27 May 2024 18:02:37 +0100 Subject: [PATCH 2/7] feat: backend hot reload with skaffold --- chart/templates/backend.yaml | 7 +++++++ docs/develop/backend-hot-reload.md | 27 +++++++++++++++++++++++++ docs/develop/frontend-dev.md | 8 +++++++- docs/develop/local-dev-setup.md | 6 +++++- mkdocs.yml | 1 + skaffold.yaml | 32 ++++++++++++++++++++---------- 6 files changed, 68 insertions(+), 13 deletions(-) create mode 100644 docs/develop/backend-hot-reload.md diff --git a/chart/templates/backend.yaml b/chart/templates/backend.yaml index a1577288ed..7097636b30 100644 --- a/chart/templates/backend.yaml +++ b/chart/templates/backend.yaml @@ -55,6 +55,12 @@ spec: - name: api image: {{ .Values.backend_image }} imagePullPolicy: {{ .Values.backend_pull_policy }} + {{- if .Values.backend_api_command_override }} + command: + {{- range .Values.backend_api_command_override }} + - {{ . | quote }} + {{- end }} + {{- else }} command: - gunicorn - btrixcloud.main:app_root @@ -66,6 +72,7 @@ spec: - "{{ .Values.backend_workers | default 1 }}" - --worker-class - uvicorn.workers.UvicornWorker + {{- end }} envFrom: - configMapRef: diff --git a/docs/develop/backend-hot-reload.md b/docs/develop/backend-hot-reload.md new file mode 100644 index 0000000000..f272718380 --- /dev/null +++ b/docs/develop/backend-hot-reload.md @@ -0,0 +1,27 @@ +# Deploy the Backend with Hot Reloading + +This guide explains how to deploy Browsertrix with [skaffold](https://skaffold.dev/) so the backend hot reloads. This +may save you time since you don't need to rebuild the backend container every time you change code. + +## Requirements + +Follow the documentation to [install skaffold](https://skaffold.dev/docs/install/), i.e. if you are on +Mac OS run: + +```sh +brew install skaffold +``` + +To install helm and set up a local Kubernetes cluster, see the section on [local dev set up](local-dev-setup.md). + +## Quickstart + +From the command line, run: + +```sh +skaffold dev +``` + +This will deploy Browsertrix into the cluster and port forward the API with hot reloading. +Navigate to `localhost:8000/api/redoc` to see the documentation. +Changing any code in `backend/btrixcloud` will trigger a reload. \ No newline at end of file diff --git a/docs/develop/frontend-dev.md b/docs/develop/frontend-dev.md index 61d255ec0e..5b7f327025 100644 --- a/docs/develop/frontend-dev.md +++ b/docs/develop/frontend-dev.md @@ -72,6 +72,12 @@ If connecting to a local deployment cluster, set `API_BASE_URL` to: API_BASE_URL=http://localhost:30870 ``` +If the API is not running at `localhost:30870`, port forward it from your local cluster: + +```sh +kubectl port-forward svc/browsertrix-cloud-backend 30870:8000 +``` + ??? info "Port when using Minikube (on macOS)" When using Minikube on macOS, the port will not be 30870. Instead, Minikube opens a tunnel to a random port, @@ -85,7 +91,7 @@ Start the frontend development server: yarn start ``` -This will open `localhost:9870` in a new tab in your default browser. +This will open `localhost:9870` in a new tab in your default browser. It will take a few minutes to finish. Saving changes to files in `src` will automatically reload your browser window with the latest UI updates. diff --git a/docs/develop/local-dev-setup.md b/docs/develop/local-dev-setup.md index dd0def5963..082a82b4fa 100644 --- a/docs/develop/local-dev-setup.md +++ b/docs/develop/local-dev-setup.md @@ -116,7 +116,7 @@ helm upgrade --install -f ./chart/values.yaml \ ??? info "MicroK8S" - If using microk8s, the commend will be: + If using microk8s, the command will be: ```sh microk8s helm3 upgrade --install -f ./chart/values.yaml -f ./chart/local.yaml btrix ./chart/ @@ -133,3 +133,7 @@ Changes to settings in `./chart/local.yaml` can be deployed with `helm upgrade . ## Deploying Frontend Only If you are just making changes to the frontend, you can also [deploy the frontend separately](frontend-dev.md) using a dev server for quicker iteration. + +## Deploying Backend with Hot Reloading + +If you want to iterate faster on the backend, read [deploy the backend with hot reloading](backend-hot-reload.md). \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 107c95dc6d..72dbb8bd6e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -63,6 +63,7 @@ nav: - develop/local-dev-setup.md - develop/frontend-dev.md - develop/docs.md + - develop/backend-hot-reload.md - User Guide: - user-guide/index.md - user-guide/signup.md diff --git a/skaffold.yaml b/skaffold.yaml index bed633e0f2..98a8374e50 100644 --- a/skaffold.yaml +++ b/skaffold.yaml @@ -4,6 +4,8 @@ metadata: name: browsertrix build: artifacts: + # only put the backend in here since it's quite easy now + # to run frontend locally and get hot reloading with yarn - image: docker.io/webrecorder/browsertrix-backend context: backend docker: @@ -12,14 +14,14 @@ build: manual: - src: 'btrixcloud/**/*' dest: . - - image: docker.io/webrecorder/browsertrix-frontend - context: frontend - docker: - dockerfile: Dockerfile - sync: - manual: - - src: 'src/**/*' - dest: . +portForward: +- resourceType: service + resourceName: browsertrix-cloud-backend + # assumes you are doing local dev in `default` namespace + # if you aren't you need to change this manually + namespace: default + port: 8000 + localPort: 8000 deploy: helm: releases: @@ -27,10 +29,18 @@ deploy: chartPath: chart valuesFiles: - chart/values.yaml - # local must come after since it overrides stuff in values.yaml - - chart/local.yaml # See https://skaffold.dev/docs/deployers/helm/ # must do this to make skaffold use local images with helm setValues: backend_image: docker.io/webrecorder/browsertrix-backend - frontend_image: docker.io/webrecorder/browsertrix-frontend \ No newline at end of file + backend_pull_policy: "Never" + # hot reloading doesn't work with default gunicorn command + # so need to override to use uvicorn + backend_api_command_override: + - uvicorn + - btrixcloud.main:app_root + - --reload + - --host + - "0.0.0.0" + - --port + - "8000" \ No newline at end of file From 35b74633fac7d633f041fa7ff0083abdcf63bd27 Mon Sep 17 00:00:00 2001 From: Alexander Darby <63904626+osintalex@users.noreply.github.com> Date: Mon, 27 May 2024 18:09:32 +0100 Subject: [PATCH 3/7] chore: add trailing newlines --- docs/develop/backend-hot-reload.md | 2 +- skaffold.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/develop/backend-hot-reload.md b/docs/develop/backend-hot-reload.md index f272718380..270a0638ef 100644 --- a/docs/develop/backend-hot-reload.md +++ b/docs/develop/backend-hot-reload.md @@ -24,4 +24,4 @@ skaffold dev This will deploy Browsertrix into the cluster and port forward the API with hot reloading. Navigate to `localhost:8000/api/redoc` to see the documentation. -Changing any code in `backend/btrixcloud` will trigger a reload. \ No newline at end of file +Changing any code in `backend/btrixcloud` will trigger a reload. diff --git a/skaffold.yaml b/skaffold.yaml index 98a8374e50..3335e93b26 100644 --- a/skaffold.yaml +++ b/skaffold.yaml @@ -43,4 +43,4 @@ deploy: - --host - "0.0.0.0" - --port - - "8000" \ No newline at end of file + - "8000" From 39c4a1b11dbd1d5542a9fcfbc1dc32c9ddd136c7 Mon Sep 17 00:00:00 2001 From: Alexander Darby <63904626+osintalex@users.noreply.github.com> Date: Mon, 27 May 2024 23:25:34 +0100 Subject: [PATCH 4/7] feat: add debugger and prioritise local values yaml --- .../backend-hot-reload-and-debugger.md | 62 +++++++++++++++++++ docs/develop/backend-hot-reload.md | 27 -------- docs/develop/local-dev-setup.md | 2 +- mkdocs.yml | 2 +- skaffold.yaml | 31 ++++++---- 5 files changed, 83 insertions(+), 41 deletions(-) create mode 100644 docs/develop/backend-hot-reload-and-debugger.md delete mode 100644 docs/develop/backend-hot-reload.md diff --git a/docs/develop/backend-hot-reload-and-debugger.md b/docs/develop/backend-hot-reload-and-debugger.md new file mode 100644 index 0000000000..dffc8c1c6f --- /dev/null +++ b/docs/develop/backend-hot-reload-and-debugger.md @@ -0,0 +1,62 @@ +# Deploy the Backend with Hot Reloading and Interactive Debugging + +This guide explains how to deploy Browsertrix with [skaffold](https://skaffold.dev/) +so the backend hot reloads and allows interactive debugging. + +This may save time since you don't need to rebuild the backend container every time you change code +and can use a debugger to step through code. + +## Requirements + +Follow the documentation to [install skaffold](https://skaffold.dev/docs/install/), i.e. if you are on +Mac OS run: + +```sh +brew install skaffold +``` + +To install helm and set up a local Kubernetes cluster, see the section on [local dev set up](local-dev-setup.md). + +## Quickstart + +From the command line, run: + +```sh +skaffold dev +``` + +This will deploy Browsertrix into the cluster and port forward the API with hot reloading. +Navigate to `localhost:8000/api/redoc` or `localhost:8000/api/docs` to see the documentation. +Changing any code in `backend/btrixcloud` will trigger a reload. + +### Debugger + +Interactive debugging uses [debugpy](https://github.com/microsoft/debugpy), which +works on VSCode but not PyCharm. + +Use this debug configuration in VSCode: + +```JSON +{ + "name": "Attach to Browsertrix Backend", + "type": "debugpy", + "request": "attach", + "connect": { + "host": "127.0.0.1", + "port": 5678 + }, + "pathMappings": [ + { + "localRoot": "${workspaceFolder}/backend/btrixcloud/", + "remoteRoot": "/app/btrixcloud/" + } + ], + "justMyCode": false +} +``` + +This will attach to the Kubernetes pod running Browsertrix and persist between +hot reloads. Change your code, wait for the application to reload, +and still hit breakpoints in the same debugging session. + + diff --git a/docs/develop/backend-hot-reload.md b/docs/develop/backend-hot-reload.md deleted file mode 100644 index 270a0638ef..0000000000 --- a/docs/develop/backend-hot-reload.md +++ /dev/null @@ -1,27 +0,0 @@ -# Deploy the Backend with Hot Reloading - -This guide explains how to deploy Browsertrix with [skaffold](https://skaffold.dev/) so the backend hot reloads. This -may save you time since you don't need to rebuild the backend container every time you change code. - -## Requirements - -Follow the documentation to [install skaffold](https://skaffold.dev/docs/install/), i.e. if you are on -Mac OS run: - -```sh -brew install skaffold -``` - -To install helm and set up a local Kubernetes cluster, see the section on [local dev set up](local-dev-setup.md). - -## Quickstart - -From the command line, run: - -```sh -skaffold dev -``` - -This will deploy Browsertrix into the cluster and port forward the API with hot reloading. -Navigate to `localhost:8000/api/redoc` to see the documentation. -Changing any code in `backend/btrixcloud` will trigger a reload. diff --git a/docs/develop/local-dev-setup.md b/docs/develop/local-dev-setup.md index 082a82b4fa..759dcd2016 100644 --- a/docs/develop/local-dev-setup.md +++ b/docs/develop/local-dev-setup.md @@ -136,4 +136,4 @@ If you are just making changes to the frontend, you can also [deploy the fronten ## Deploying Backend with Hot Reloading -If you want to iterate faster on the backend, read [deploy the backend with hot reloading](backend-hot-reload.md). \ No newline at end of file +If you want to iterate faster on the backend, read [deploy the backend with hot reloading and interactive debugging](backend-hot-reload-and-debugger.md). \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 72dbb8bd6e..f182782e85 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -63,7 +63,7 @@ nav: - develop/local-dev-setup.md - develop/frontend-dev.md - develop/docs.md - - develop/backend-hot-reload.md + - develop/backend-hot-reload-and-debugger.md - User Guide: - user-guide/index.md - user-guide/signup.md diff --git a/skaffold.yaml b/skaffold.yaml index 3335e93b26..96e870b50a 100644 --- a/skaffold.yaml +++ b/skaffold.yaml @@ -15,13 +15,18 @@ build: - src: 'btrixcloud/**/*' dest: . portForward: +# so you can hit the API on `localhost:8000` - resourceType: service resourceName: browsertrix-cloud-backend - # assumes you are doing local dev in `default` namespace - # if you aren't you need to change this manually namespace: default port: 8000 localPort: 8000 +# for the debugger +- resourceType: deployment + resourceName: browsertrix-cloud-backend + namespace: default + port: 5678 + localPort: 5678 deploy: helm: releases: @@ -29,18 +34,20 @@ deploy: chartPath: chart valuesFiles: - chart/values.yaml + # local must come after values since it is expected to override + - chart/local.yaml # See https://skaffold.dev/docs/deployers/helm/ # must do this to make skaffold use local images with helm setValues: - backend_image: docker.io/webrecorder/browsertrix-backend - backend_pull_policy: "Never" # hot reloading doesn't work with default gunicorn command # so need to override to use uvicorn - backend_api_command_override: - - uvicorn - - btrixcloud.main:app_root - - --reload - - --host - - "0.0.0.0" - - --port - - "8000" + # plus need to start the process with debugpy to debug + backend_api_command_override: + - sh + - -c + - > + pip install --no-input debugpy + && + python -m debugpy --listen 0.0.0.0:5678 + -m uvicorn btrixcloud.main:app_root + --reload --host 0.0.0.0 --port 8000 From afa83068ff2c448f7f98793bb537d0e9cceaed7d Mon Sep 17 00:00:00 2001 From: Alexander Darby <63904626+osintalex@users.noreply.github.com> Date: Sat, 13 Jul 2024 13:54:01 +0100 Subject: [PATCH 5/7] feat: debug and hot reload for op container --- chart/templates/backend.yaml | 8 ++++- .../backend-hot-reload-and-debugger.md | 30 ++++++++++++++++--- skaffold.yaml | 25 ++++++++++++++++ 3 files changed, 58 insertions(+), 5 deletions(-) diff --git a/chart/templates/backend.yaml b/chart/templates/backend.yaml index 7097636b30..e61252965f 100644 --- a/chart/templates/backend.yaml +++ b/chart/templates/backend.yaml @@ -147,6 +147,12 @@ spec: - name: op image: {{ .Values.backend_image }} imagePullPolicy: {{ .Values.backend_pull_policy }} + {{- if .Values.backend_op_command_override }} + command: + {{- range .Values.backend_op_command_override }} + - {{ . | quote }} + {{- end }} + {{- else }} command: - gunicorn - btrixcloud.main_op:app_root @@ -158,7 +164,7 @@ spec: - "{{ .Values.backend_workers | default 1 }}" - --worker-class - uvicorn.workers.UvicornWorker - + {{- end }} envFrom: - configMapRef: name: backend-env-config diff --git a/docs/develop/backend-hot-reload-and-debugger.md b/docs/develop/backend-hot-reload-and-debugger.md index dffc8c1c6f..03c87a2b7e 100644 --- a/docs/develop/backend-hot-reload-and-debugger.md +++ b/docs/develop/backend-hot-reload-and-debugger.md @@ -26,19 +26,25 @@ skaffold dev ``` This will deploy Browsertrix into the cluster and port forward the API with hot reloading. -Navigate to `localhost:8000/api/redoc` or `localhost:8000/api/docs` to see the documentation. -Changing any code in `backend/btrixcloud` will trigger a reload. + +Navigate to `localhost:8000/api/redoc` or `localhost:8000/api/docs` to see the documentation +for the api container. + +Navigate to `http://localhost:8756/redoc` or `http://localhost:8756/docs` to see the documentation +for the op container. + +Changing any code in `backend/btrixcloud` will trigger a reload in both the op and api containers. ### Debugger Interactive debugging uses [debugpy](https://github.com/microsoft/debugpy), which works on VSCode but not PyCharm. -Use this debug configuration in VSCode: +Use these debug configurations in VSCode: ```JSON { - "name": "Attach to Browsertrix Backend", + "name": "Attach to Browsertrix Backend API", "type": "debugpy", "request": "attach", "connect": { @@ -52,6 +58,22 @@ Use this debug configuration in VSCode: } ], "justMyCode": false +}, +{ + "name": "Attach to Browsertrix Backend OP", + "type": "debugpy", + "request": "attach", + "connect": { + "host": "127.0.0.1", + "port": 5679 + }, + "pathMappings": [ + { + "localRoot": "${workspaceFolder}/backend/btrixcloud/", + "remoteRoot": "/app/btrixcloud/" + } + ], + "justMyCode": false } ``` diff --git a/skaffold.yaml b/skaffold.yaml index 96e870b50a..a156fd7544 100644 --- a/skaffold.yaml +++ b/skaffold.yaml @@ -27,6 +27,19 @@ portForward: namespace: default port: 5678 localPort: 5678 +# so you can hit the op container on `localhost:8756` +- resourceType: service + resourceName: browsertrix-cloud-backend + namespace: default + # can't references {{ Values. }} hence hardcoding + port: 8756 + localPort: 8756 +# for the debugger +- resourceType: deployment + resourceName: browsertrix-cloud-backend + namespace: default + port: 5679 + localPort: 5679 deploy: helm: releases: @@ -39,6 +52,9 @@ deploy: # See https://skaffold.dev/docs/deployers/helm/ # must do this to make skaffold use local images with helm setValues: + # we hardcoded this earlier so make sure it has same value + # across the helm chart + opPort: 8756 # hot reloading doesn't work with default gunicorn command # so need to override to use uvicorn # plus need to start the process with debugpy to debug @@ -51,3 +67,12 @@ deploy: python -m debugpy --listen 0.0.0.0:5678 -m uvicorn btrixcloud.main:app_root --reload --host 0.0.0.0 --port 8000 + backend_op_command_override: + - sh + - -c + - > + pip install --no-input debugpy + && + python -m debugpy --listen 0.0.0.0:5679 + -m uvicorn btrixcloud.main_op:app_root + --reload --host 0.0.0.0 --port 8756 \ No newline at end of file From 01b8f509fc6f77cde1f340ff93b09c96fcb5d035 Mon Sep 17 00:00:00 2001 From: Alexander Darby <63904626+osintalex@users.noreply.github.com> Date: Sat, 13 Jul 2024 13:58:52 +0100 Subject: [PATCH 6/7] chore: add trailing newline --- skaffold.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skaffold.yaml b/skaffold.yaml index a156fd7544..8bdc7b8e3d 100644 --- a/skaffold.yaml +++ b/skaffold.yaml @@ -75,4 +75,4 @@ deploy: && python -m debugpy --listen 0.0.0.0:5679 -m uvicorn btrixcloud.main_op:app_root - --reload --host 0.0.0.0 --port 8756 \ No newline at end of file + --reload --host 0.0.0.0 --port 8756 From 01a0303976669ad7c43b0689b75c80f35cee0269 Mon Sep 17 00:00:00 2001 From: Alexander Darby <63904626+osintalex@users.noreply.github.com> Date: Sun, 4 Aug 2024 23:14:29 +0100 Subject: [PATCH 7/7] refactor: remove probes for easier local dev --- chart/templates/backend.yaml | 9 ++++++--- skaffold.yaml | 6 ++++-- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/chart/templates/backend.yaml b/chart/templates/backend.yaml index e61252965f..3468796b8f 100644 --- a/chart/templates/backend.yaml +++ b/chart/templates/backend.yaml @@ -55,7 +55,7 @@ spec: - name: api image: {{ .Values.backend_image }} imagePullPolicy: {{ .Values.backend_pull_policy }} - {{- if .Values.backend_api_command_override }} + {{- if .Values.skaffold_dev }} command: {{- range .Values.backend_api_command_override }} - {{ . | quote }} @@ -147,7 +147,7 @@ spec: - name: op image: {{ .Values.backend_image }} imagePullPolicy: {{ .Values.backend_pull_policy }} - {{- if .Values.backend_op_command_override }} + {{- if .Values.skaffold_dev }} command: {{- range .Values.backend_op_command_override }} - {{ . | quote }} @@ -198,6 +198,7 @@ spec: cpu: {{ .Values.backend_cpu }} memory: {{ .Values.backend_memory }} + {{- if not (.Values.skaffold_dev) }} startupProbe: httpGet: path: /healthz @@ -206,6 +207,7 @@ spec: periodSeconds: 5 failureThreshold: 5 successThreshold: 1 + {{- end }} readinessProbe: httpGet: @@ -216,6 +218,7 @@ spec: failureThreshold: 5 successThreshold: 1 + {{- if not (.Values.skaffold_dev) }} livenessProbe: httpGet: path: /healthz @@ -224,7 +227,7 @@ spec: periodSeconds: 30 failureThreshold: 15 successThreshold: 1 - + {{- end }} --- diff --git a/skaffold.yaml b/skaffold.yaml index 8bdc7b8e3d..6fe2058c39 100644 --- a/skaffold.yaml +++ b/skaffold.yaml @@ -55,6 +55,8 @@ deploy: # we hardcoded this earlier so make sure it has same value # across the helm chart opPort: 8756 + # we need to override some settings for skaffold dev + skaffold_dev: true # hot reloading doesn't work with default gunicorn command # so need to override to use uvicorn # plus need to start the process with debugpy to debug @@ -64,7 +66,7 @@ deploy: - > pip install --no-input debugpy && - python -m debugpy --listen 0.0.0.0:5678 + python -Xfrozen_modules=off -m debugpy --listen 0.0.0.0:5678 -m uvicorn btrixcloud.main:app_root --reload --host 0.0.0.0 --port 8000 backend_op_command_override: @@ -73,6 +75,6 @@ deploy: - > pip install --no-input debugpy && - python -m debugpy --listen 0.0.0.0:5679 + python -Xfrozen_modules=off -m debugpy --listen 0.0.0.0:5679 -m uvicorn btrixcloud.main_op:app_root --reload --host 0.0.0.0 --port 8756