To try out the latest release of Browsertrix Cloud on your local machine, you'll first need to have a working Kubernetes cluster.
Before running Browsertrix Cloud, you'll need to set up a running Kubernetes cluster.
Today, there are numerous ways to deploy Kubernetes fairly easily, and we recommend trying one of the single-node options, which include Docker Desktop, microk8s, minikube and k3s.
The instructions below assume you have the local package managers for your platform (eg.
brew for macOS,
choco for Windows, etc...) already installed.
Cloning the repository at https://github.com/webrecorder/browsertrix-cloud is only needed to access additional configuration files.
Here are some environment specific instructions for setting up a local cluster from different Kubernetes vendors:
Docker Desktop (recommended for macOS and Windows)
For macOS and Windows, we recommend testing out Browsertrix Cloud using Kubernetes support in Docker Desktop as that will be one of the simplest options.
Install Docker Desktop if not already installed.
From the Dashboard app, ensure
Enable Kubernetesis checked from the Preferences screen.
Restart Docker Desktop if asked, and wait for it to fully restart.
MicroK8S (recommended for Ubuntu)
For Ubuntu and other linux distros, we recommend using MicroK8S for both local deployment and production.
Install the following addons
microk8s enable dns hostpath-storage registry helm3. (For production, also add
ingress cert-managerto the list of addons)
Wait for add-ons to finish installing with
microk8s status --wait-ready
Note: microk8s comes with its own version helm, so you don't need to install it separately. Replace
microk8s helm3 in the subsequent instructions below.
Minikube (Windows, macOS, or Linux)
Install Minikube following installation instructions, eg.
brew install minikube. Note that Minikube also requires Docker or another container management system to be installed as well.
K3S (recommended for non-Ubuntu Linux)
Install K3s as per the instructions
KUBECONFIGto point to the config for K3S:
export KUBECONFIG=/etc/rancher/k3s/k3s.yamlto ensure Helm will use the correct version.
Launching Browsertrix Cloud with Helm¶
Once you have a running Kubernetes cluster with one of the options above, and Helm 3 installed, you can install the latest release of Browsertrix Cloud directly from the latest GitHub release.
If using microk8s, the command will be:
Subsequent commands will also use
microk8s helm3 instead of
The default setup includes the full Browsertrix Cloud system, with frontend, backend api, db (via MongoDB) and storage (via Minio)
An admin user with name
email@example.com and password
PASSW0RD! will be automatically created.
With Helm, additional YAML files can be added to further override previous settings.
Some possible settings can be changed are found in chart/examples/local-config.yaml.
For example, to change the default superadmin, uncomment the
superadmin block in
local-config.yaml, and then change the username (
firstname.lastname@example.org) and password (
PASSW0RD!) to different values. (The admin username and password will be updated with each deployment).
To change the local port, change
You can then redeploy with these additional settings by running:
The above examples assumes running from a cloned Browsertrix Cloud repo, however the config file can be saved anywhere and specified with
Waiting for Cluster to Start¶
After running the helm command, you should see something like:
After that, especially on first run, it may take a few minutes for the Browsertrix Cloud cluster to start, as all images need to be downloaded locally.
You can try running the command:
kubectl wait --for=condition=ready pod --all --timeout=300s to wait for all pods to be initialized.
The command will exit when all pods have been loaded, or if there is an error and it times out.
If the command succeeds, you should be able to access Browsertrix Cloud by loading: http://localhost:30870/ in your browser.
Minikube (on macOS)
When using Minikube on a macOS, the port will not be 30870. Instead, Minikube opens a tunnel to a random port,
obtained by running
minikube service browsertrix-cloud-frontend --url in a separate terminal.
Use the provided URL (in the format
Debugging Pod Issues¶
If this command fails, you can also run
kubectl get pods to see the status of each of the pods.
There should be 4 pods listed: backend, frontend, minio and mongodb. If any one is not ready for a while, something may be wrong.
To get more details about why a pod has not started, you can run
kubectl describe <podname> and see the latest status at the bottom.
Often, the error may be obvious, such as failed to pull an image.
If the pod is running, or previously ran, you can also get the logs from the container by running
kubectl logs <podname>
The outputs of these commands will be helpful if you'd like to report an issue on GitHub
Updating the Cluster¶
To update the cluster, for example to update to new version
NEWVERSION, re-run the same command again, which will pull the latest images. In this way, you can upgrade to the latest release of Browsertrix Cloud. The upgrade will preserve the database and current archives.
To uninstall, run
helm uninstall btrix.
By default, the database + storage volumes are not automatically deleted, so you can run
helm upgrade ... again to restart the cluster in its current state.
If you are upgrading from a previous version, and run into issues with
helm upgrade ..., we recommend uninstalling and then re-running upgrade.
Deleting all Data¶
To fully delete all persistent data (db + archives) created in the cluster, also run
kubectl delete pvc --all after uninstalling.
Deploying for Local Development¶
These instructions are intended for deploying the cluster from the latest releases published on GitHub. See setting up cluster for local development for additional customizations related to developing Browsertrix Cloud and deploying from local images.