Documentation

.github/workflows/ci.yaml

@@ -73,3 +73,53 @@ jobs:
         with:
           image: ${{ github.repository }}
           github_token: ${{ secrets.GITHUB_TOKEN }}
+
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Print GitHub event name
+        run: echo "${{ github.event_name }}"
+
+      - name: Filter paths
+        uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            docs:
+              - "docs/**"
+              - "src/mobu/**"
+            docsSpecific:
+              - "docs/**"
+
+      - name: Install graphviz
+        if: steps.filter.outputs.docs == 'true' || github.event_name == 'workflow_dispatch'
+        run: sudo apt-get install graphviz
+
+      - name: Build docs
+        if: steps.filter.outputs.docs == 'true' || github.event_name == 'workflow_dispatch'
+        uses: lsst-sqre/run-tox@v1
+        with:
+          python-version: "3.12"
+          tox-envs: docs
+          tox-plugins: tox-uv
+          cache-key-prefix: docs
+
+      # Upload docs:
+      # - on pushes to main if *any* documentation content might have changed
+      # - on workflow dispatches if any documentation content might have changed
+      # - on pushes to tickets/ branches if docs/ directory content changed
+      - name: Upload to LSST the Docs
+        uses: lsst-sqre/ltd-upload@v1
+        with:
+          project: "mobu"
+          dir: "docs/_build/html"
+          username: ${{ secrets.LTD_USERNAME }}
+          password: ${{ secrets.LTD_PASSWORD }}
+        if: >-
+          (github.event_name == 'push' && github.ref_name == 'main' && steps.filter.outputs.docs == 'true')
+          || (github.event_name == 'workflow_dispatch')
+          || (github.event_name == 'pull_request' && startsWith(github.head_ref, 'tickets/') && steps.filter.outputs.docsSpecific == 'true')

.gitignore

@@ -69,6 +69,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
+docs/_static
 docs/_build/
 
 # PyBuilder

README.md

