Outline docs for devops

.github/workflows/build_docs.yml

@@ -0,0 +1,46 @@
+name: build docs
+on: push
+
+jobs:
+  build_docs:
+    runs-on: "ubuntu-20.04"
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v3
+
+      - name: Build docs
+        run: make docs
+
+      - name: Get current git ref
+        id: rev_parse
+        run: echo "COMMIT_HASH=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
+
+      - name: Checkout ooni/docs
+        uses: actions/checkout@v2
+        with:
+          repository: "ooni/docs"
+          ssh-key: ${{ secrets.OONI_DOCS_DEPLOYKEY }}
+          path: "ooni-docs"
+
+      - name: Update docs
+        run: cp -R dist/docs/* ooni-docs/src/content/docs/devops/
+
+      - name: Check for conflicting slugs
+        run: |
+          cat ooni-docs/src/content/docs/devops/*.md \
+            | grep "^slug:" | awk -F':' '{gsub(/^ +/, "", $2); print $2}' | sort | uniq -c \
+            | awk '{if ($1 > 1) { print "duplicate slug for: " $2; exit 1}}'
+
+      - name: Print the lines of the generated docs
+        run: wc -l ooni-docs/src/content/docs/mydocs/*
+
+      - name: Commit changes
+        # Only push the docs update when we are in main
+        # if: github.ref == 'refs/heads/main'
+        run: |
+          cd ooni-docs
+          git config --global user.email "[email protected]"
+          git config --global user.name "OONI Github Actions Bot"
+          git add .
+          git commit -m "auto: update backend docs to ${{ steps.rev_parse.outputs.COMMIT_HASH }}" || echo "No changes to commit"
+          git push origin

.gitignore

@@ -14,3 +14,6 @@ override.tf
 override.tf.json
 *_override.tf
 *_override.tf.json
+
+# Ignore generated docs
+/dist

Makefile

@@ -1,25 +1,7 @@
-#!/bin/bash
-DOCS_ROOT=dist/docs/
-REPO_NAME="ooni/backend"
-COMMIT_HASH=$(git rev-parse --short HEAD)
+docs:
+	./scripts/build-docs.sh
 
-mkdir -p $DOCS_ROOT
+clean:
+	rm -rf dist/
 
-strip_title() {
-    # Since the title is already present in the frontmatter, we need to remove
-    # it to avoid duplicate titles
-    local infile="$1"
-    cat $infile | awk 'BEGIN{p=1} /^#/{if(p){p=0; next}} {print}'
-}
-
-cat <<EOF>$DOCS_ROOT/00-index.md
----
-# Do not edit! This file is automatically generated
-# to edit go to: https://github.com/$REPO_NAME/edit/master/README.md
-# version: $REPO_NAME:$COMMIT_HASH
-title: My Documentation Title
-description: My Documentation Description
-slug: mydocs
----
-EOF
-strip_title README.md >> $DOCS_ROOT/00-index.md
+.PHONY: docs clean

README.md

@@ -0,0 +1,37 @@
+# OONI Devops
+
+## Infrastructure Tiers
+
+We divide our infrastructure components into 3 tiers:
+
+- **Tier 0: Critical**: These are mission critical infrastructure components. If these become unavailable or have significant disruption, it will have a major impact.
+
+- **Tier 1: Essential**: These components are important, but not as critical as
+  tier 0. They are part of our core operations, but if they become unavailable
+  the impact is important, but not major.
+
+- **Tier 2: Non-Essential**: These are auxiliary components. Their
+  unavailability does not have a major impact.
+
+### Tier 0 (Critical) components
+
+- Probe Services (collector specifically)
+- Fastpath (part responsible for storing post-cans)
+- DNS configuration
+- Monitoring
+- OONI bridges
+- OONI.org website
+
+### Tier 1 (Essential) components
+
+- OONI API measurement listing
+- OONI Explorer
+- OONI Run
+- OONI Data analysis pipeline
+- Website analytics
+
+### Tier 2 (Non-Essential) components
+
+- Test list editor
+- Jupyter notebooks
+- Countly

scripts/build-docs.sh

@@ -15,11 +15,35 @@ strip_title() {
 cat <<EOF>$DOCS_ROOT/00-index.md
 ---
 # Do not edit! This file is automatically generated
-# to edit go to: https://github.com/$REPO_NAME/edit/master/README.md
+# to edit go to: https://github.com/$REPO_NAME/edit/main/README.md
 # version: $REPO_NAME:$COMMIT_HASH
 title: OONI Devops
 description: OONI Devops
 slug: devops
 ---
 EOF
-strip_title README.md >> $DOCS_ROOT/00-index.md
+strip_title README.md >> $DOCS_ROOT/00-index.md
+
+cat <<EOF>$DOCS_ROOT/01-iac.md
+---
+# Do not edit! This file is automatically generated
+# to edit go to: https://github.com/$REPO_NAME/edit/main/tf/README.md
+# version: $REPO_NAME:$COMMIT_HASH
+title: OONI Devops IaC
+description: OONI Devops IaC Documentation
+slug: devops/iac
+---
+EOF
+strip_title tf/README.md >> $DOCS_ROOT/01-iac.md
+
+cat <<EOF>$DOCS_ROOT/02-configuration-management.md
+---
+# Do not edit! This file is automatically generated
+# to edit go to: https://github.com/$REPO_NAME/edit/main/ansible/README.md
+# version: $REPO_NAME:$COMMIT_HASH
+title: OONI Devops Configuration Management
+description: OONI Devops Configuration Management Documentation
+slug: devops/configuration-management
+---
+EOF
+strip_title ansible/README.md >> $DOCS_ROOT/02-configuration-management.md