diff --git a/ansible/README.md b/ansible/README.md index f1ca0a58..04dda448 100644 --- a/ansible/README.md +++ b/ansible/README.md @@ -1,3 +1,3 @@ ### Install -Most current instructions to install will always be [here](https://docs.browsertrix.cloud/deploy/production/) +Most current instructions to install will always be [here](https://docs.browsertrix.cloud/deploy/remote/) diff --git a/chart/examples/k3s-hosted.yaml b/chart/examples/k3s-hosted.yaml new file mode 100644 index 00000000..62b10e74 --- /dev/null +++ b/chart/examples/k3s-hosted.yaml @@ -0,0 +1,83 @@ +# Hosted Config (eg. for k3s) +# -------------------------------- +# +# This config can be used to run Browsertrix Cloud hosted on a remote server. +# This requires setting the hostname and signing hostname. +# +# +# The `ingress.host` and `ingress.cert_email` and optional `signer.host` must be set below. +# +# k3s +# --- +# +# One way to deploy this is with k3s, which will require the following changes: +# +# Make sure to disable traefik on your k3s cluster by adding `--no-deploy traefik` to the systemd unit that starts k3s _before_ starting your server. One way to check that traefik is not running your cluster is with `kubectl get deployments -n kube-system` and see if traefik shows up in the output +# +# Once traefik has been disabled, you must install `nginx-ingress` which can be installed by: +# helm upgrade --install nginx ingress-nginx/ingress-nginx -n ingress-nginx --create-namespace +# +# You'll also need to install cert-manager. Browsertrix cloud recommends installing cert-manager through jetpack with the following command: +# +# helm repo add jetstack https://charts.jetstack.io +# helm repo update +# +# helm repo update jetstack +# helm upgrade --install \ +# cert-manager jetstack/cert-manager \ +# --namespace cert-manager \ +# --create-namespace \ +# --version v1.12.0 \ +# --set installCRDs=true +# +# run with: +# +# helm3 upgrade --install -f ./chart/values.yaml -f ./chart/examples/microk8s-hosted.yaml btrix ./chart/ +# +# +# If developing locally, you must import your built containers with ctr +# +# `docker save webrecorder/browsertrix-backend:latest | k3s ctr images import --base-name webrecorder/browsertrix-backend:latest -` +# `docker save webrecorder/browsertrix-frontend:latest | k3s ctr images import --base-name webrecorder/browsertrix-frontend:latest -` + + +ingress: + # required: set host to use tls + # uncomment and replace example below with your registered domain + # host: "yourdomain.org" + + # required: set email to use tls + # uncomment and replace example below with your valid email address + #cert_email: "you@yourdomain.org" + + scheme: "https" + tls: true + +ingress_class: "nginx" + + +# optionally, set host below to enable WACZ signing +signer: + enabled: true + + # uncomment and replace example below with your registered domain + # host: "second.yourdomain.org" + + +# optionally, override default mongodb auth, used for all data storage: + +#mongo_auth: + # username: root + # password: PASSWORD! + + +# optionally, set these to custom values + +#superuser: + # set this to enable a superuser admim + # email: admin@example.com + + # optional: if not set, automatically generated + # change or remove this + # password: PASSWORD! + diff --git a/docs/deploy/production.md b/docs/deploy/remote.md similarity index 62% rename from docs/deploy/production.md rename to docs/deploy/remote.md index 2f0ec869..651072c2 100644 --- a/docs/deploy/production.md +++ b/docs/deploy/remote.md @@ -1,6 +1,6 @@ -# Production: Self-Hosted and Cloud +# Remote: Self-Hosted and Cloud -For production and hosted deployments (both on a single machine or in the cloud), the only requirement is to have a designed domain and (strongly recommended, but not required) second domain for signing web archives. +For remote and hosted deployments (both on a single machine or in the cloud), the only requirement is to have a designed domain and (strongly recommended, but not required) second domain for signing web archives. We are also experimenting with [Ansible playbooks](../deploy/ansible) for cloud deployment setups. @@ -9,7 +9,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](https://microk8s.io/). +For a single-machine remote 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. @@ -25,6 +25,39 @@ For a single-machine production deployment, we recommend using [MicroK8s](https: helm upgrade --install -f ./chart/values.yaml -f ./chart/my-config.yaml btrix ./chart/ ``` +## Single Machine Deployment with k3s + +Another option for a single-machine remote deployment is [k3s](https://k3s.io) + +1. Install K3s, as suggested in the [local deployment guide](../deploy/local.md). Make sure to **disable traefik** which can be done by adding `--no-deploy traefik` to the `systemd` unit when installing k3s + +2. Install `nginx-ingress` with: `helm upgrade --install nginx ingress-nginx/ingress-nginx -n ingress-nginx --create-namespace` +3. Install `cert-manager`. We recommend installing `cert-manager` through Jetpack, like so: + +```zsh +helm repo add jetstack https://charts.jetstack.io +helm repo update + +helm repo update jetstack +helm upgrade --install \ + cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --create-namespace \ + --version v1.12.0 \ + --set installCRDs=true +``` + +4. Copy `cp ./chart/examples/k3s-hosted.yaml ./chart/my-config.yaml` to make local changes. + +5. Set the `ingress.host`, `ingress.cert_email` and `signing.host` fields in `./chart/my-config.yaml` to your host and domain + +6. Set the super-admin username and password, and mongodb username and password in `./chart/my-config.yaml` + +7. Run with: + + ```shell + helm upgrade --install -f ./chart/values.yaml -f ./chart/my-config.yaml btrix ./chart/ + ``` ### Using Custom Storage diff --git a/mkdocs.yml b/mkdocs.yml index 378fa6e2..3ab32906 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -47,7 +47,7 @@ nav: - Deploy: - deploy/index.md - deploy/local.md - - deploy/production.md + - deploy/remote.md - Ansible: - deploy/ansible/digitalocean.md - deploy/ansible/microk8s.md