05c5e09d25
Closes #1434 ### Changes #### Developer - Adds the K3S playbook guide to the navigation - Adds note about restarting MKDocs when adding new icons - Adds note about concise language to the styleguide ([see previous discussion](https://github.com/webrecorder/browsertrix-cloud/pull/1394#discussion_r1402666872)) - Adds a note about noun usage to the styleguide #### User guide - Adds tables for archived item and workflow statuses - Adds custom styles for displaying statuses with their icons like we do in the app - Fixes capitalization issues --------- Co-authored-by: Tessa Walsh <tessa@bitarchivist.net> Co-authored-by: sua yoo <sua@webrecorder.org>
136 lines
5.3 KiB
Markdown
136 lines
5.3 KiB
Markdown
# Setup for Local Development
|
|
|
|
## Installation
|
|
|
|
First, see our [Local Deployment guide](../deploy/local.md#installing-kubernetes) for instructions on how to install the latest release with [Kubernetes](https://kubernetes.io/) with [Helm 3](https://v3.helm.sh/).
|
|
|
|
## Local Dev Configuration
|
|
|
|
The local deployment guide explains how to deploy Browsertrix Cloud with latest published images.
|
|
|
|
However, if you are developing locally, you will need to use your local images instead.
|
|
|
|
We recommend the following setup:
|
|
|
|
1. Copy the provided `./chart/examples/local-config.yaml` Helm configuration file to a separate file `local.yaml`, so that local changes to it will not be accidentally committed to git.
|
|
|
|
From the root directory:
|
|
|
|
```sh
|
|
cp ./chart/examples/local-config.yaml ./chart/local.yaml
|
|
```
|
|
|
|
2. Uncomment `backend_image`, `frontend_image`, and pull policies in `./chart/local.yaml`, which will ensure the local images are used:
|
|
```yaml
|
|
backend_image: docker.io/webrecorder/browsertrix-backend:latest
|
|
frontend_image: docker.io/webrecorder/browsertrix-frontend:latest
|
|
backend_pull_policy: 'Never'
|
|
frontend_pull_policy: 'Never'
|
|
```
|
|
|
|
??? info "MicroK8S"
|
|
|
|
For microk8s, the pull policies actually need to be set to `IfNotPresent` instead of `Never`:
|
|
|
|
```yaml
|
|
backend_pull_policy: 'IfNotPresent'
|
|
frontend_pull_policy: 'IfNotPresent'
|
|
```
|
|
|
|
This will ensure images are pulled from the MicroK8S registry (configured in next section).
|
|
|
|
|
|
|
|
3. Build the local backend and frontend images. The exact process depends on the Kubernetes environment you've selected in your initial deployment. Environment specific build instructions are as follows:
|
|
|
|
??? info "Docker Desktop"
|
|
|
|
Rebuild the local images by running `#!shell ./scripts/build-backend.sh` and/or `#!shell ./scripts/build-frontend.sh` scripts to build the images in the local Docker.
|
|
|
|
??? info "MicroK8S"
|
|
|
|
MicroK8s uses its own container registry, running on port 32000.
|
|
|
|
1. Ensure the registry add-on is enabled by running `microk8s enable registry`
|
|
|
|
2. Set `export REGISTRY=localhost:32000/` and then run `#!shell ./scripts/build-backend.sh` and/or `#!shell ./scripts/build-frontend.sh` to rebuild the images into the MicroK8S registry.
|
|
|
|
3. In `./chart/local.yaml`, also uncomment the following lines to use the local images:
|
|
```yaml
|
|
backend_image: "localhost:32000/webrecorder/browsertrix-backend:latest"
|
|
frontend_image: "localhost:32000/webrecorder/browsertrix-frontend:latest"
|
|
```
|
|
|
|
??? info "Minikube"
|
|
|
|
Minikube comes with its own image builder to update the images used in Minikube.
|
|
|
|
To build the backend image, run:
|
|
|
|
```shell
|
|
minikube image build -t webrecorder/browsertrix-backend:latest ./backend
|
|
```
|
|
|
|
To build a local frontend image, run:
|
|
|
|
```shell
|
|
minikube image build -t webrecorder/browsertrix-frontend:latest ./frontend
|
|
```
|
|
|
|
??? info "K3S"
|
|
|
|
K3S uses `containerd` by default. To use local images, they need to be imported after rebuilding.
|
|
|
|
1. Rebuild the images with Docker by running by running `./scripts/build-backend.sh` and/or `./scripts/build-frontend.sh` scripts. (Requires Docker to be installed as well).
|
|
|
|
2. Serializer the images to .tar:
|
|
```shell
|
|
docker save webrecorder/browsertrix-backend:latest > ./backend.tar
|
|
docker save webrecorder/browsertrix-frontend:latest > ./frontend.tar
|
|
```
|
|
|
|
3. Import images into k3s containerd:
|
|
```shell
|
|
k3s ctr images import --base-name webrecorder/browsertrix-backend:latest ./backend.tar
|
|
k3s ctr images import --base-name webrecorder/browsertrix-frontend:latest ./frontend.tar
|
|
```
|
|
|
|
4. To change other options, uncomment them as needed in `./chart/local.yaml` or add additional overrides from `./chart/values.yaml`.
|
|
|
|
For example, to set a superuser email to `my_super_user_email@example.com` and password to `MySecretPassword!`, uncomment that block and set:
|
|
```yaml
|
|
superuser:
|
|
# set this to enable a superuser admin
|
|
email: my_super_user_email@example.com
|
|
|
|
# optional: if not set, automatically generated
|
|
# change or remove this
|
|
password: MySecretPassword!
|
|
```
|
|
|
|
5. Once the images have been built and config changes made in `./chart/local.yaml`, the cluster can be re-deployed by running:
|
|
```sh
|
|
helm upgrade --install -f ./chart/values.yaml \
|
|
-f ./chart/local.yaml btrix ./chart/
|
|
```
|
|
|
|
??? info "MicroK8S"
|
|
|
|
If using microk8s, the commend will be:
|
|
|
|
```sh
|
|
microk8s helm3 upgrade --install -f ./chart/values.yaml -f ./chart/local.yaml btrix ./chart/
|
|
```
|
|
|
|
Refer back to the [Local Development guide](../deploy/local.md#waiting-for-cluster-to-start) for additional information on running and debugging your local cluster.
|
|
|
|
## Update the Images
|
|
|
|
After making any changes to backend code (in `./backend`) or frontend code (in `./frontend`), you'll need to rebuild the images as specified above, before running `helm upgrade ...` to re-deploy.
|
|
|
|
Changes to settings in `./chart/local.yaml` can be deployed with `helm upgrade ...` directly.
|
|
|
|
## 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.
|