Static Web App documentation

1 Introduction

Documentation for the Council’s Data Science Azure Static Web App.

2 Azure Static Web App

Our Azure Static Web App¹ is called SCCStaticWeb01. To configure it you need to login to the Azure Portal: portal.azure.com.

The app uses the standard plan (access to all the features) which is £5/app a month because the free version is very limited.

3 Azure Repos

Azure Static Web Apps are built from repos².

4 Quarto Website

The ds-website repo is the initial source of the SWA.

The website format is provided by Quarto Website³.

_quarto.yml is where the main format and content items are configured⁴.

index.qmd is the homepage.

5 Deployment process

The deployment process is outlined in the diagram below.

flowchart LR
    A(change to<br><i>main</i> branch of<br><b><i>ds-website</i></b> repo) 
        --> B(
            triggers pipeline
            <b><i>ds-website-pipeline.yml</i></b>)
    B --> C(<b>render<br>Quarto<br>project</b>)     
    C --> D(deploys content of<br>repo sub-folder<br><b><i>/_site</i></b>)
    D --> E(to SWA at<br><i>scc-data-science.sheffield.gov.uk</i>)

flowchart LR
    A(change to<br><i>main</i> branch of<br><b><i>ds-website</i></b> repo) 
        --> B(
            triggers pipeline
            <b><i>ds-website-pipeline.yml</i></b>)
    B --> C(<b>render<br>Quarto<br>project</b>)     
    C --> D(deploys content of<br>repo sub-folder<br><b><i>/_site</i></b>)
    D --> E(to SWA at<br><i>scc-data-science.sheffield.gov.uk</i>)

6 Azure Pipelines

Our Azure Static Web App is built and deployed from Azure Repos using Azure Pipelines⁵.

There is a choice of where Quarto is rendered⁶. So far we’ve rendered everything within Azure DevOps rather than locally. However, rendering locally for testing purposes is needed, in which case something like the following is added to a .gitignore file so that rendered output isn’t included in the repo:

# Rendered Quarto output
homeless-risk.html
homeless-risk_*

ds-website-pipeline.yml is the configuration file for our pipeline.

Not all website content is contained within our ds-website repo. Most of the website content is contained in additional repos that we include in the build by adding the following resources in our pipeline YAML:

resources:
  repositories:
  - repository: swa-doc
    type: git
    name: DataScience/swa-doc
  - repository: homeless-risk
    type: git
    name: DataScience/homeless-risk  

Also in our pipeline YAML, these resources need to be checked out and their location specified ready for the Quarto project (website) to be rendered:

steps:
  - checkout: self
    workspaceRepo: true
    submodules: true
  - checkout: git://DataScience/swa-doc
    path: s/ds-website/swa-doc
  - checkout: git://DataScience/homeless-risk
    path: s/ds-website/homeless-risk

When adding a new resource to a pipeline, the first time it’s run it will pause and wait for you to provide permission:

Pipeline permission

The Azure Pipelines task reference⁷ is useful.

7 Navigation

Top bar navigation for the website⁸ is configured via the _quarto.yml file in the ds-website repo:

navbar:
  left:
    - text: "Home"
      href: index.qmd
    - text: "Projects"
      menu:
        - homeless-risk/homeless-risk.qmd
    - text: "Guidance"
      menu:
        - swa-doc/swa-documentation.qmd
    - text: "About"
      href: about.qmd

The size of the logo in the top bar is configured via the style.css file in the ds-website repo:

.navbar-logo {
    max-height: 50px;
  }

Listings⁹ can be added to the homepage via the YAML header in the index.qmd file in the ds-website repo:

listing:
  date-format: "D MMM YYYY"
  contents:
    - "swa-doc/*.qmd"
    - "homeless-risk/*.qmd"

8 Branding

We’ve applied some Council branding using brand.yml¹⁰.

This has involved adding the _brand.yml and scc-logo.png files to the root of our ds-website repo.

The _brand.yml file is from the NHS-R Community¹¹ with only minor modifications made so far.

Changes to branding should be made via github.com/scc-pi/brand-sheff.

9 Permissions

9.1 Change the app

Licenses and permissions to change the app are currently available to:

1. Alexandru Mocanu
   
2. Laurie Platt
   
3. Giles Robinson
   
4. Olumide Ogunyanwo

9.2 View content

Some content may need to be confidential as it could contain personal data, or organisationally sensitive information. Permissions to view different parts of the app is controlled via those listed above.

Initial thoughts on roles:

1. authenticated - everyone with a Sheffield City Council login.
   
