Merge branch 'main' into fix-and-improve-local-juju-setup

.github/workflows/automatic-doc-checks.yml

@@ -0,0 +1,21 @@
+name: Automatic doc checks
+
+on:
+  push:
+    branches-ignore:
+      - 'main'
+    paths:
+      - 'docs/**'
+      - '.github/workflows/automatic-doc-checks.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  documentation-checks:
+    uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
+    with:
+      working-directory: "docs"
+      fetch-depth: 0

.github/workflows/markdown-style-checks.yml

@@ -0,0 +1,22 @@
+name: Markdown style checks
+
+on:
+  push:
+    branches-ignore:
+      - 'main'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  markdown-lint:
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - uses: DavidAnson/markdownlint-cli2-action@v16
+      with:
+        config: "docs/.sphinx/.markdownlint.json"

.github/workflows/sphinx-python-dependency-build-checks.yml

@@ -0,0 +1,52 @@
+# The purpose of this workflow file is to confirm that the Sphinx
+# virtual environment can be built from source, consequently documenting
+# the packages required in the build environment to do that.
+#
+# This is needed because some projects embeds the documentation into built
+# artifacts which involves rendering the documentation on the target
+# architecture.
+#
+# Depending on the architecture, pip may or may not have already built wheels
+# available, and as such we need to make sure building wheels from source can
+# succeed.
+name: Sphinx python dependency build checks
+on:
+  push:
+    branches-ignore:
+      - 'main'
+    paths:
+      - 'docs/**'
+      - '.github/workflows/sphinx-python-dependency-build-checks.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Install dependencies
+      run: |
+        set -ex
+        sudo apt -y install \
+          cargo \
+          libpython3-dev \
+          libxml2-dev \
+          libxslt1-dev \
+          make \
+          python3-venv \
+          rustc \
+          libtiff5-dev libjpeg8-dev libopenjp2-7-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk libharfbuzz-dev libfribidi-dev libxcb1-dev
+    - name: Build Sphinx venv
+      working-directory: "docs"
+      run: |
+        set -ex
+        make install \
+          PIPOPTS="--no-binary :all:" \
+          || ( cat .sphinx/venv/pip_install.log && exit 1 )

.gitignore

@@ -1,4 +1,5 @@
 # Visual Studio Code configurations
 .vscode
 
-.idea
+.idea
+build

.readthedocs.yaml

@@ -0,0 +1,40 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  jobs:
+    pre_install:
+    - git fetch --unshallow || true
+    post_checkout:
+    # Cancel building pull requests when there aren't changed in the docs directory.
+    # If there are no changes (git diff exits with 0) we force the command to return with 183.
+    # This is a special exit code on Read the Docs that will cancel the build immediately.
+    # https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition
+    - |
+      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/;
+      then
+        exit 183;
+      fi
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  builder: dirhtml
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+formats:
+- pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+  - requirements: docs/.sphinx/requirements.txt

.wokeignore

@@ -0,0 +1,4 @@
+# the cheat sheets contain a link to a repository with a block word which we
+# cannot avoid for now, ie
+# https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+doc-cheat-sheet*

README.md

@@ -1,167 +1,11 @@
-# Juju deployment
+# Test Observer
 
-Local Juju and charm deployment via microk8s and terraform.
+Test Observer (TO) is a dashboard for viewing the results of tests run on different environments for a particular artefact. A user interested in testing an artefact (a deb, snap, charm or image) under different environments (particular machines or cloud setups) can use TO as means for storing, viewing and comparing results with previous runs or versions of an artefact. The last use case is particularly useful for catching regressions. Additionally, TO provides a mechanism to assign reviewers that can look at results and mark artefacts as approved or failed to gate updates. It is important to note that TO does not run the tests itself, but provides an API with which users can report the results to.
 