@@ -5,3 +5,7 @@ It attempts to simulate user interactions with Science Platform services continu
 It can be used for both monitoring and synthetic load testing.
 
 mobu is developed with the [Safir](https://safir.lsst.io/) framework.
+
+See [mobu.lsst.io](https://mobu.lsst.io) for full documentation.
+
+

changelog.d/20240626_113149_danfuchs_mobu_in_ci.md

@@ -0,0 +1,13 @@
+<!-- Delete the sections that don't apply -->
+
+### Backwards-incompatible changes
+
+- The existing refresh functionality is now a GitHub app integration (from a simple webhook integration). This requires new Phalanx secrets to be sync'd, and a new GitHub app to be added to repos that want the functionality. Special care has been taken to not leave these checks in a forever-in-progress state, even in the case of (graceful) mobu shutdown/restart
+
+### New features
+
+- A GitHub app integration to generate GitHub actions checks for commits pushed to notebook repo branches that are part of active PRs. These checks trigger and report on a solitary Mobu run of the changed notebooks in the commit.
+
+### Other changes
+
+- Python 3.12.3 -> 3.12.4

docs/api.rst

@@ -0,0 +1,5 @@
+########
+REST API
+########
+
+This is a stub page for the API.

docs/conf.py

@@ -0,0 +1 @@
+from documenteer.conf.guide import *

docs/development/github.rst

@@ -0,0 +1,58 @@
+###########################
+Testing GitHub integrations
+###########################
+
+The GitHub integrations can be tested locally by pointing your local mobu at the ``idfdev`` env, and using a services like https://smee.io to proxy GitHub webhooks to your local mobu.
+
+Test repo
+=========
+`This repo <https://github.com/lsst-sqre/dfuchs-test-mobu>`__ has a bunch of different notebooks in a bunch of different directories, some of which intentionally throw exceptions.
+It contains `a script <https://github.com/lsst-sqre/dfuchs-test-mobu/blob/main/update.sh>`__ to update certain notebooks, conditionally updating the poison ones.
+The `data-dev Mobu CI app <https://github.com/apps/mobu-ci-data-dev-lsst-cloud>`__ in the `lsst-sqre GitHub org <https://github.com/organizations/lsst-sqre/settings/installations/51531298>`__, is currently installed and configured to work with this repo.
+
+smee.io
+=======
+You can use https://smee.io to proxy GitHub webhook requests from the data-dev Mobu CI GitHub app to your local mobu.
+
+#. Install the tool from [smee.io](https://smee.io/).
+#. Start it up and point it at your one of local mobu's GitHub webhook endpoints (the CI endpoint in this example):
+
+   .. code-block::
+
+      ❯ smee -p 8000 -P /mobu/github/ci/webhook
+      Forwarding https://smee.io/kTysHB50d4pgUmRN to http://127.0.0.1:8000/mobu/github/ci/webhook
+
+#. Configure the [data-dev GitHub Mobu CI app](https://github.com/organizations/lsst-sqre/settings/apps/mobu-ci-data-dev-lsst-cloud) to send webooks to the smee URL.
+#. Run your local mobu against the ``idfdev`` env, as described :doc:`here <idfdev>`.
+#. Point your local mobu at a local `Safir <https://github.com/lsst-sqre/safir>`__ .
+
+   .. code-block:: diff
+
+      index ce732db..ce2d693 100644
+      --- a/requirements/main.in
+      +++ b/requirements/main.in
+      @@ -22,6 +22,6 @@ pydantic-settings
+       pyvo
+       pyyaml
+      -safir>=5.0.0
+      +# safir>=5.0.0
+      +-e /home/danfuchs/src/safir
+       shortuuid
+       structlog
+
+#. Patch your local Safir to handle the malformed requests that smee.io sends.
+   The requests sent by the smee proxy have ``:port`` suffixes in the ``X-Forwarded-For`` values.
+   Safir doesn't handle this (and I don't think it's Safir's fault; I _think_ the port should be in ``X-Forwarded-Port``), so you have to change Safir:
+
+   .. code-block:: diff
+
+      index 2a3f40c..7211241 100644
+      --- a/src/safir/middleware/x_forwarded.py
+      +++ b/src/safir/middleware/x_forwarded.py
+      @@ -116,5 +116,5 @@ class XForwardedMiddleware:
+               return [
+                   ip_address(addr)
+      -            for addr in (a.strip() for a in forwarded_for_str[0].split(","))
+      +            for addr, _ in (a.strip().split(':') for a in forwarded_for_str[0].split(","))
+                   if addr
+               ]

docs/development/idfdev.rst

@@ -0,0 +1,72 @@
+##########################
+Testing against ``idfdev``
+##########################
+
+You can run mobu locally while having all of the actual business run against services in ``idefdev`` (or any other environment).
+
+
+#. Install the `1Password CLI <https://developer.1password.com/docs/cli/>`__.
+#. Generate a personal `idfdev gafaelfawr token <https://data-dev.lsst.cloud/auth/tokens/>`__ generated with an ``admin:token`` scope.
+#. Put this token in a ``data-dev.lsst.cloud personal token`` entry in your personal 1Password vault.
+#. Run mobu locally with something like this shell script:
+
+   .. code-block:: shell
+
+      #!/usr/bin/env bash
+
+      set -euo pipefail
+
+      config_dir="/tmp/mobu_test"
+      ci_config_file="github.yaml"
+      ci_config_path="$config_dir/$ci_config_file"
+      autostart_config_file="autostart.yaml"
+      autostart_config_path="$config_dir/$autostart_config_file"
+
+      mkdir -p "$config_dir"
+
+      # Note: This whitespace must be actual <tab> chars!
+      cat <<- 'END' > "$ci_config_path"
+              users:
+              - username: bot-mobu-ci-local-1
+              - username: bot-mobu-ci-local-2
+              accepted_github_orgs:
+              - lsst-sqre
+      END
+
+      # Note: This whitespace must be actual <tab> chars!
+      cat <<- 'END' > "$autostart_config_path"
+              - name: "my-test"
+                count: 1
+                users:
+                  - username: "bot-mobu-my-test-local"
+                scopes:
+                  - "exec:notebook"
+                business:
+                  type: "NotebookRunner"
+                  options:
+                    repo_url: "https://github.com/lsst-sqre/dfuchs-test-mobu.git"
+                    repo_ref: "main"
+                    max_executions: 10
+                  restart: true
+      END
+
+      export MOBU_ENVIRONMENT_URL=https://data-dev.lsst.cloud
+      export MOBU_GAFAELFAWR_TOKEN=$(op read "op://Employee/data-dev.lsst.cloud personal token/credential")
+      export MOBU_AUTOSTART_PATH="$autostart_config_path"
+      export MOBU_LOG_LEVEL=debug
+
+      # Don't set the MOBU_GITHUB_REFRESH* vars if you don't need that integration
+      export MOBU_GITHUB_REFRESH_ENABLED=true
+      export MOBU_GITHUB_REFRESH_APP_WEBHOOK_SECRET=$(op read "op://RSP data-dev.lsst.cloud/mobu/github-refresh-app-webhook-secret")
+
+      # Don't set the MOBU_GITHUB_REFRESH* vars if you don't need that integration
+      export MOBU_GITHUB_CI_APP_ENABLED=true
+      export MOBU_GITHUB_CI_APP_WEBHOOK_SECRET=$(op read "op://RSP data-dev.lsst.cloud/mobu/github-ci-app-webhook-secret")
+      export MOBU_GITHUB_CI_APP_ID=$(op read "op://RSP data-dev.lsst.cloud/mobu/github-ci-app-id")
+      export MOBU_GITHUB_CI_APP_PRIVATE_KEY=$(op read "op://RSP data-dev.lsst.cloud/mobu/github-ci-app-private-key" | base64 -d)
+
+      # Don't set MOBU_GITHUB_CONFIG_PATH if you don't need any of the GitHub integrations.
+      export MOBU_GITHUB_CONFIG_PATH="$ci_config_path"
+
+      uvicorn mobu.main:app 2>&1
+

docs/development/index.rst

@@ -0,0 +1,10 @@
+###########
+Development
+###########
+
+Here are some guides on developing and testing mobu.
+
+.. toctree::
+
+   idfdev
+   github

docs/documenteer.toml

@@ -0,0 +1,12 @@
+[project]
+title = "Mobu"
+copyright = "2015-2024 Association of Universities for Research in Astronomy, Inc. (AURA)"
+
+[project.python]
+package = "mobu"
+
+[project.openapi]
+openapi_path = "_static/openapi.json"
+
+[project.openapi.generator]
+function = "mobu.main:create_openapi"

docs/index.rst

@@ -0,0 +1,40 @@
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   user_guide/index
+   operations/index
+   development/index
+   api
+
+####
+Mobu
+####
+
+mobu (short for "monkey business") is a continous integration testing framework for the `Rubin Science Platform <https://phalanx.lsst.io/>`__ .
+It attempts to simulate user interactions with Science Platform services continuously, recording successes and failures and optionally reporting failures to a Slack channel via a Slack incoming webhook.
+It runs some number of "monkeys" that simulate a random user of the Science Platform.
+Those monkeys are organized into "flocks" that share a single configuration across all of the monkeys.
+It can be used for both monitoring and synthetic load testing.
+
+mobu is on github at https://github.com/lsst-sqre/mobu.
+
+.. grid:: 3
+
+   .. grid-item-card:: User Guide
+      :link: user_guide/index
+      :link-type: doc
+
+      Learn how to configure mobu to run your run and test your code.
+
+   .. grid-item-card:: Operations
+      :link: operations/index
+      :link-type: doc
+
+      Learn how to add mobu to new environments and add new integrations to mobu.
+
+   .. grid-item-card:: Development
+      :link: operations/index
+      :link-type: doc
+
+      Learn how to add contribute to the mobu codebase.