docs: Setup diagram auto gen

.github/workflows/autoupdate-structurizr-diagrams.yml

@@ -0,0 +1,46 @@
+name: Auto update Structurizr Diagrams
+
+on:
+  pull_request:
+    paths:
+      - 'docs/workspace.dsl' # This setting will have the action trigger only if certain file changes. Set the location of your DSL.
+      - '.github/workflows/autoupdate-structurizr-diagrams.yml' # Useful for testing purposes
+
+jobs:
+  update-diagrams:
+    runs-on: ubuntu-latest
+    container: ghcr.io/sebastienfi/structurizr-cli-with-bonus:latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+      - name: Set up git
+        # This step needs to be done before checkout so that the checkout respects clrf
+        uses: canonical/ubuntu-pro-for-wsl/.github/actions/setup-git@main
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Generate Diagram Images
+        shell: bash
+        run: |
+          set -eu
+          echo "Actual folder is"
+          echo ${PWD}
+          /usr/local/structurizr-cli/structurizr.sh export -workspace 'docs/workspace.dsl' -format plantuml -output 'docs/diagrams'
+          cd 'docs/diagrams'
+          echo 'Generating PNGs...'
+          plantuml -tpng *.puml
+          rm *.puml
+      - name: Get output branch for branch name
+        id: get-branch-name
+        shell: bash
+        run: echo "branch=${GITHUB_REF#refs/heads/}" >> $GITHUB_OUTPUT
+      - name: Create Pull Request if there is a diff
+        uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: Auto update diagrams
+          title: 'docs: Auto update diagram files'
+          labels: docs, automated pr
+          body: "[Auto-generated pull request](https://github.com/canonical/ubuntu-pro-for-wsl/actions/workflows/autoupdate-structurizr-diagrams.yml) by GitHub Action"
+          branch: autoupdate-diagrams-${{ steps.get-branch-name.outputs.branch }}
+          base: ${{ github.head_ref }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+          delete-branch: true

docs/.custom_wordlist.txt

@@ -17,6 +17,8 @@ macOS
 MSIX
 powershell
 PowerShell
+structurizr
+Structurizr
 systemd
 ubuntu
 UbuntuProForWSL
@@ -48,6 +50,7 @@ HIPAA
 Hostagent
 LTS
 os
+repo
 SLA
 SRU
 tcp

docs/diagrams/readme.md

@@ -0,0 +1,18 @@
+Diagrams in this directory are auto-generated.
+Any PR that makes changes in the `docs/workspace.dsl` file in this repo will
+trigger a GitHub action that updates the diagrams.
+This will add a new commit to the PR.
+
+# Contributing
+
+If you want to edit the `workspace.dsl` and see your changes reflected during
+testing you have two options:
+
+1. The [online editor](https://structurizr.com/dsl) from Structurizr
+2. The [CLI](https://docs.structurizr.com/cli) from Structurizr
+
+The diagrams are built according to the [C4 model](https://c4model.com/).
+This allows architectural diagrams to be constructed at different levels of abstraction from a single `workspace.dsl`.
+
+If contributing to the diagrams you should be familiar with the C4 Model.
+Any change you make could potentially impact multiple diagrams.

docs/workspace.dsl

@@ -0,0 +1,189 @@
+workspace {
+
+    model {
+
+        # Enable nested groups:    "" "Existing"
+        properties {    "" "Existing"
+            "structurizr.groupSeparator" "/"
+        }    
+        # People and software systems
+        up4w = softwareSystem "UP4W " {
+            up4wagent = container "UP4W Windows Agent" {
+                configModule = component "Configuration Module"
+                landscapeProService = component "Landscape Pro Service" 
+            }
+            up4wgui = container "UP4W Windows GUI"
+        }
+        wslProService = softwareSystem "WSL Pro Service"
+
+        # group "Ubuntu Pro offering for Ubuntu WSL" {
+        canonical = person "Canonical Support Line" "24/7 enterprise support for Ubuntu and your full open source stack" "Existing"
+        landscape = softwareSystem "Landscape" "Included with your Ubuntu Pro subscription. Automates security patching, auditing, access management and compliance tasks across your Ubuntu estate." "Existing, Service"
+        upc = softwareSystem "Ubuntu Pro" "Automates the enablement of Ubuntu Pro services" "Existing"
+        # esm = softwareSystem "Canonical ESM" "1,800+ additional high and critical patches, 10 years of maintenance for the whole stack" "Existing"
+        # cis = softwareSystem "CIS" "Automates compliance and auditing with the Center for Internet Security (CIS) benchmarks" "Existing"
+        # }
+        landscapeClient = softwareSystem "Landscape Client" "" "Existing"
+        landscapeServer = softwareSystem "Landscape Server" "" "Existing"
+        proClient = softwareSystem "Ubuntu Pro Client" "" "Existing"        
+        user = person "User" 
+        windowsRegistry = softwareSystem "Windows registry" "" "Existing"
+        ups = softwareSystem "Ubuntu Pro subscription" "" "Existing, Service"
+        # wsl = softwareSystem "WSL" "" "Existing"         
+
+
+        # Relationships
+        configModule -> landscapeProService "Configures"
+        configModule -> windowsRegistry "Reads configuration from"
+        configModule -> wslProService "Sends configuration to"
+        landscapeServer -> landscapeClient "Reads from and sends instructions to"
+        landscapeServer -> landscapeProService "Reads from and sends instructions to"
+        up4w -> canonical "Enables 24/7 optional enterprise-grade support from"
+        up4w -> landscape "Registers your Windows host and Ubuntu WSL instances with"
+        up4w -> ups "Adds your Ubuntu WSL instances to your"
+        up4w -> upc "Attaches to Ubuntu Pro"
+        up4wgui -> up4wagent "Writes configuration to"
+        user -> up4w "Uses"
+        wslProService -> landscapeClient "Configures"
+        wslProService -> proClient "Configures"
+        # landscapeClient -> landscapeServer "Distro information
+        # landscapeProService -> landscapeClient "Executes commands"
+        # landscapeProService -> landscapeServer "Connects to, sends information to, and receives commands from""
+        # landscapeProService -> landscapeServer "System and WSL information"
+        # landscapeProService -> wsl "Starts and stops Ubuntu WSL instances created by"
+        # landscapeServer -> landscapeClient "Distro management commands"
+        # landscapeServer -> landscapeProService "Lifetime management commands"
+        # upc -> cis "Automates compliance and auditing"
+        # upc -> esm "Enables stability, security, and compliance with"
+
+
+        deploymentEnvironment "UP4WTutorial" {
+            g1 = deploymentGroup "1"
+            g2 = deploymentGroup "2"
+            g3 = deploymentGroup "3"
+            g4 = deploymentGroup "4"
+
+
+
+            deploymentNode "Your computer = Windows host" "" "Windows" {
+                softwareSystemInstance windowsRegistry g1            
+
+                deploymentNode "Ubuntu WSL instance (Ubuntu 22.04 LTS)" {
+                    softwareSystemInstance landscapeServer g1,g2
+                }
+
+                group "UP4W appx" {
+                    containerInstance up4wgui g1
+                    containerInstance up4wagent g1,g2
+                }
+
+                deploymentNode "Ubuntu WSL instance (Ubuntu Preview; created locally)" {
+                    softwareSystemInstance wslProService g1
+                    softwareSystemInstance proClient g1
+                    softwareSystemInstance landscapeClient g1
+
+                }
+
+                deploymentNode "Ubuntu WSL instance (Ubuntu; created remotely via Landscape Server)" {
+                    softwareSystemInstance wslProService g2
+                    softwareSystemInstance proClient g2
+                    softwareSystemInstance landscapeClient g2
+
+                }            
+
+            }
+        }
+
+
+
+        deploymentEnvironment "UbuntuProForWSL" {
+            deploymentNode "Your computer = Windows host" "" "Windows" {
+                group "UP4W appx" {
+                    containerInstance up4wgui
+                    containerInstance up4wagent
+                }
+                softwareSystemInstance windowsRegistry
+                # softwareSystemInstance WSL
+                deploymentNode "WSL (VM)" "" "" {
+                    deploymentNode "Ubuntu WSL instance (distro)" "" "Ubuntu (Preview)" {
+                        softwareSystemInstance wslProService
+                        softwareSystemInstance proClient
+                        softwareSystemInstance landscapeClient
+                    }
+
+                }
+            }
+            deploymentNode "Someone else's computer" "" "" {
+                softwareSystemInstance landscapeServer
+            }
+        }
+
+    }
+
+    views {
+        systemLandscape "SystemLandscape" {
+            include user up4w landscape ups
+            autoLayout
+        }    
+        systemContext up4w "SystemContext" {
+            include user up4w landscape ups
+            autoLayout
+        }
+
+        container up4w "SystemContainers" {
+            include *
+            autoLayout
+        }        
+        component up4wagent "ContainerComponents" {
+            include *
+            autoLayout
+        }    
+
+        deployment up4w "UbuntuProForWSL" "UbuntuProForWSL" {
+            include *
+            autoLayout
+            properties {
+                "structurizr.groups" true
+            }            
+        }     
+
+        deployment up4w "UP4WTutorial" "UP4WTutorial" {
+            include *
+            # autoLayout
+            properties {
+                "structurizr.groups" true
+            }            
+        }          
+
+        theme default
+
+        styles {
+            element "Element" {
+                metadata false
+                fontSize 25               
+                }
+            # element "Software System" {
+                # metadata false
+                # background #1168bd
+                # color #ffffff
+            # }
+            element "Person" {
+                metadata false
+                shape person
+                # background red
+                color #ffffff
+            }
+            element "Existing" {
+                background #999999
+                color #ffffff
+            }
+
+            element "Service" {
+                background #999999
+                color #ffffff
+                shape Box
+            }            
+        }    
+    }
+
+}