Reorganize content

- Renames "Dev" to "Develop" for improved navigation labels
- Deployment docs are now located under a larger "Development" section (fewer nav bar choices & realistically I think anyone who wants to do one is going to be referring to the other)
- Adds links to tools the first time they're mentioned
- Rewords part of the homepage
- Hides section navigation on the homepage (now we don't have a blank section nav bar!
- Adds some syntax highlighting
- Removes some manual word wrapping — this was done very rarely / inconsistently
This commit is contained in:
Henry Wilkinson 2023-03-27 02:11:41 -04:00
parent 7576ac8423
commit f6bab4f26c
9 changed files with 31 additions and 28 deletions

View File

@ -1,4 +1,4 @@
# Introduction
# Introduction to Deployment
Browsertrix Cloud is designed to be a cloud-native application running in Kubernetes.
@ -7,7 +7,7 @@ However, despite the name, it is perfectly reasonable (and easy!) to deploy Brow
The main requirements for Browsertrix Cloud are:
- A Kubernetes Cluster
- Helm 3 (package manager for Kubernetes)
- [Helm 3](https://helm.sh/) (package manager for Kubernetes)
We have prepared a [Local Deployment](./local) and [Production (Self-Hosted and Cloud) Deployment](./production) guides to help with
setting up Browsertrix Cloud for different scenarios.

View File

@ -4,13 +4,11 @@ To just test out Browsertrix Cloud on your local machine, you'll first need to h
## Installing Kubernetes
Before running Browsertrix Cloud, you'll need to set up a running Kubernetes cluster.
Before running Browsertrix Cloud, you'll need to set up a running [Kubernetes](https://kubernetes.io/) 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 cloned
the [https://github.com/webrecorder/browsertrix-cloud](https://github.com/webrecorder/browsertrix-cloud) repository locally,
and have local package managers for your platform (eg. `brew` for Mac, `choco` for Windows, etc...) already installed.
The instructions below assume you have cloned the [https://github.com/webrecorder/browsertrix-cloud](https://github.com/webrecorder/browsertrix-cloud) repository locally, and have local package managers for your platform (eg. `brew` for Mac, `choco` for Windows, etc...) already installed.
Here are some environment specific instructions for setting up a local cluster from different Kubernetes vendors:
@ -62,7 +60,7 @@ Here are some environment specific instructions for setting up a local cluster f
Once you have a running Kubernetes cluster with one of the options above, and Helm 3 installed, you can then run from the Browsertrix Cloud repo directory:
```
```shell
helm upgrade --install -f ./chart/values.yaml -f ./chart/examples/local-config.yaml btrix ./chart/
```
@ -81,7 +79,7 @@ Note that the admin user and password will not be reset after creation.
After running the helm command, you should see something like:
```
```shell
Release "btrix" does not exist. Installing it now.
NAME: btrix
LAST DEPLOYED: <time>
@ -117,7 +115,7 @@ The outputs of these commands will be helpful if you'd like to report an issue [
To update the cluster, 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.
```
```shell
helm upgrade --install -f ./chart/values.yaml -f ./chart/examples/local-config.yaml btrix ./chart/
```
@ -136,7 +134,7 @@ By default, this setup will pull the latest release of Browsertrix Cloud. Howeve
First, open `./chart/examples/local-config.yaml` and add the following, which will ensure only local images are used:
```
```yaml
backend_pull_policy: "Never"
frontend_pull_policy: "Never"
```
@ -157,7 +155,7 @@ Now, rebuild either the backend and/or frontend images locally. The exact proces
2. In `./chart/examples/local-config.yaml`, uncomment out one or both of 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"
```
@ -168,12 +166,13 @@ Now, rebuild either the backend and/or frontend images locally. The exact proces
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
```
@ -185,14 +184,14 @@ Now, rebuild either the backend and/or frontend images locally. The exact proces
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
```

View File

@ -10,7 +10,7 @@ The production deployments also allow using an external mongodb server, and/or e
## Single Machine Deployment with MicroK8S
For a single-machine production deployment, we recommend using microk8s.
For a single-machine production deployment, we recommend using [MicroK8s](https://microk8s.io/).
1. Install MicroK8S, as suggested in [the local deployment guide](../deploy/local.md) and ensure the `ingress` and `cert-manager` addons are also enabled.
@ -22,7 +22,7 @@ For a single-machine production deployment, we recommend using microk8s.
4. Run with:
```
```shell
helm upgrade --install -f ./chart/values.yaml -f ./chart/my-config.yaml btrix ./chart/
```
@ -31,7 +31,7 @@ For a single-machine production deployment, we recommend using microk8s.
If you would like to use existing external storage, such an existing S3-compatible storage, also set the default storage, for example:
```
```yaml
minio_local: false
storages:
@ -49,11 +49,10 @@ Note that this setup is not limited to Amazon S3, but should work with any S3-co
If you would like to use an externally hosted MongoDB, you can add the following config to point to a custom MongoDB instance.
The `db_url` should follow the [MongoDB Connection String Format](https://www.mongodb.com/docs/manual/reference/connection-string/)
which should include the username and password of the remote instance.
The `db_url` should follow the [MongoDB Connection String Format](https://www.mongodb.com/docs/manual/reference/connection-string/) which should include the username and password of the remote instance.
```
```yaml
mongo_local: false
mongo_auth:

View File

@ -12,5 +12,4 @@ pip install mkdocs-material
In the project root directory run `mkdocs serve` to run a local version of the documentation site.
The docs hosted on [docs.browsertrix.cloud](https://docs.browsertrix.cloud) are created from
the main branch of [https://github.com/webrecorder/browsertrix-cloud](https://github.com/webrecorder/browsertrix-cloud)
The docs hosted on [docs.browsertrix.cloud](https://docs.browsertrix.cloud) are created from the main branch of [https://github.com/webrecorder/browsertrix-cloud](https://github.com/webrecorder/browsertrix-cloud)

View File

@ -1,12 +1,18 @@
# Welcome
---
hide:
- navigation
- toc
---
# Home
Welcome to the Browsertrix Cloud official user guide and developer docs. These docs will contain the following sections.
- [Deployment Guide](./deploy) - Info on how to install and deploy Browsertrix Cloud locally or in the cloud.
- [Developer Docs](./dev) - for info on how to developing Browsertrix Cloud itself.
- [User Guide](./user-guide) - for info on how to use Browsertrix Cloud system.
- [Developer Docs](./develop) - Information on developing Browsertrix Cloud itself.
- [Deployment Guide](./develop/deploy) - How to install and deploy Browsertrix Cloud on your local machine, or in the cloud.
- [User Guide](./user-guide) - Instructions and reference for using Browsertrix Cloud.
If you are unfamiliar with Browsertrix Cloud, please check out [our website](https://browsertrix.cloud) or the main repository at [https://github.com/webrecorder/browsertrix-cloud](https://github.com/webrecorder/browsertrix-cloud)
If you are unfamiliar with Browsertrix Cloud, please check out [our website](https://browsertrix.cloud), or the main repository at [https://github.com/webrecorder/browsertrix-cloud](https://github.com/webrecorder/browsertrix-cloud)
Our docs are still under construction. If you find something missing, chances are we haven't gotten around to writing that part yet. If you find typos or something isn't clear or seems incorrect, please open an [issue](https://github.com/webrecorder/browsertrix-cloud/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) and we'll try to make sure that your questions get answered here in the future!