-## Setup
+Certification currently deploys an instance of TO that they used for reviewing Stable Release Updates (SRUs). Other teams also use this instance for their tests. You can visit the [frontend](https://test-observer.canonical.com/) and view the [API docs](https://test-observer-api.canonical.com/docs), although this currently requires Canonical VPN access. There's also a staging deployment of [frontend](https://test-observer-staging.canonical.com/) and [API](https://test-observer-api-staging.canonical.com/docs) that teams can use to test their integration.
 
-It is recommended to install the pre-requisites on a VM rather than your host machine. To do so, first install multipass:
+## Run Locally
 
-```bash
-sudo snap install multipass
-```
+For development look at the [backend](/backend/README.md) and [frontend](/frontend/README.md).
 
-Then launch the "charm-dev" VM blueprint that comes pre-setup with required tools (this will take a while):
-
-```bash
-multipass launch --mount $HOME charm-dev
-```
-
-Note the home mount to access the project files in the VM.
-
-Once the VM initialization has been completed, you will need to enable microk8s ingress there:
-
-```bash
-multipass exec charm-dev -- sudo microk8s enable ingress
-```
-
-Then install terraform:
-
-```bash
-multipass exec charm-dev -- sudo snap install terraform --classic
-```
-
-And initialize it:
-
-```bash
-multipass exec charm-dev -- terraform init
-```
-
-## Deploy
-
-You can deploy everything using terraform by running:
-
-```bash
-multipass exec charm-dev -- TF_VAR_environment=development TF_VAR_external_ingress_hostname=local terraform apply -auto-approve
-```
-
-Then wait for the deployment to settle and all the statuses to become active. You can watch the statuses via:
-
-```bash
-multipass exec charm-dev -- JUJU_MODEL=test-observer-development juju status --storage --relations --watch 5s
-```
-
-Look at the IPv4 addresses of your charm-dev vm through:
-
-```bash
-multipass info charm-dev
-```
-
-One of these connect to the ingress enabled inside the VM. To figure out which one try the following command on each IP address until you get response:
-
-```bash
-curl --connect-to ::<ip-address> http://test-observer-api.local
-```
-
-Once you find the IP address add the following entry to your host machine's `/etc/hosts` file:
-
-```bash
-<ip-address>   test-observer.local test-observer-api.local
-```
-
-After that you should be able to get to TO frontend on your host machine's browser through the url test-observer.local. You should also be able to access the API through test-observer-api.local.
-
-## Teardown
-
-To take everything down you can start with terraform:
-
-```bash
-multipass exec charm-dev -- TF_VAR_environment=development TF_VAR_external_ingress_hostname=local terraform destroy --auto-approve
-```
-
-The above step can take a while and may even get stuck with some applications in error state. You can watch it through:
-
-```bash
-multipass exec charm-dev -- JUJU_MODEL=test-observer-development juju status --storage --relations --watch 5s
-```
-
-To forcefully remove applications stuck in error state:
-
-```bash
-multipass exec charm-dev -- JUJU_MODEL=test-observer-development juju remove-application <application-name> --destroy-storage --force
-```
-
-Once everything is down and the juju model has been deleted you can stop the multipass VM:
-
-```bash
-multipass stop charm-dev
-```
-
-## Developing the charm
-
-To develop and test updates to the backend and frontend charms, you would typically want to first complete the above steps to deploy a working system. Once you have done that, proceed with the following steps.
-
-### Build and refresh the backend charm
-
-You can make edits to the backend charm and refresh it in the running system on the fly with:
-
-```bash
-cd backend/charm
-charmcraft pack
-juju refresh api --path ./test-observer-api_ubuntu-22.04-amd64.charm
-
-# to update the OCI image that runs the backend
-juju attach-resource api api-image=ghcr.io/canonical/test_observer/backend:[tag or sha]
-```
-
-### Build and refresh the frontend charm
-
-Same thing with the frontend:
-
-```bash
-cd frontend/charm
-charmcraft pack
-
-juju refresh frontend ./test-observer-frontend_ubuntu-22.04-amd64.charm
-
-# to update the OCI image that runs the backend
-juju attach-resource frontend frontend-image=ghcr.io/canonical/test_observer/frontend:[tag or sha]
-```
-
-Note that the frontend app is made aware of the backend URL to connect to using the global `window.testObserverAPIBaseURI`, which is set at runtime with some nginx config level trickery based on...
-
-- the `test-observer-api` charm's `hostname` config value.
-- the frontend charm's `test-observer-api-scheme` config value.
-
-These in turn can be set using the terraform plan (`terraform/test-observer.tf` and associated variables).
-
-## Running tests
-
-To run the unit and integration tests for the frontend charms, do the following:
-
-```bash
-cd frontend/charm
-tox -e unit
-tox -e integration
-```
-
-## Releasing the charms
-
-Charms are released through GitHub actions on push to main. If however you need to release charms on your branch before merging with main you could always just add your branch as a trigger to those same GitHub actions.
-
-## VS Code & charm libraries
-
-VS Code fails to find (for autocompletions and code navigation purposes) the charm libraries under `lib` in each of `backend/charm` and `frontend/charm`. There is a .vscode-settings-default.json found under each of these directories which you can copy to the `.gitignore`d path `.vscode/settings.json` to make them fly. Taking the backend charm as an example:
-
-```bash
-mkdir -p backend/charm/.vscode
-cp backend/charm/.vscode-settings-default.json backend/charm/.vscode/settings.json
-
-mkdir -p frontend/charm/.vscode
-cp frontend/charm/.vscode-settings-default.json frontend/charm/.vscode/settings.json
-```
-
-Now if you use as your project the directory `backend/charm` and `frontend/charm` respectively (which you'll want to do also for them to keep their own virtual environments), VS Code should be happy.
-
-## Handy documentation pointers about charming
-
-- [Integrations (how to provide and require relations)](https://juju.is/docs/sdk/integration)
+To run via Terraform, juju and charms simulating production and staging environments, look at [terraform](README.md)