2. administrator - Laurie, Giles, & Olumide.
   
3. all-content - Nicola McHugh & James Ford.
   
4. project-name - might be better as an area of the Council e.g. housing rather than SAA.

Note: authenticated and administrator are built-in roles, others we define ourselves.

9.2.1 Consent

The first time someone views the app, they are asked to consent to the app accessing their email and username to authenticate them.

Consent

9.2.2 Role management

Roles are allocated to accounts in the SWA Role management settings.

Role management

9.2.3 Role routes

Access to app content by different roles is defined in a config.json file in the /src sub-folder of the DataScience repo.

For example, an app with this homepage …

index.html

… and these json settings …

  "routes": [
    {
      "route": "/index.html",
      "allowedRoles": ["authenticated"]
    },
    {
      "route": "/folder1/project1.html",
      "allowedRoles": ["authenticated"]
    },
    {
      "route": "/folder2/project2.html",
      "allowedRoles": ["administrator", "project2"]
    }
  ]

… has the following permissions:

1. Everyone with a Council login can see the homepage.
   
2. Everyone with a Council login can see Project1 content.
   
3. Only administrators and those with a project2 role assigned in role management is able to see Project2 content.

10 Preview

We can preview changes to the website by manually triggering the ds-website preview pipeline:

Once completed we can inspect it at:
calm-moss-08771f003-preview.westeurope.4.azurestaticapps.net

We’ve used pipeline conditions¹² and created a named preview environment in our Azure Static Web App¹³.

The changes made include:

1. No trigger on changes to any branches or PRs in ds-website-pipeline.yml
   

trigger: none

2. Added condition and a named deployment_environment in ds-website-pipeline.yml
   

  - task: AzureStaticWebApp@0
    displayName: 'preview AzureStaticWebApp'
    condition: eq(variables.destination, 'preview')
    inputs:
      azure_static_web_apps_api_token: $(AZURE_STATIC_WEB_APPS_API_TOKEN_CALM_MOSS_08771F003)
      deployment_environment: "preview"

3. Added a new pipeline called ds-website preview with variable destination = preview.

Pipeline variable

4. Acquired the preview URL from the SWA Environments settings.

Preview environments

11 Checklist

1. Add new menu item under navbar in _quarto.yml in ds-website.
   
2. Add new contents item in index.qmd in ds-website (optional).
   
3. Add any new packages to requirements.txt in ds-website.
4. Add new repository item under resources to ds-website-pipeline.yml in ds-website.
   
5. Add checkout item under steps to ds-website-pipeline.yml in ds-website.
   
6. Complete a PR to main in ds-website.
   
7. The first time a pipeline uses a repo it will pause until permission is granted to access the new repo being used.
   
8. Preview the changes by manually running pipeline ds-website preview and view at calm-moss-08771f003-preview.westeurope.4.azurestaticapps.net.
9. Make the change live by manually running pipeline ds-website and view at scc-data-science.sheffield.gov.uk.

12 Kanban

Past and planned work on the website is detailed on an Azure Board¹⁴: dev.azure.com/SheffieldCityCouncil/DataScience/_boards/board/t/DataScience%20Team/Issues?System.Tags=swa.

Footnotes

1. Static Web Apps documentation (learn.microsoft.com/en-us/azure/static-web-apps)

2. Azure Repos documentation (learn.microsoft.com/en-us/azure/devops/repos/?view=azure-devops)

3. Quarto Website (quarto.org/docs/websites)

4. Quarto Website config file (quarto.org/docs/websites/#config-file)

5. Azure Pipelines documentation (learn.microsoft.com/en-us/azure/devops/pipelines)

6. Quarto rendering for CI (quarto.org/docs/publishing/ci.html#rendering-for-ci)

7. Azure Pipelines task reference (learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/?view=azure-pipelines)

8. Quarto website top navigation (quarto.org/docs/websites/website-navigation.html#top-navigation)

9. Quarto website listings (quarto.org/docs/websites/website-listings.html)

10. brand.yml (posit.co/blog/unified-branding-across-posit-tools-with-brand-yml)

11. NHS-R brand.yml (posit-dev.github.io/brand-yml/inspiration/brand-guidelines/nhsr-community)

12. Pipeline conditions (learn.microsoft.com/en-us/azure/devops/pipelines/process/conditions?view=azure-devops)

13. Create named preview environments in Azure Static Web Apps (learn.microsoft.com/en-us/azure/static-web-apps/named-environments?tabs=azure-devops)

14. Azure Boards documentation (learn.microsoft.com/en-us/azure/devops/boards/?view=azure-devops)