From a8f4f8cfc3791d3e01e166b94684bfa8529c7d23 Mon Sep 17 00:00:00 2001 From: sua yoo Date: Wed, 18 Sep 2024 13:43:09 -0700 Subject: [PATCH] docs: Clarify hosted vs. self-deployment requirements (#2082) Updates docs to clarify difference between self-hosting and hosted subscription. --------- Co-authored-by: Henry Wilkinson Co-authored-by: Tessa Walsh --- docs/deploy/index.md | 9 ++++++--- docs/develop/index.md | 24 +++++++++++++++++++----- docs/index.md | 26 +++++++++++++++++++------- docs/user-guide/index.md | 2 +- mkdocs.yml | 34 +++++++++++++++++----------------- 5 files changed, 62 insertions(+), 33 deletions(-) diff --git a/docs/deploy/index.md b/docs/deploy/index.md index 1f5ca42b..3ea0077a 100644 --- a/docs/deploy/index.md +++ b/docs/deploy/index.md @@ -1,15 +1,18 @@ -# Deploying Browsertrix +# Self-Hosting + +!!! info "Already signed up for Browsertrix?" + + This guide is for developers and users who are self-hosting Browsertrix. If you've registered through [browsertrix.com](https://browsertrix.com/), you may be looking for the [user guide](../user-guide/index.md). Browsertrix is designed to be a cloud-native application running in Kubernetes. -However, despite the name, it is perfectly reasonable (and easy!) to deploy Browsertrix locally using one of the many available local Kubernetes options. +However, it is perfectly reasonable to deploy Browsertrix locally using one of the many available local Kubernetes options. The main requirements for Browsertrix are: - A Kubernetes Cluster - [Helm 3](https://helm.sh/) (package manager for Kubernetes) - We have prepared a [Local Deployment Guide](local.md) which covers several options for testing Browsertrix locally on a single machine, as well as a [Production (Self-Hosted and Cloud) Deployment](remote.md) guide to help with setting up Browsertrix in different production scenarios. Information about configuring storage, crawler channels, and other details in local or production deployments is in the [Customizing Browsertrix Deployment Guide](customization.md). Details on managing org export and import for existing clusters can be found in the [Org Import & Export](admin/org-import-export.md) guide. diff --git a/docs/develop/index.md b/docs/develop/index.md index 5228f16a..c47fc768 100644 --- a/docs/develop/index.md +++ b/docs/develop/index.md @@ -5,12 +5,20 @@ hide: # Developing Browsertrix +## Local Development + +Get the latest Browsertrix source using git: + +```sh +git clone https://github.com/webrecorder/browsertrix.git +``` + +To develop Browsertrix, the system must [first be deployed locally](../deploy/local.md) in a Kubernetes cluster. The deployment can then be [further customized for local development](./local-dev-setup.md). + +## Source Code + Browsertrix consists of a Python-based backend and TypeScript-based frontend. -To develop Browsertrix, the system must [first be deployed locally](../deploy/local.md) in a Kubernetes cluster. - -The deployment can then be [further customized for local development](./local-dev-setup.md). - ### Backend The backend is an API-only system, using the FastAPI framework. Latest API docs can be viewed in the browser by adding `/api/redoc` to the URL of a running cluster (ex: `http://localhost:30870/api/redoc` when running locally on port `30870`.) @@ -21,10 +29,16 @@ At this time, the backend must be deployed in the Kubernetes cluster. ### Frontend -The frontend UI is implemented in TypeScript, using the Lit framework and Shoelace component library. +The frontend UI is implemented in TypeScript, using the [Lit](https://lit.dev/) framework and [Shoelace](https://shoelace.style/) component library. The static build of the frontend is bundled with nginx, but the frontend can be deployed locally in dev mode against an existing backend. See [Developing the Frontend UI](frontend-dev.md) for more details. + +## Contributing + +Browsertrix is planned and developed on GitHub: . We welcome pull requests that contribute towards [fixing bugs](https://github.com/webrecorder/browsertrix/issues?q=is%3Aopen+is%3Aissue+label%3Abug) and feature enhancements. + +Check out our [project board](https://github.com/orgs/webrecorder/projects/9/views/1) to see current and upcoming features that the Webrecorder team is working on. diff --git a/docs/index.md b/docs/index.md index 2df70aa0..518a6639 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,14 +4,26 @@ hide: - toc --- -# Home +# Browsertrix Docs -Welcome to the Browsertrix official user guide and developer docs. These docs will contain the following sections. +Browsertrix is an open source web archiving system created by [Webrecorder](https://webrecorder.net/). Sign up for Browsertrix on [browsertrix.com](https://browsertrix.com/) to start archiving with zero setup, or follow our self-hosting guide to deploy Browsertrix on your own infrastructure. -- [Deployment Guide](deploy/index.md) — How to install and deploy Browsertrix on your local machine, or in the cloud. -- [Developer Docs](develop/index.md) — Information on developing Browsertrix itself. -- [User Guide](user-guide/index.md) — Instructions and reference for using Browsertrix. +## Documentation -If you are unfamiliar with Browsertrix, please check out [our website](https://browsertrix.com), or the main repository at [https://github.com/webrecorder/browsertrix](https://github.com/webrecorder/browsertrix) +Docs are organized into the following sections: -If something is missing, unclear, or seems incorrect, please open an [issue](https://github.com/webrecorder/browsertrix/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! +- [User Guide](./user-guide/index.md) — Instructions on how to use Browsertrix to create and share web archives. +- [Self-Hosting](./deploy/index.md) — Instructions on how to install, set up, and deploy self-hosted Browsertrix. +- [Development](./develop/index.md) — Contribute to the open source development of Browsertrix software. + +If you have feedback on the docs, please feel free to [reach out to us](mailto:docs-feedback@webrecorder.net). + +## Support + +For help with a specific topic, try our [community help forum](https://forum.webrecorder.net/c/help/5). + +Dedicated professional support is available with a custom subscription or support contract. Check out [our plans](https://browsertrix.com/) for details. + +## Bugs + +For bug reports or feature requests, please open a [GitHub issue](https://github.com/webrecorder/browsertrix/issues/new/choose). \ No newline at end of file diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md index 5f8c0403..76346ca7 100644 --- a/docs/user-guide/index.md +++ b/docs/user-guide/index.md @@ -1,6 +1,6 @@ # Welcome -Browsertrix is an intuitive, open source, automated web archiving system. Archive, replay, and share websites exactly as they were at a certain point in time. +Browsertrix is an intuitive, automated web archiving system. Archive, replay, and share websites exactly as they were at a certain point in time. Browsertrix is built and hosted by [Webrecorder](https://webrecorder.net/), a leading expert in web archiving. Our goal is to make web archiving easier and more accessible to everyone through open source tools, easy-to-use interfaces, and community building. diff --git a/mkdocs.yml b/mkdocs.yml index bf7ff3e1..d5c2d309 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,23 +44,7 @@ theme: view: bootstrap/eye nav: - - index.md - - Deploy: - - deploy/index.md - - deploy/local.md - - deploy/remote.md - - deploy/customization.md - - Ansible: - - deploy/ansible/digitalocean.md - - deploy/ansible/microk8s.md - - deploy/ansible/k3s.md - - Administration: - - deploy/admin/org-import-export.md - - Develop: - - develop/index.md - - develop/local-dev-setup.md - - develop/frontend-dev.md - - develop/docs.md + - Overview: index.md - User Guide: - Getting Started: - user-guide/index.md @@ -88,6 +72,22 @@ nav: - Account Settings: - user-guide/user-settings.md - user-guide/contribute.md + - Self-Hosting: + - Overview: deploy/index.md + - deploy/local.md + - deploy/remote.md + - deploy/customization.md + - Ansible: + - deploy/ansible/digitalocean.md + - deploy/ansible/microk8s.md + - deploy/ansible/k3s.md + - Administration: + - deploy/admin/org-import-export.md + - Development: + - develop/index.md + - develop/local-dev-setup.md + - develop/frontend-dev.md + - develop/docs.md markdown_extensions: - toc: