From 0a1f5eff8ef0ae5a4437ff5734a1cb8ac87822af Mon Sep 17 00:00:00 2001 From: Henry Wilkinson Date: Thu, 6 Apr 2023 05:44:19 -0400 Subject: [PATCH] Docs: adds mkdocs features, adds theming (#728) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add stylesheet & mkdocs features - Adds a custom stylesheet & brand colours - Adds Recursive as the code font - Adds repo info to the nav bar - Adds auto tracking ID links for deep linking to sections as users scroll the page - Index pages are now a part of their section as determined by their H1 - Removes mkdocs info from future footer * Reorganize content - Renames "Dev" to "Develop" for improved navigation labels - 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 * Rename "Developer Docs" index page - Better title for sidebar * Update docs.md - Adds links to tools - Adds future docs style guide section - Updates name and makes it an H1 - Replaces hyphens on the homepage with em dashes * deployment index page: changed title, removed non-k8s section, cleaned up intro * develop index page: changed title fixed typo on main page --------- Co-authored-by: Ilya Kreymer --- docs/deploy/index.md | 18 ++++++------------ docs/deploy/local.md | 25 ++++++++++++------------- docs/deploy/production.md | 11 +++++------ docs/dev/docs.md | 16 ---------------- docs/develop/docs.md | 19 +++++++++++++++++++ docs/{dev => develop}/frontend-dev.md | 0 docs/{dev => develop}/index.md | 2 +- docs/index.md | 16 +++++++++++----- docs/stylesheets/extra.css | 22 ++++++++++++++++++++++ mkdocs.yml | 12 ++++++++++-- 10 files changed, 86 insertions(+), 55 deletions(-) delete mode 100644 docs/dev/docs.md create mode 100644 docs/develop/docs.md rename docs/{dev => develop}/frontend-dev.md (100%) rename docs/{dev => develop}/index.md (95%) create mode 100644 docs/stylesheets/extra.css diff --git a/docs/deploy/index.md b/docs/deploy/index.md index ea41370d..cac28539 100644 --- a/docs/deploy/index.md +++ b/docs/deploy/index.md @@ -1,21 +1,15 @@ -# Introduction +# Deploying Browsertrix Cloud Browsertrix Cloud is designed to be a cloud-native application running in Kubernetes. -However, despite the name, it is perfectly reasonable (and easy!) to deploy Browsertrix Cloud locally using one of the many available local Kubernetes options. Here are a few recommendations for different scenarios. +However, despite the name, it is perfectly reasonable (and easy!) to deploy Browsertrix Cloud locally using one of the many available local Kubernetes options. 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. - -### Non Kubernetes Deployments - -Previously, Browsertrix Cloud also supported Docker Compose and podman-based deployment. This is now deprecated due to the complexity -of maintaining feature parity across different setups, and with various Kubernetes deployment options being available and easy to deploy, even on a single machine. - -Making deployment of Browsertrix Cloud as easy as possible remains a key goal, and we welcome suggestions for how we can further improve our Kubernetes deployment options. +We have prepared a [Local Deployment Guide](./local) which covers several options for testing Browsertrix Cloud locally on a single machine, +as well as a [Production (Self-Hosted and Cloud) Deployment](./production) guides to help with +setting up Browsertrix Cloud for different production scenarios. diff --git a/docs/deploy/local.md b/docs/deploy/local.md index 273cc913..78df912b 100644 --- a/docs/deploy/local.md +++ b/docs/deploy/local.md @@ -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: