Operations Engineering Example Application

This repository contains an example application demonstrating Operations Engineering application standards to follow when deploying to the Cloud Platform and using the following tools; flask, docker, helm. Intended to be used as an evolving template.

Table of Contents

1. Prerequisites
2. How to use
3. Updating dependencies
4. Generic settings
5. Deployment
6. Contributing
7. Contact
8. License

Prerequisites

To develop, deploy or run this app you will need to install:

• Python 3.12
• Docker and Docker Compose (Optional, for running a local AWS DynamoDB instance or development/production servers with Docker Compose)
• Helm and Kubectl (Optional, for deploying to Cloud Platform)

How to use

Create a new application

We rely on naming conventions to facilitate use of this template. All Operations Engineering applications are named in the form <TEAM_NAME>-<NAME>, where TEAM_NAME=operations-engineering, hence operations-engineering-example, operations-engineering-reports etc. This convention is followed throughout the code in the kubernetes namespace, helm chart, and GitHub deployment workflows. Thus to create a new application choose the value of <NAME> and proceed,

• Create a repo called <TEAM_NAME>-<NAME>, for example, operations-engineering-example

• Copy the contents of this repo into it and make the following changes

  1. In .github/workflows/deploy-to-dev.yml and .github/workflows/deploy-to-prod.yml update the value of NAME under the env section at the top of the file:

     env:
       TEAM_NAME: operations-engineering
       NAME: example
       ENV: dev
     

  2. Update the subdirectory helm/operations-engineering-example to helm/<TEAM_NAME>-<NAME>, this is the helm chart name.

  3. In helm/Chart.yaml update the value of name with <TEAM_NAME>-<NAME>.

  4. In helm/<TEAM_NAME>-<NAME>/values.yaml update the values of teamName and name at the top of the file with <TEAM_NAME> and <NAME> respectively.

  5. In config.py update as required, for example CONTACT_EMAIL, SERVICE_NAME, SERVICE_URL. This file provides configuration for the GOVUK frontend.

  6. Update README.md.

• Create Cloud Platform namespaces called <TEAM_NAME>-<NAME>-<ENV> for example, operations-engineering-example-dev and operations-engineering-example-prod and link to the repo. Follow instructions here: Creating a Cloud Platform environment.

• The app is available at <TEAM_NAME>-<NAME>-<ENV>.cloud-platform.service.justice.gov.uk

Updating dependencies

This app is set up with dependabot to automatically raise PRs to update dependencies. Note that the govuk-frontend package version is hardcoded in build.py and application/templates/components/base.html, which must be updated manually if another version is required. The version of govuk-frontend is determined by the version of govuk-frontend-jijna set in the requirements.txt file. The current verison of govuk-frontend is recorded in application/static/VERSION.txt. For example, govuk-frontend-jinja 2.7.0 requires govuk-frontend 4.7.0.

Generic settings

The flask app itself is deliberately generically named application and does not need to be changed. If you choose to change it then corresponding changes are required in build.py, Dockerfile, makefile and possibly elsewhere. The app is hardcoded to run and listen on port 1551 as appuser 1051 (see Dockerfile and compose.yaml).

See below for how deployment to dev and prod is triggered.

Deployment

Development environment

The development namespace for this project is called operations-engineering-example-dev.

A merge to the main branch triggers the deploy-to-dev workflow. This runs a helm upgrade command to update the deployment.

To deploy manually, follow the steps in the deploy-to-dev GitHub workflow.

The development app is available at: https://operations-engineering-example-dev.cloud-platform.service.justice.gov.uk/

Access information on the deployment in Cloud Platform using kubectl or helm, for example;

kubectl -n operations-engineering-example-dev get pods
helm -n operations-engineering-example-dev list
helm -n operations-engineering-example-dev history operations-engineering-example-dev

Production environment

The production namespace on Cloud Platform for this project is called operations-engineering-example-prod.

To deploy the app to the production namespace do the following:

• Switch to the main branch and ensure it is up to date.
• Create a new tag using git tag vx.y.z where x.y.z is the new version number, and the v prefix provides the match criterion to trigger deployment. Please follow semantic versioning.
• Push the tag to the remote repository using git push origin --tags

This triggers the deploy-to-prod GitHub workflow to create a release and deploy the app to the production namespace.

The production app is available at: https://operations-engineering-example-prod.cloud-platform.service.justice.gov.uk/

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please update tests as appropriate.

Contact

If you have any questions or need further clarification, feel free to ask in the #ask-operations-engineering channel on Slack or email us at operations-engineering@digital.justice.gov.uk.

License

This project is licensed under the MIT License - see the LICENSE file for details.