Static Web App documentation

Author

Laurie Platt, Giles Robinson & Olumide Ogunyanwo

Published

Last updated 02 May, 2025

1 Introduction

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

2 Checklist

This is a summary checklist for adding new content to the website.

2.1 Local render

Test adding new content to the website by rendering it locally.

  1. Add sub-folder in local ds-website repo e.g. C:/repo/ds-website/python-doc.
  2. Copy content to the new sub-folder from e.g. C:/repo/python-doc. Don’t copy .git or .gitignore.
  3. Add the sub-folder name to .gitignore in ds-website repo.
  4. Install any packages to venv in local ds-website repo that you need but don’t already have.
  5. Add new menu item under navbar in _quarto.yml in ds-website.
  6. Add new contents item in index.qmd in ds-website (optional).
  7. From the Command Pallete in ds-website: > Quarto: Render Project. Open e.g. C:/repo/ds-website/_site/index.html.

2.2 CI render

After testing locally move to DevOps for CI (Continuous Integration) render.

In ds-website-pipeline.yml in ds-website:

  1. Add new repository item under resources.
  2. Add checkout item under steps.
  3. Add any new packages via pip install commands under script.

Then:

  1. Merge changes to main via PR. This will trigger the pipeline.
  2. The first time the pipeline is run it will pause until permission is granted to access the new repo being used.
  3. Open scc-data-science.sheffield.gov.uk

2.3 TODO

  1. Restrict access to content (issue 6320).
  2. Dev and test envs via repo branches (issue 6145).
  3. Other rendering options (issue 6519).

3 Azure Static Web App

Our Azure Static Web App1 is called SCCStaticWeb01. To configure it you need to login with an extranet account (e.g. Laurie.Platt@SCCExtranet.onmicrosoft.com) 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.

4 Azure Repos

Azure Static Web Apps are built from repos2.

5 Proof-of-concept

A proof-of-concept Azure Static Web App (SWA) was setup by Alexandru. Its deployment is currently paused.

The deployment process is outlined in the diagram below.

Code 
flowchart LR
    A(change to<br><i>main</i> branch of<br><i>DataScience</i> repo) 
        --> B(
            triggers pipeline
            <i>azure-static-web-apps-calm-moss-08771f003-pipeline.yml</i>)
    B --> C(deploys content of<br>repo sub-folder<br><i>/src</i>)
    C --> D(to SWA at<br><i>scc-data-science.sheffield.gov.uk</i>)

flowchart LR
    A(change to<br><i>main</i> branch of<br><i>DataScience</i> repo) 
        --> B(
            triggers pipeline
            <i>azure-static-web-apps-calm-moss-08771f003-pipeline.yml</i>)
    B --> C(deploys content of<br>repo sub-folder<br><i>/src</i>)
    C --> D(to SWA at<br><i>scc-data-science.sheffield.gov.uk</i>)

6 Permissions

6.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

6.2 View content

Some content may need to be confidential as it may 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.

6.2.2 Role management

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

Role management

6.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.

7 Quarto Website

The ds-website repo replaces the proof-of-concept DataScience repo as the initial source of the SWA.

The website format is provided by Quarto Website3.

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

index.qmd is the homepage.

The new deployment process is outlined in the diagram below. It has an additional step (“render Quarto project”) in the middle.

Code 
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>)

8 Azure Pipelines

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

There is a choice of where Quarto is rendered6. 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

These also 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 reference7 is useful.

9 Branding

We’ve applied Council branding using brand.yml8.

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 Community9 with only minor modifications made so far.

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

11 Kanban

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