DoS Road Distance

Table of Contents

• DoS Road Distance
  • Table of Contents
  • Overview
  • Quick Start
    • Development Requirements
    • Local Environment Configuration
    • Local Project Setup
  • Contributing
  • Development
  • Testing
    • Test data and mock services
    • Manual check
  • Deployment
    • Summary of branch, PR and commit naming
      • Branch naming
        • Rules
        • Examples
      • PR naming
        • Rules
        • Example PR name
      • Commit messages
        • Rules
        • Example commit messages
    • Artefact Versioning
    • CI/CD Pipelines
    • Deployment From the Command-line
    • Secrets
    • AWS Access
  • Architecture
    • Diagrams
      • System Context Diagram
      • Container Diagram
      • Component Diagram
      • Processes and Data Flow
      • Infrastructure
      • Networking
    • Integration
      • Interfaces
      • Dependencies
    • Data
    • Authentication and authorisation
    • Technology Stack
    • Key Architectural Decisions
    • System Quality Attributes
    • Guiding Principles
  • Operation
    • Error Handling
    • Observability
    • Auditing
    • Backups
    • Cloud Environments
    • Runbooks
  • Product
    • Communications
    • Documentation

Overview

A few sentences what business problem this project solves...

Quick Start

Development Requirements

• macOS operating system provisioned with the curl -L bit.ly/make-devops-macos-setup | bash command
• iTerm2 command-line terminal and Visual Studio Code source code editor, which will be installed automatically for you in the next steps

Local Environment Configuration

Clone the repository

git clone [project-url]
cd ./[project-dir]

The following is equivalent to the curl -L bit.ly/make-devops-macos-setup | bash command

make macos-setup

Please, ask one of your colleagues for the AWS account numbers used by the project. The next command will prompt you to provide them. This information can be sourced from a properly set up project by running make show-configuration | grep ^AWS_ACCOUNT_ID_

make devops-setup-aws-accounts

Generate and trust a self-signed certificate that will be used locally to enable encryption in transit

make trust-certificate

Local Project Setup

make setup
make build
make start log
open https://ui.project.local:8443

Contributing

Here is the list of the development practices that have to be followed by the team and the individual members:

• Only use single canonical branch master. Any intermediate branch significantly increases the maintenance overhead of the repository.
• Apply the git rebase workflow and never merge from master to a task branch. Follow the squash-rebase-merge pattern to keep the history linear and clean.
• Cryptographically sign your commits using gpg to ensure its content have not been tampered with.
• Format the summary message of your Pull/Merge Request using the following pattern "JIRA-XXX Descriptive name" to enable tooling to produce release notes automatically.
• Announce your PR/MR on the development Slack channel to allow any team member to review it and to share the knowledge. A change can be merged only if all comments have been addressed and it has been approved by at least one peer.

Before starting any work, please read CONTRIBUTING.md for more detailed instructions.

Development

• Describe how to
  • Connect to a local database
  • Interact with mock components
  • Switch each individual component to the dev mode
• Code formatting
• Code quality
• Reference the TODO.md file
• Provide guidance on how to use feature toggles and branching by abstraction

Testing

List all the type of test suites included and provide instructions how to execute them

• Unit
• Integration
• Contract
• End-to-end
• Performance
• Security
• Smoke

How to run test suite in the pipeline

Test data and mock services

• How the test data set is produced
• Are there any mock services in place

Manual check

Here are the steps to perform meaningful local system check:

• Log in to the system using a well known username role

Deployment

Summary of branch, PR and commit naming

Branch naming

Rules

• Starts with task/
• Then the ticket reference with upper case PD
• Then underscore and three plus words underscore delimited, first letter of first word upper case
• No punctuation at the end

Examples

task/PD-1234_Makefile_build_cleanup

PR naming

Rules

• The ticket reference with upper case PD
• Then a space and three plus words space delimited, first letter of first word upper case
• No punctuation at the end

Example PR name

PD-1234 Cleaned up code

Commit messages

Rules

