FAQ | This is a LIVE service | Changelog

Skip to content
Snippets Groups Projects

Improve Ballots page & add Authorised Editors + Team Responsible info

Closed Improve Ballots page & add Authorised Editors + Team Responsible info
nb745-master-patch-30895 into master
Closed Nick Brown requested to merge nb745-master-patch-30895 into master
Compare
and
1 file
+ 109
− 78
Compare changes
  • Side-by-side
  • Inline
docs/services/regent-house-ballots.md
+ 109
− 78
# Regent House Ballots application
# Regent House Ballots Application
This page gives an overview of the Regent House ballots application, describing its current status,
where and how it's developed and deployed, and who is responsible for maintaining it.
This page gives an overview of the Regent House ballots application,
describing its current status, where and how it's developed and deployed,
and who is responsible for maintaining it.
## Service Description
The [Regent
House](https://www.governance.cam.ac.uk/governance/key-bodies/rh-senate/pages/regent-house-membership-and-rights.aspx)
is a key governance body for the University. Membership of the Region House will vote in *Ballots of
the Regent House*. These ballots cover a wide range of issues facing the Regent House.
The [Regent House][regent-house] is a key governance body for the University.
Membership of the Region House will vote in *Ballots of the Regent House*.
These ballots cover a wide range of issues facing the Regent House.
The University out-sources the actual voting recording and tallying to an external third-party. All
ballots have a list of eligible voters. For each voter on a particular ballot, the third-party
provider gives the University a unique URL which the voter can use to vote on a ballot.
The University out-sources the actual voting recording and tallying to an external third-party.
All ballots have a list of eligible voters.
For each voter on a particular ballot, the third-party provider gives the University
a unique URL which the voter can use to vote on a ballot.
This web application presents a single shareable URL representing a ballot. When a University member
visits that URL, they are authenticated and, should they be on the voter list for that ballot, they
are redirected to their unique voting URL.
This web application presents a single shareable URL representing a ballot.
When a University member visits that URL, they are authenticated.
If they are on the voter list for that ballot, they are then redirected to their unique voting URL.
Additionally, this web application provides a management interface which allows administrators to
create ballots, specify the times at which they open and close and upload a list of voters along
@@ -24,109 +25,120 @@ with unique voter URLs.
## Service Status
The Region House Ballots app is currently in early user testing.
The Region House Ballots app is fully operational.
## Contact
Technical queries and support should be directed as per our [contact page](../contact/index.md).
Issues discovered in the *functionality* of service or new feature requests should be opened as
GitLab issues in the [application
project](https://gitlab.developers.cam.ac.uk/uis/devops/regent-house-ballots/ballots-webapp/).
GitLab issues in the [application project][app-project].
Issues discovered with deployment, e.g. mis-configured certificates, broken authentication, etc,
should be opened as GitLab issues in the [deployment
project](https://gitlab.developers.cam.ac.uk/uis/devops/regent-house-ballots/infrastructure).
should be opened as GitLab issues in the [infrastructure project][infra-project].
## Environments
The Regent House Ballots application is currently deployed to the following environments with the
following SAML metadata records:
| Name | URL | Metadata record |
| ----------- | ------------------ | -- |
| Production | <https://ballots.apps.cam.ac.uk/> | <https://metadata.raven.cam.ac.uk/metadata/show/945/> |
| Staging | <https://staging.ballots.apps.cam.ac.uk/> | <https://metadata.raven.cam.ac.uk/metadata/show/944/> |
| Development | <https://development.ballots.apps.cam.ac.uk/> | <https://metadata.raven.cam.ac.uk/metadata/show/943/> |
<!-- markdownlint-disable MD013 -->
| Name | URL | Metadata record |
|-------------|-----------------------------------------------|-------------------------------------------------------|
| Production | <https://ballots.apps.cam.ac.uk/> | <https://metadata.raven.cam.ac.uk/metadata/show/945/> |
| Staging | <https://staging.ballots.apps.cam.ac.uk/> | <https://metadata.raven.cam.ac.uk/metadata/show/944/> |
| Development | <https://development.ballots.apps.cam.ac.uk/> | <https://metadata.raven.cam.ac.uk/metadata/show/943/> |
<!-- markdownlint-enable MD013 -->
## Notification channel(s) for environments
## Notification Channels
| Environment | Display name | Email |
| ----------- | ------------ | ----- |
<!-- markdownlint-disable MD013 -->
| Environment | Display name | Email |
|-------------|----------------------------------------------------------|------------------------------------|
| Production | Regent House Ballots - Jackson DevOps team email channel | **<devops-jackson@uis.cam.ac.uk>** |
<!-- markdownlint-enable MD013 -->
## Source code
## Source Code
The source code for the Regent House Ballots application is spread over the following repositories:
| Repository | Description |
| ----------- | ------------------ |
| [Web application](https://gitlab.developers.cam.ac.uk/uis/devops/regent-house-ballots/ballots-webapp/) | Django-based web application |
| [Infrastructure](https://gitlab.developers.cam.ac.uk/uis/devops/regent-house-ballots/infrastructure/) | Terraform-based deployment |
| Repository | Description |
|---------------------------------|------------------------------|
| [Web application][app-project] | Django-based web application |
| [Infrastructure][infra-project] | Terraform-based deployment |
These repositories are configured in the [GitLab project
factory](https://gitlab.developers.cam.ac.uk/uis/devops/infra/gitlab-project-factory/).
These repositories are configured in the [GitLab project factory][gitlab-project-factory].
## Technologies used
## Technologies Used
The following gives an overview of the technologies the Regent House Ballots application is built on.
The following gives an overview of
the technologies the Regent House Ballots application is built on.
| Category | Language | Framework(s) |
| -------- | -------- | --------- |
| Web application | Python | Django |
| Deployment | Terraform | Google Cloud Platform |
| Category | Language | Framework(s) |
|-----------------|-----------|-----------------------|
| Web application | Python | Django |
| Deployment | Terraform | Google Cloud Platform |
Special note should be taken that this application uses Raven SAML 2.0 for authentication.
Post-deployment configuration steps are documented in the [deployment project's
README](https://gitlab.developers.cam.ac.uk/uis/devops/regent-house-ballots/infrastructure#post-deploy-configuration).
Post-deployment configuration steps are documented in the
[infrastructure project's README][post-deploy-config].
## Operational documentation
## Operational Documentation
The following gives an overview of how the Regent House Ballots application is deployed and
maintained.
### Users' guide
### User Guide
The users' guide for the application is maintained in a [Google
doc](https://docs.google.com/document/d/17msoT7ORlBXHDweKMhSCmqporN55HGt-nfO_Zsl1mNU/edit) and is
published to a [public
website](https://docs.google.com/document/d/e/2PACX-1vToIr4wGk9GWT8_zXXoIFnl1sEs9nhlGN7yGgwGiiTRISKJCCRzScTsM22EGQkDfXrYUmdGpd7lIwWZ/pub)
which is linked to from the application itself. This link may be customised in the terraform
configuration.
The User Guide for this application is maintained in a [Google Doc][user-guide]
and is published to a [public website][user-guide-web] which is linked to
from the application itself.
### Access control
* This link may be customised in the terraform configuration.
* The web version has been published via **Google Docs > File > Share > Publish to web**.
* Source document edits will appear almost immediately in the web version.
Access control in the application is keyed by Lookup group membership. This is configured in the
deployment project.
#### Authorised Editors
The following people are authorised to edit the Google Doc linked above:
* [Ceri Benton](https://lookup.cam.ac.uk/person/crsid/cb765)
The document has been shared with them with **Commenter** role.
This allows them to enter **Suggesting** mode.
Suggested edits should then be reviewed by the **Team Responsible** *(see below)*
and applied for inclusion.
### Access Control
Access control in the application is keyed by Lookup group membership.
This is configured in the infrastructure project.
> **IMPORTANT** The membership of the uis-regent-house-ballot-{...} groups must be "University" or
> "World" in order for Raven SAML 2 to pass membership information to the application.
In **development**, any member of
[uis-regent-house-ballot-superadmins](https://www.lookup.cam.ac.uk/group/uis-regent-house-ballot-superadmins)
In **development**, any member of [uis-regent-house-ballot-superadmins][superadmins]
has both staff and superuser status.
In **production** and **staging**, members of
[uis-regent-house-ballot-superadmins](https://www.lookup.cam.ac.uk/group/uis-regent-house-ballot-superadmins)
have both staff and superuser status. Members of
[uis-regent-house-ballot-administrators](https://www.lookup.cam.ac.uk/group/uis-regent-house-ballot-administrators)
In **production** and **staging**, members of [uis-regent-house-ballot-superadmins][superadmins]
have both staff and superuser status. Members of [uis-regent-house-ballot-administrators][admins]
have staff and ballot manager status.
In production and staging, it is envisaged that technical support staff will be members of
uis-regent-house-ballot-superadmins while "normal" ballot administrators will be members of
uis-regent-house-ballot-administrators.
`uis-regent-house-ballot-superadmins` while "normal" ballot administrators will be members of
`uis-regent-house-ballot-administrators`.
### How and where the Regent House Ballots application is deployed
### How & where it's deployed
Deployment is via our standard [terraform deployment CI
pipeline](https://gitlab.developers.cam.ac.uk/uis/devops/continuous-delivery/ci-templates/-/blob/master/auto-devops/terraform-pipeline.yml?ref_type=heads).
Deployment is via our standard [terraform deployment CI pipeline][terraform-ci].
### Deploying a new release
Making a new release of the application is done via [release
automation](../explanations/gitlab-release-automation.md). In short: merged commits are collected
together into a draft "next release" Merge Request. When merged, a new release tag is pushed to the
repository along with a Docker image being pushed to Google's Artefact registry.
Making a new release of the application is done via [release automation][release-automation].
In short: merged commits are collected together into a draft "next release" Merge Request.
When merged, a new release tag is pushed to the repository
along with a Docker image being pushed to Google's Artefact registry.
Deployment is done by:
@@ -139,20 +151,39 @@ Deployment is done by:
Monitoring is configured as per our standard Google Cloud Run application module.
## Service management and tech lead
## Service Management
The **Service Owner** for this application is
[Ceri Benton](https://www.lookup.cam.ac.uk/person/crsid/cb765).
The **Service Manager** for this application is
[Andrew Crook](https://www.lookup.cam.ac.uk/person/crsid/ajc322).
The **service owner** for the Regent House Ballots application is [Ceri
Benton](https://www.lookup.cam.ac.uk/person/crsid/cb765).
The **Tech Lead** for this application is
[Rich Wareham](https://www.lookup.cam.ac.uk/person/crsid/rjw57).
The **service manager** for the Regent House Ballots application is [Andrew
Crook](https://www.lookup.cam.ac.uk/person/crsid/ajc322).
The **Team Responsible** for this application is
[Jackson Team](mailto:devops-jackson@uis.cam.ac.uk).
The **tech lead** for the Regent House Ballots application is **TBA**.
The following engineers have operational experience with this application
and are able to respond to support requests or incidents:
The following engineers have operational experience with the Regent House Ballots application and
are able to respond to support requests or incidents:
* [Mark Hill](https://www.lookup.cam.ac.uk/person/crsid/mh2215).
* [Rich Wareham](https://www.lookup.cam.ac.uk/person/crsid/rjw57).
Contacts at the University's voting provider are included in the
[infrastructure project's README][infra-readme].
Contacts at the University's voting provider are included in the [infrastructure project's
README](https://gitlab.developers.cam.ac.uk/uis/devops/regent-house-ballots/infrastructure/).
<!-- markdownlint-disable MD013 -->
[regent-house]: https://www.governance.cam.ac.uk/governance/key-bodies/rh-senate/pages/regent-house-membership-and-rights.aspx
[infra-readme]: https://gitlab.developers.cam.ac.uk/uis/devops/regent-house-ballots/infrastructure/
[user-guide]: https://docs.google.com/document/d/17msoT7ORlBXHDweKMhSCmqporN55HGt-nfO_Zsl1mNU/edit
[user-guide-web]: https://docs.google.com/document/d/e/2PACX-1vToIr4wGk9GWT8_zXXoIFnl1sEs9nhlGN7yGgwGiiTRISKJCCRzScTsM22EGQkDfXrYUmdGpd7lIwWZ/pub
[terraform-ci]: https://gitlab.developers.cam.ac.uk/uis/devops/continuous-delivery/ci-templates/-/blob/master/auto-devops/terraform-pipeline.yml?ref_type=heads
[app-project]: https://gitlab.developers.cam.ac.uk/uis/devops/regent-house-ballots/ballots-webapp/
[infra-project]: https://gitlab.developers.cam.ac.uk/uis/devops/regent-house-ballots/infrastructure
[gitlab-project-factory]: https://gitlab.developers.cam.ac.uk/uis/devops/infra/gitlab-project-factory/
[post-deploy-config]: https://gitlab.developers.cam.ac.uk/uis/devops/regent-house-ballots/infrastructure#post-deploy-configuration
[superadmins]: https://www.lookup.cam.ac.uk/group/uis-regent-house-ballot-superadmins
[admins]: https://www.lookup.cam.ac.uk/group/uis-regent-house-ballot-administrators
[release-automation]: (../explanations/gitlab-release-automation.md)
<!-- markdownlint-enable MD013 -->