sr2/docs.sr2.uk
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: first pass at oper guide requirements

Browse source
This commit is contained in:
Iain Learmonth 2025-11-09 12:07:04 +00:00
parent efd0e7cf53
commit 8f7d0d372e
27 changed files with 1615 additions and 611 deletions
Download patch file Download diff file Expand all files Collapse all files

44
docs/intro.md
View file

@ -1,47 +1,7 @@
---
sidebar_position: 1
sidebar_label: Overview
---
# Tutorial Intro
# Documentation Overview
Let's discover **Docusaurus in less than 5 minutes**.
## Getting Started
Get started by **creating a new site**.
Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
### What you'll need
- [Node.js](https://nodejs.org/en/download/) version 20.0 or above:
- When installing Node.js, you are recommended to check all checkboxes related to dependencies.
## Generate a new site
Generate a new Docusaurus site using the **classic template**.
The classic template will automatically be added to your project after you run the command:
```bash
npm init docusaurus@latest my-website classic
```
You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
The command also installs all necessary dependencies you need to run Docusaurus.
## Start your site
Run the development server:
```bash
cd my-website
npm run start
```
The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.

4
docs/operator/_category_.yml Normal file
View file

@ -0,0 +1,4 @@
---
label: Operator Guide
link:
type: "generated-index"

80
docs/operator/architecture.md Normal file
View file

@ -0,0 +1,80 @@
---
sidebar_position: 10
---
# Architecture
We begin the guide with a high-level overview of the architecture of the CDR Link deployment framework.
## Introduction
We deploy each CDR Link instance on a single
[Red Had Enterprise Linux](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux)
9 (or compatible) host using
[rootless Podman](https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md).
Each component of Link is a container instance with the containers managed via systemd using
[Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html).
Components communicate via isolated networks that are also configured via Quadlet, and make use of the
[slirp4netns](https://github.com/rootless-containers/slirp4netns) user-mode networking for unprivileged
network namespaces.
Both
[discretionary access controls](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/configuring_basic_system_settings/managing-file-system-permissions_configuring-basic-system-settings)
and SELinux are used to prevent lateral movement between containers should a container be compromised, with particular
attention given to the messaging channels WhatsApp and Signal.
No container runs its application as the inside "root" user, which is an unprivileged user on the host.
The `/home` mount point on the host is encrypted using
[LUKS](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/managing_storage_devices/encrypting-block-devices-using-luks_managing-storage-devices)
with a per instance key to protect all user data at rest.
Further, we use separate partitions for critical audit logging to ensure that a resource exhaustion attack cannot
prevent later investigation, and automatically shut down instances where there is no space available for audit logging.
## Components
The following diagram shows the dependency relationships between the components of CDR Link.
If you use our [Ansible role](./deploy) for deployment then these will be automatically configured.
The Link stack containers are
[OCI](https://opencontainers.org/) compliant containers and you can run these with alternatives
such as [Docker Compose](https://docs.docker.com/compose/) however we would not be able to provide support for this
setup.
Our former Docker Compose deployment framework has been deprecated and we intend to migrate all partners to our new
rootless Podman setup for the improved reliability, performance, and security.
:::info
While the following diagram refers to `.service` units, these are the units generated by Podman Quadlet.
The service definitions are in `.container` units within the Quadlet directory at `$HOME/.config/containers/systemd`.
:::
```mermaid
flowchart TD
bridge-worker.service --> bridge-postgresql.service
bridge-worker.service --> bridge-whatsapp.service
bridge-worker.service --> signal-cli-rest-api.service
link.service --> bridge-postgresql.service
link.service --> bridge-worker.service
opensearch-dashboards.service --> zammad-opensearch.service
zammad-nginx.service --> zammad-railsserver.service
zammad-nginx.service --> link.service
zammad-storage.target{zammad-storage.target}
zammad-storage.target --> zammad-postgresql.service
zammad-storage.target --> zammad-redis.service
zammad-storage.target --> zammad-memcached.service
zammad-storage.target --> zammad-opensearch.service
zammad-railsserver.service -.-> zammad-init.service
zammad-init.service --> zammad-storage.target
zammad-railsserver.service --> zammad-storage.target
zammad-scheduler.service --> zammad-storage.target
zammad-websocket.service --> zammad-storage.target
link.target{link.target}
link.target --> opensearch-dashboards.service
link.target --> zammad-nginx.service
link.target --> zammad-scheduler.service
link.target --> zammad-websocket.service
```

105
docs/operator/requirements.md Normal file
View file

@ -0,0 +1,105 @@
---
sidebar_position: 20
---
# Requirements
If you are looking to self-host CDR Link, this page details what is required to run a secure and reliable instance.
The following requirements assume that your deployment framework will be the same as ours.
You may need to adjust the requirements if your framework differs materially, and while we can offer limited support for
this we would not be able to assist with in-depth troubleshooting.
## Deployment Host
:::danger
A compromise of this host effectively compromises the entire stack.
:::
* Appropriately hardened and vendor supported Linux operating system with the latest security updates applied
* SSH key backed by hardware security module and requiring unlock (e.g. [YubiKey](https://www.yubico.com/)) to be used
for login to the instance host
* Python 3.11+ (the `venv` module is included in Python since v3.3 so this is not a separate requirement)
* Git
* Ansible-compatible secrets management (e.g.
[sops](https://getsops.io/) or
[Bitwarden Secrets Manager](https://bitwarden.com/products/secrets-manager/))
## CDR Link Instance Host
It is **strongly recommended** that this host is dedicated to running the CDR Link software only.
* A [Red Hat Enterprise Linux](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux)
9 (or compatible) host with the latest security updates and appropriate hardening applied
* At least 4 (v)CPUs, 15GB RAM, and 75GB disk space
* Separate partitions for `/var`, `/var/log`, `/var/log/audit`, and `/home`
* `/home` must use the
[XFS](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/managing_file_systems/getting-started-with-xfs_managing-file-systems)
file system (to apply quotas)
* A global scope IP address assigned to one of the network interfaces
* FirewallD is installed and enabled with only the `ssh` service enabled
* Our deployment script will add the `http` and `https` services
* An unprivileged user created with 65536
[subuids and subgids](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/building_running_and_managing_containers/assembly_starting-with-containers_building-running-and-managing-containers#proc_setting-up-rootless-containers_assembly_starting-with-containers)
assigned that will be used to run the Link stack
* An unprivileged user with sudo permission, and the SSH public key from the deployment host installed as an authorised
key
In our deployments, we would perform the hardening configuration using our
[baseline Ansible role](https://guardianproject.dev/sr2/ansible-collection-core/src/branch/main/roles/baseline),
however this role is not intended for general use and so may not fit your requirements.
We manage our users, groups, and subordinate IDs using
[Identity Management](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/installing_identity_management/index)
but a locally created user can also be used.
:::warning
Depending on your configuration it is also possible to use an LDAP user with locally defined subuids and subgids however
be aware that this may lead to conflicts between hosts, and complications if file system snapshots or backups are
available across hosts.
:::
## CDR Link Handset (Optional)
The handset is only required if you wish to use the Signal or WhatsApp channels with CDR Link.
It is **strongly recommended** that this handset is dedicated to running the CDR Link related apps only and is stored in
a secure facility.
Consider that the device will require to have its cellular connection available and so it would not be advised to store
the handset, for example, in a metallic container.
:::tip
Many of the handset related support requests we receive are due to partners using the handset directly rather than
allowing CDR Link to manage the channels leading to the system losing synchronisation and then failing to recover.
:::
The handset has the ability to send and receive messages via the helpdesk channels and so should not be frequently moved
between locations to reduce the risk of theft or other loss.
Cheaper handsets often do not receive security updates for Android promptly after their release as there are multiple
steps in the supply chain before an update can be distributed. Ensure that you purchase your handset from a reputable
manufacturer that provides a guaranteed period of security updates and has a track record of timely distribution of
those updates.
* At least Android 14, preferably at least 15 for new deployments, with latest system updates installed
* Google Play Services are required for Signal and WhatsApp
* Cellular plan that can receive SMS and with enough data to allow for system updates
* SMS required to allow activation of the WhatsApp and Signal accounts
* We have seen lower rates of accounts being blocked (automatically flagged as spam or fraud) when using cellular data
plans as opposed to WiFi
* At least 3GB RAM and 16GB storage
* [Mobile Device Management](https://www.android.com/intl/en_uk/enterprise/management/) for configuration, automatic
updates and remote wipe capability
* Appropriate hardening, for example:
* Ensure that a complex screen lock is used
* Ensure that device encryption is enabled
* Ensure that developer options are disabled
* Ensure screen timeout is set
* Ensure lock screen does not show notifications
* Disable Bluetooth and WiFi
* 7-day timer to manage charging to avoid failure of the internal battery
:::danger
If you leave the phone permanently connected to the charger, the internal battery of the handset will fail and may pose
a fire hazard.
You should consider any charging of lithium-ion batteries in your local site risk assessments.
:::

8
docs/tutorial-basics/_category_.json
View file

@ -1,8 +0,0 @@
{
"label": "Tutorial - Basics",
"position": 2,
"link": {
"type": "generated-index",
"description": "5 minutes to learn the most important Docusaurus concepts."
}
}

23
docs/tutorial-basics/congratulations.md
View file

@ -1,23 +0,0 @@
---
sidebar_position: 6
---
# Congratulations!
You have just learned the **basics of Docusaurus** and made some changes to the **initial template**.
Docusaurus has **much more to offer**!
Have **5 more minutes**? Take a look at **[versioning](../tutorial-extras/manage-docs-versions.md)** and **[i18n](../tutorial-extras/translate-your-site.md)**.
Anything **unclear** or **buggy** in this tutorial? [Please report it!](https://github.com/facebook/docusaurus/discussions/4610)
## What's next?
- Read the [official documentation](https://docusaurus.io/)
- Modify your site configuration with [`docusaurus.config.js`](https://docusaurus.io/docs/api/docusaurus-config)
- Add navbar and footer items with [`themeConfig`](https://docusaurus.io/docs/api/themes/configuration)
- Add a custom [Design and Layout](https://docusaurus.io/docs/styling-layout)
- Add a [search bar](https://docusaurus.io/docs/search)
- Find inspirations in the [Docusaurus showcase](https://docusaurus.io/showcase)
- Get involved in the [Docusaurus Community](https://docusaurus.io/community/support)

34
docs/tutorial-basics/create-a-blog-post.md
View file

@ -1,34 +0,0 @@
---
sidebar_position: 3
---
# Create a Blog Post
Docusaurus creates a **page for each blog post**, but also a **blog index page**, a **tag system**, an **RSS** feed...
## Create your first Post
Create a file at `blog/2021-02-28-greetings.md`:
```md title="blog/2021-02-28-greetings.md"
---
slug: greetings
title: Greetings!
authors:
- name: Joel Marcey
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
- name: Sébastien Lorber
title: Docusaurus maintainer
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
tags: [greetings]
---
Congratulations, you have made your first post!
Feel free to play around and edit this post as much as you like.
```
A new blog post is now available at [http://localhost:3000/blog/greetings](http://localhost:3000/blog/greetings).

57
docs/tutorial-basics/create-a-document.md
View file

@ -1,57 +0,0 @@
---
sidebar_position: 2
---
# Create a Document
Documents are **groups of pages** connected through:
- a **sidebar**
- **previous/next navigation**
- **versioning**
## Create your first Doc
Create a Markdown file at `docs/hello.md`:
```md title="docs/hello.md"
# Hello
This is my **first Docusaurus document**!
```
A new document is now available at [http://localhost:3000/docs/hello](http://localhost:3000/docs/hello).
## Configure the Sidebar
Docusaurus automatically **creates a sidebar** from the `docs` folder.
Add metadata to customize the sidebar label and position:
```md title="docs/hello.md" {1-4}
---
sidebar_label: 'Hi!'
sidebar_position: 3
---
# Hello
This is my **first Docusaurus document**!
```
It is also possible to create your sidebar explicitly in `sidebars.js`:
```js title="sidebars.js"
export default {
tutorialSidebar: [
'intro',
// highlight-next-line
'hello',
{
type: 'category',
label: 'Tutorial',
items: ['tutorial-basics/create-a-document'],
},
],
};
```

43
docs/tutorial-basics/create-a-page.md
View file

@ -1,43 +0,0 @@
---
sidebar_position: 1
---
# Create a Page
Add **Markdown or React** files to `src/pages` to create a **standalone page**:
- `src/pages/index.js` → `localhost:3000/`
- `src/pages/foo.md` → `localhost:3000/foo`
- `src/pages/foo/bar.js` → `localhost:3000/foo/bar`
## Create your first React Page
Create a file at `src/pages/my-react-page.js`:
```jsx title="src/pages/my-react-page.js"
import React from 'react';
import Layout from '@theme/Layout';
export default function MyReactPage() {
return (
<Layout>
<h1>My React page</h1>
<p>This is a React page</p>
</Layout>
);
}
```
A new page is now available at [http://localhost:3000/my-react-page](http://localhost:3000/my-react-page).
## Create your first Markdown Page
Create a file at `src/pages/my-markdown-page.md`:
```mdx title="src/pages/my-markdown-page.md"
# My Markdown page
This is a Markdown page
```
A new page is now available at [http://localhost:3000/my-markdown-page](http://localhost:3000/my-markdown-page).

31
docs/tutorial-basics/deploy-your-site.md
View file

@ -1,31 +0,0 @@
---
sidebar_position: 5
---
# Deploy your site
Docusaurus is a **static-site-generator** (also called **[Jamstack](https://jamstack.org/)**).
It builds your site as simple **static HTML, JavaScript and CSS files**.
## Build your site
Build your site **for production**:
```bash
npm run build
```
The static files are generated in the `build` folder.
## Deploy your site
Test your production build locally:
```bash
npm run serve
```
The `build` folder is now served at [http://localhost:3000/](http://localhost:3000/).
You can now deploy the `build` folder **almost anywhere** easily, **for free** or very small cost (read the **[Deployment Guide](https://docusaurus.io/docs/deployment)**).

152
docs/tutorial-basics/markdown-features.mdx
View file

@ -1,152 +0,0 @@
---
sidebar_position: 4
---
# Markdown Features
Docusaurus supports **[Markdown](https://daringfireball.net/projects/markdown/syntax)** and a few **additional features**.
## Front Matter
Markdown documents have metadata at the top called [Front Matter](https://jekyllrb.com/docs/front-matter/):
```text title="my-doc.md"
// highlight-start
---
id: my-doc-id
title: My document title
description: My document description
slug: /my-custom-url
---
// highlight-end
## Markdown heading
Markdown text with [links](./hello.md)
```
## Links
Regular Markdown links are supported, using url paths or relative file paths.
```md
Let's see how to [Create a page](/create-a-page).
```
```md
Let's see how to [Create a page](./create-a-page.md).
```
**Result:** Let's see how to [Create a page](./create-a-page.md).
## Images
Regular Markdown images are supported.
You can use absolute paths to reference images in the static directory (`static/img/docusaurus.png`):
```md
![Docusaurus logo](/img/docusaurus.png)
```
![Docusaurus logo](/img/docusaurus.png)
You can reference images relative to the current file as well. This is particularly useful to colocate images close to the Markdown files using them:
```md
![Docusaurus logo](./img/docusaurus.png)
```
## Code Blocks
Markdown code blocks are supported with Syntax highlighting.
````md
```jsx title="src/components/HelloDocusaurus.js"
function HelloDocusaurus() {
return <h1>Hello, Docusaurus!</h1>;
}
```
````
```jsx title="src/components/HelloDocusaurus.js"
function HelloDocusaurus() {
return <h1>Hello, Docusaurus!</h1>;
}
```
## Admonitions
Docusaurus has a special syntax to create admonitions and callouts:
```md
:::tip My tip
Use this awesome feature option
:::
:::danger Take care
This action is dangerous
:::
```
:::tip My tip
Use this awesome feature option
:::
:::danger Take care
This action is dangerous
:::
## MDX and React Components
[MDX](https://mdxjs.com/) can make your documentation more **interactive** and allows using any **React components inside Markdown**:
```jsx
export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '20px',
color: '#fff',
padding: '10px',
cursor: 'pointer',
}}
onClick={() => {
alert(`You clicked the color ${color} with label ${children}`)
}}>
{children}
</span>
);
This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !
This is <Highlight color="#1877F2">Facebook blue</Highlight> !
```
export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '20px',
color: '#fff',
padding: '10px',
cursor: 'pointer',
}}
onClick={() => {
alert(`You clicked the color ${color} with label ${children}`);
}}>
{children}
</span>
);
This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !
This is <Highlight color="#1877F2">Facebook blue</Highlight> !

7
docs/tutorial-extras/_category_.json
View file

@ -1,7 +0,0 @@
{
"label": "Tutorial - Extras",
"position": 3,
"link": {
"type": "generated-index"
}
}

BIN
docs/tutorial-extras/img/docsVersionDropdown.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 25 KiB

BIN
docs/tutorial-extras/img/localeDropdown.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 27 KiB

55
docs/tutorial-extras/manage-docs-versions.md
View file

@ -1,55 +0,0 @@
---
sidebar_position: 1
---
# Manage Docs Versions
Docusaurus can manage multiple versions of your docs.
## Create a docs version
Release a version 1.0 of your project:
```bash
npm run docusaurus docs:version 1.0
```
The `docs` folder is copied into `versioned_docs/version-1.0` and `versions.json` is created.
Your docs now have 2 versions:
- `1.0` at `http://localhost:3000/docs/` for the version 1.0 docs
- `current` at `http://localhost:3000/docs/next/` for the **upcoming, unreleased docs**
## Add a Version Dropdown
To navigate seamlessly across versions, add a version dropdown.
Modify the `docusaurus.config.js` file:
```js title="docusaurus.config.js"
export default {
themeConfig: {
navbar: {
items: [
// highlight-start
{
type: 'docsVersionDropdown',
},
// highlight-end
],
},
},
};
```
The docs version dropdown appears in your navbar:
![Docs Version Dropdown](./img/docsVersionDropdown.png)
## Update an existing version
It is possible to edit versioned docs in their respective folder:
- `versioned_docs/version-1.0/hello.md` updates `http://localhost:3000/docs/hello`
- `docs/hello.md` updates `http://localhost:3000/docs/next/hello`

88
docs/tutorial-extras/translate-your-site.md
View file

@ -1,88 +0,0 @@
---
sidebar_position: 2
---
# Translate your site
Let's translate `docs/intro.md` to French.
## Configure i18n
Modify `docusaurus.config.js` to add support for the `fr` locale:
```js title="docusaurus.config.js"
export default {
i18n: {
defaultLocale: 'en',
locales: ['en', 'fr'],
},
};
```
## Translate a doc
Copy the `docs/intro.md` file to the `i18n/fr` folder:
```bash
mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/
cp docs/intro.md i18n/fr/docusaurus-plugin-content-docs/current/intro.md
```
Translate `i18n/fr/docusaurus-plugin-content-docs/current/intro.md` in French.
## Start your localized site
Start your site on the French locale:
```bash
npm run start -- --locale fr
```
Your localized site is accessible at [http://localhost:3000/fr/](http://localhost:3000/fr/) and the `Getting Started` page is translated.
:::caution
In development, you can only use one locale at a time.
:::
## Add a Locale Dropdown
To navigate seamlessly across languages, add a locale dropdown.
Modify the `docusaurus.config.js` file:
```js title="docusaurus.config.js"
export default {
themeConfig: {
navbar: {
items: [
// highlight-start
{
type: 'localeDropdown',
},
// highlight-end
],
},
},
};
```
The locale dropdown now appears in your navbar:
![Locale Dropdown](./img/localeDropdown.png)
## Build your localized site
Build your site for a specific locale:
```bash
npm run build -- --locale fr
```
Or build your site to include all the locales at once:
```bash
npm run build
```