• The ticket reference with upper case PD
• Then a space and three plus words space delimited, first letter of first word upper case
• No punctuation at the end of the first line
• You can have multiple lines with anything else needed, but each line must be less then 75 characters
• Note: All commits must be GPG signed

git commit -S -m "<MESSAGE>"

Example commit messages

PD-1234 Changed copy and cleanup process for a build

PD-1234 This is a longer commit
message spread over multiple
lines.
We can also add extra information

Artefact Versioning

E.g. semantic versioning vs. timestamp-based

CI/CD Pipelines

List all the pipelines and their purpose

• Development
• Test
• Cleanup
• Production (deployment)

Reference the jenkins/README.md file

Deployment From the Command-line

make deploy PROFILE=dev

Secrets

Where are the secrets located, i.e. AWS Secrets Manager, under the $(PROJECT_ID)-$(PROFILE)/deployment secret name and variable $(DEPLOYMENT_SECRETS) should be set accordingly.

AWS Access

To be able to interact with a remote environment, please make sure you have set up your AWS CLI credentials and MFA to the right AWS account using the following command

tx-mfa

Architecture

Diagrams

System Context Diagram

Include a link to the C4 model System Context diagram

Container Diagram

Include a link to the C4 model Container diagram

Component Diagram

Include a link to the C4 model Component diagram

Processes and Data Flow

Include a link to the Processes and Data Flow diagram

Infrastructure

Include a link to the Infrastructure diagram. Please, be aware that any sensitive information that can be potentially misused either directly or indirectly must not be stored and accessible publicly. This could be IP addresses, domain names or detailed infrastructure information.

Networking

Include a link to the Networking diagram. Please, be aware that any sensitive information must not be stored and accessible publicly. This could be IP addresses, domain names or detailed networking information.

Integration

Interfaces

Document all the system external interfaces

• API documentation should be generated automatically

Dependencies

Document all the system external dependencies and integration points

Data

What sort of data system operates on and processes

• Data set
• Consistency and integrity
• Persistence

Authentication and authorisation

• Default user login for testing
• Different user roles
• Authosrisation type
• Authentication method

It is recommended that any other documentation related to the aspect of security should be stored in a private workspace.

Technology Stack

What are the technologies and programing languages used to implement the solution

Key Architectural Decisions

Link or include the abbreviated list of the ADRs

System Quality Attributes

• Accessibility, usability
• Resilience, durability, fault-tolerance
• Scalability, elasticity
• Consistency
• Performance
• Interoperability
• Security
• Supportability

Guiding Principles

List of the high level principles that a product /development team must adhere to:

• The solution has to be coded in the open - e.g. NHSD GitHub org
• Be based on the open standards, frameworks and libraries
• API-first design
• Test-first approach
• Apply the automate everything pattern
• AWS-based cloud solution deployable to the NHSD CPaaS Texas platform
• Use of the Make DevOps automation scripts (macOS and Linux)

Operation

Error Handling

• What is the system response under the erroneous conditions

Observability

• Logging
  • Indexes
  • Format
• Tracing
  • Correlation ID
• Monitoring
  • Dashboards
• Alerting
  • Triggers
  • Service status
• Fitness functions
  • What do we measure?

What are the links of the supporting systems?

Auditing

Are there any auditing requirements in accordance with the data retention policies?

Backups

• Frequency and type of the backups
• Instructions on how to recover the data

Cloud Environments

List all the environments and their relation to profiles

• Development
  • Profile: dev
  • URL address: https://?.k8s-dev.texasplatform.uk/
  • Username: ?@nhs.net
  • Password: stored in the AWS Secrets Manager ?
• Test
• Demo
• Live

Describe how to provision and deploy to a task branch environment

Runbooks

List all the operational runbooks

Product

Communications

• Slack channels
  • Development, e.g. [service-name]-development
  • CI/CD and data pipelines, processes, e.g. [service-name]-automation
  • Service status, e.g. [service-name]-status
• Email addresses in use, e.g. [service.name]@nhs.net

All of the above can be service, product, application or even team specific.

Documentation

• Sprint board link
• Backlog link
• Roadmap link
• Risks register link
• Documentation workspace link