From 4faac86f7bb527a33e0acf666e266dbc30fd4138 Mon Sep 17 00:00:00 2001 From: Collinbrown95 Date: Wed, 25 Oct 2023 20:57:15 +0000 Subject: [PATCH] deploy: 0925267b50c77afb20fd1482b6d5ac61ac529f2d --- checks/url-checks/index.html | 446 ++++++++++++++++++++++++++++++++++ index.html | 451 +++++++++++++++++++++++++++++++++++ search/search_index.json | 2 +- sitemap.xml | 10 + sitemap.xml.gz | Bin 299 -> 307 bytes 5 files changed, 908 insertions(+), 1 deletion(-) create mode 100644 checks/url-checks/index.html create mode 100644 index.html diff --git a/checks/url-checks/index.html b/checks/url-checks/index.html new file mode 100644 index 0000000..204030e --- /dev/null +++ b/checks/url-checks/index.html @@ -0,0 +1,446 @@ + + + + + + + + + + + + + + + + + + URL (Service) Checks - Observatory (R U OK?) Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + +
+
+ + + + + + + + +

URL (Service) Checks

+

Some products have one or more services exposed through URLs. URL compliance checks perform a series of automated accessibility and security compliance checks using information that can be retrieved via these public URLs.

+

GraphQL Schema

+
1
+2
+3
+4
+5
+6
+7
type URLCheck {
+    accessibility: AccessibilityReport
+}
+
+type AccessibilityReport {
+    minimumColourContrast: ComplianceCheck
+    ariaLabelsIncluded: ComplianceCheck
+
+ + +
+ +
+
+ +
+ + + +
+
+
+
+ + + + + + + + \ No newline at end of file diff --git a/index.html b/index.html new file mode 100644 index 0000000..b5efe0d --- /dev/null +++ b/index.html @@ -0,0 +1,451 @@ + + + + + + + + + + + + + + + + + + Observatory (R U OK?) Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + +
+
+ + + + + + + + +

Observatory (R U OK?)

+

Observatory is an automated real-time scanning framework for products whose source code is managed on PHACDataHub. The purpose of Observatory is to ensure compliance with requirements around concerns such as security and accessibility.

+

Term Glossary

+

For the purposes of Observatory, we use the glossary below to define several terms used throughout our GraphQL Schema and data models.

+ + + + + + + + + + + + + + + + + +
TermMeaning
ProductAny software product managed under PHACDataHub.
ServiceAny software product managed under PHACDataHub that is exposed through one or more service URLs (i.e. not all products deploy services).
+ + +
+ +
+
+ +
+ + + +
+
+
+
+ + + + + + + + \ No newline at end of file diff --git a/search/search_index.json b/search/search_index.json index 6170769..c82c1f4 100644 --- a/search/search_index.json +++ b/search/search_index.json @@ -1 +1 @@ -{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-\\.]+"},"docs":[{"location":"architecture/","text":"RUOK Architecture The core architecture relies on an event-driven workflow based on GitHub Webhooks for repository events. A webhook server listens for repository events from GitHub. When a webhook event is received, the webhook server verifies the authenticity of the event (i.e. that it actually originated from GitHub.com), then publishes a repository event in a NATS queue. Multiple scanners are subscribed to NATS queue groups, where each scanner performs certain kinds of checks. For example, the \"Clone Repo Scanner\" shown on the diagram above may clone the repository on which an event was detected and perform certain compliance checks on the cloned repository, whereas the \"Octokit API scanner\" may call the GitHub API to verify certain properties of the repository. Scanners write their results to the GraphQL API as a mutation query. The GraphQL API in turn writes the requested changes to the appropriate document in ArangoDB. A small web application reads the data from ArangoDB by making the appropriate GraphQL query to the GraphQL API to report on products' health, compliance, security posture, and any other properties of interest.","title":"Architecture"},{"location":"architecture/#ruok-architecture","text":"The core architecture relies on an event-driven workflow based on GitHub Webhooks for repository events. A webhook server listens for repository events from GitHub. When a webhook event is received, the webhook server verifies the authenticity of the event (i.e. that it actually originated from GitHub.com), then publishes a repository event in a NATS queue. Multiple scanners are subscribed to NATS queue groups, where each scanner performs certain kinds of checks. For example, the \"Clone Repo Scanner\" shown on the diagram above may clone the repository on which an event was detected and perform certain compliance checks on the cloned repository, whereas the \"Octokit API scanner\" may call the GitHub API to verify certain properties of the repository. Scanners write their results to the GraphQL API as a mutation query. The GraphQL API in turn writes the requested changes to the appropriate document in ArangoDB. A small web application reads the data from ArangoDB by making the appropriate GraphQL query to the GraphQL API to report on products' health, compliance, security posture, and any other properties of interest.","title":"RUOK Architecture"},{"location":"deployment/","text":"Deploying on Kubernetes This document outlines how to deploy the Kubernetes application for ruok-service-autochecker . Deploying on a Local Kubernetes Cluster To deploy the ruok-service-autochecker application onto a local Kubernetes environment, ensure your current context is set to your local cluster (i.e. kubectl config set-context ). You can verify your Kubernetes context by running kubectl config get-contexts ; your current context will be indicated with * . Before deploying the application, it is necessary to first build and tag all of the images in this repository. You can build and tag all of the images by running make build . Note that you may need to perform an extra step of loading your locally built images into your local cluster's image registry (see Loading an image into the KinD Cluster , for example). Once connected to your local cluster, run make k8s to deploy the various manifests and kustomization.yaml files associated with the application. Continuous Deployment onto GKE TODO","title":"Deployment"},{"location":"deployment/#deploying-on-kubernetes","text":"This document outlines how to deploy the Kubernetes application for ruok-service-autochecker .","title":"Deploying on Kubernetes"},{"location":"deployment/#deploying-on-a-local-kubernetes-cluster","text":"To deploy the ruok-service-autochecker application onto a local Kubernetes environment, ensure your current context is set to your local cluster (i.e. kubectl config set-context ). You can verify your Kubernetes context by running kubectl config get-contexts ; your current context will be indicated with * . Before deploying the application, it is necessary to first build and tag all of the images in this repository. You can build and tag all of the images by running make build . Note that you may need to perform an extra step of loading your locally built images into your local cluster's image registry (see Loading an image into the KinD Cluster , for example). Once connected to your local cluster, run make k8s to deploy the various manifests and kustomization.yaml files associated with the application.","title":"Deploying on a Local Kubernetes Cluster"},{"location":"deployment/#continuous-deployment-onto-gke","text":"TODO","title":"Continuous Deployment onto GKE"},{"location":"development-environment/","text":"Development Environment This page outlines how to set up a development environment for this project. This document is meant to serve as a high-level mental model for how to set up a development environment. There are many ways to substitute certain components if a developer prefers one tool over another. Overview The diagram below shows a high-level overview of the development environment. VSCode is used as the integrated development environment. VSCode is run in client-server mode: The desktop VSCode application is downloaded for the operating system of choice, and a project-specific VSCode Dev Container is used to run VSCode server as a dev container. The VSCode Dev Container is attached to the host network, so the development container can access ports exposed on 127.0.0.1 , for example. K9s is used as a kubernetes dashboard, which provides a user interface for the developer to interact with the Kubernetes cluster. Podman is a daemonless and rootless OCI-compliant runtime and container manager that can be used to build OCI images and run containers on your development machine. Kubernetes in Docker (KinD) is a tool for running local kubernetes clusters entirely in OCI containers (i.e. OCI containers are used to run Kubernetes nodes). The sections below outline how to set up each component of this environment. VSCode Development Containers TLDR : The .devcontainer/devcontainer.json file contains the dev container configuration for this project. If you install the VSCode Dev Container extension and build/run the dev container, the dev container will be setup automatically. The section below highlights specific issues that you might encounter along with helpful resources to troubleshoot potential issues. Starting Dev Container as non-root user I added the \"containerUser\": \"node\" key to start the dev container as the default non-root node user for the dev container. Since I am running my dev container on Ubuntu Linux, I also needed to add the following line to my devcontainer.json file: 1 2 3 4 5 ... , \"runArgs\" : [ \"--userns=keep-id\" ], ... This line of configuration is necessary because, on Linux, podman maps the user ID (UID) that launched the container process to the root user of the container. By default, this means that my current user ID (usually 1000 in most cases) maps to the UID 1 (i.e. root user of the container user namespace). You can run podman unshare cat /proc/self/uid_map on the host machine to see how host UIDs map to UIDs in the container process namespaces. This caused problems as the files/folders in the repo are mounted to the container filesystem with root as the owner, so the node user didn't have permission to write to these files. Setting --userns=keep-id keeps the UID of 1000 in the container, so the repo files/folders that get mounted to the container filesystem are correctly owned by UID 1000 (i.e. node user), and it is possible to write to files in the container as the non-root user. See this stackoverflow answer for a more detailed explanation of how this works. Attach Development Container to Host Network As per this thread answer , add the following key in devcontainer.json . 1 2 3 4 5 ... , \"runArgs\" : [ \"--network=host\" ], ... VSCode Development Tools VSCode Integrated Debugger Debug configurations can be found in the .vscode/launch.json file in the project root. For information on how to use VSCode's integrated debugger, see the VSCode Debugging documentation . Environment Variable Management with direnv In order to run or debug a given application in a dev container, it may be necessary load a specific set of environment variables to configure that application. direnv is a tool that automatically loads environment variables into your shell when you cd into a folder. You may need to run direnv allow in a directory upon making changes to its .envrc file. Podman Instructions for installing the Podman runtime on all platforms can be found at this link . Additionally (and optionally), you can install Podman Desktop , which provides a graphical tool to facilitate working with podman. Using Podman with KinD It might be necessary to follow the steps in Kind - Rootless . After following these instructions, I had to run systemd-run --user --scope --property=Delegate=yes kind create cluster to create my kind cluster. This Linkedin Arcticle is also a good resource that reviews step-by-step setup of a KIND cluster using podman on Ubuntu Linux. Loading an image into the KinD Cluster KinD doesn't spin up a local registry out of the box, so it's necessary to run kind load docker-image to load a locally build container image into the KinD cluster. If you're using Podman Desktop, there is a UI convenience for this by navigating to the Images tab, then for the image(s) you want to load into the KinD cluster, click \"Push image to Kind cluster\" (see screenshot below). Related Issues KinD - Running with rootless podman doesn't work as documented KinD - Podman creation fails KinD - How I Wasted a Day Loading Local Docker Images","title":"Development Environment"},{"location":"development-environment/#development-environment","text":"This page outlines how to set up a development environment for this project. This document is meant to serve as a high-level mental model for how to set up a development environment. There are many ways to substitute certain components if a developer prefers one tool over another.","title":"Development Environment"},{"location":"development-environment/#overview","text":"The diagram below shows a high-level overview of the development environment. VSCode is used as the integrated development environment. VSCode is run in client-server mode: The desktop VSCode application is downloaded for the operating system of choice, and a project-specific VSCode Dev Container is used to run VSCode server as a dev container. The VSCode Dev Container is attached to the host network, so the development container can access ports exposed on 127.0.0.1 , for example. K9s is used as a kubernetes dashboard, which provides a user interface for the developer to interact with the Kubernetes cluster. Podman is a daemonless and rootless OCI-compliant runtime and container manager that can be used to build OCI images and run containers on your development machine. Kubernetes in Docker (KinD) is a tool for running local kubernetes clusters entirely in OCI containers (i.e. OCI containers are used to run Kubernetes nodes). The sections below outline how to set up each component of this environment.","title":"Overview"},{"location":"development-environment/#vscode-development-containers","text":"TLDR : The .devcontainer/devcontainer.json file contains the dev container configuration for this project. If you install the VSCode Dev Container extension and build/run the dev container, the dev container will be setup automatically. The section below highlights specific issues that you might encounter along with helpful resources to troubleshoot potential issues.","title":"VSCode Development Containers"},{"location":"development-environment/#starting-dev-container-as-non-root-user","text":"I added the \"containerUser\": \"node\" key to start the dev container as the default non-root node user for the dev container. Since I am running my dev container on Ubuntu Linux, I also needed to add the following line to my devcontainer.json file: 1 2 3 4 5 ... , \"runArgs\" : [ \"--userns=keep-id\" ], ... This line of configuration is necessary because, on Linux, podman maps the user ID (UID) that launched the container process to the root user of the container. By default, this means that my current user ID (usually 1000 in most cases) maps to the UID 1 (i.e. root user of the container user namespace). You can run podman unshare cat /proc/self/uid_map on the host machine to see how host UIDs map to UIDs in the container process namespaces. This caused problems as the files/folders in the repo are mounted to the container filesystem with root as the owner, so the node user didn't have permission to write to these files. Setting --userns=keep-id keeps the UID of 1000 in the container, so the repo files/folders that get mounted to the container filesystem are correctly owned by UID 1000 (i.e. node user), and it is possible to write to files in the container as the non-root user. See this stackoverflow answer for a more detailed explanation of how this works.","title":"Starting Dev Container as non-root user"},{"location":"development-environment/#attach-development-container-to-host-network","text":"As per this thread answer , add the following key in devcontainer.json . 1 2 3 4 5 ... , \"runArgs\" : [ \"--network=host\" ], ...","title":"Attach Development Container to Host Network"},{"location":"development-environment/#vscode-development-tools","text":"","title":"VSCode Development Tools"},{"location":"development-environment/#vscode-integrated-debugger","text":"Debug configurations can be found in the .vscode/launch.json file in the project root. For information on how to use VSCode's integrated debugger, see the VSCode Debugging documentation .","title":"VSCode Integrated Debugger"},{"location":"development-environment/#environment-variable-management-with-direnv","text":"In order to run or debug a given application in a dev container, it may be necessary load a specific set of environment variables to configure that application. direnv is a tool that automatically loads environment variables into your shell when you cd into a folder. You may need to run direnv allow in a directory upon making changes to its .envrc file.","title":"Environment Variable Management with direnv"},{"location":"development-environment/#podman","text":"Instructions for installing the Podman runtime on all platforms can be found at this link . Additionally (and optionally), you can install Podman Desktop , which provides a graphical tool to facilitate working with podman.","title":"Podman"},{"location":"development-environment/#using-podman-with-kind","text":"It might be necessary to follow the steps in Kind - Rootless . After following these instructions, I had to run systemd-run --user --scope --property=Delegate=yes kind create cluster to create my kind cluster. This Linkedin Arcticle is also a good resource that reviews step-by-step setup of a KIND cluster using podman on Ubuntu Linux.","title":"Using Podman with KinD"},{"location":"development-environment/#loading-an-image-into-the-kind-cluster","text":"KinD doesn't spin up a local registry out of the box, so it's necessary to run kind load docker-image to load a locally build container image into the KinD cluster. If you're using Podman Desktop, there is a UI convenience for this by navigating to the Images tab, then for the image(s) you want to load into the KinD cluster, click \"Push image to Kind cluster\" (see screenshot below).","title":"Loading an image into the KinD Cluster"},{"location":"development-environment/#related-issues","text":"KinD - Running with rootless podman doesn't work as documented KinD - Podman creation fails KinD - How I Wasted a Day Loading Local Docker Images","title":"Related Issues"},{"location":"github-webhooks/","text":"GitHub Webhooks webhook-server/ contains the implementation of the GitHub webhook server portion of this project. The purpose of this server is to listen for events triggered by certain events of interest on GitHub resources. Validating GitHub Webhook Deliveries TODO Local Development with GitHub Webhooks In order to test webhook-server locally, it is necessary to use a webhook proxy URL to forward webhooks from GitHub to your computer. Instructions for how to do this are as follows: In your browser, nagivate to https://smee.io/ and click Start a new channel . Copy the full URL under Webhook Proxy URL . Install the corresponding smee-client package from npm as a dev dependency: npm i sme-client --save-dev . Start the smee-client as follows: smee --url --path --port . Go to a repository of interest in the PHACDataHub Github organization, go to Settings --> Code and automation --> Webhooks --> Add new webhook and paste the Webhook Proxy URL from step 1. Choose application/json for the content type. You can also choose which repo events get forwarded, or select \"sent me everything\" to receive all events. Start up the webhook-server . Trigger an event on the GitHub repo that you registered the webhook with. If everything is set up correctly, you should receive a request to webhook-server where req.body contains the JSON payload of the GitHub webhook event. Helpful Resources testing webhooks redelivering webhooks about webhooks","title":"GitHub Webhooks"},{"location":"github-webhooks/#github-webhooks","text":"webhook-server/ contains the implementation of the GitHub webhook server portion of this project. The purpose of this server is to listen for events triggered by certain events of interest on GitHub resources.","title":"GitHub Webhooks"},{"location":"github-webhooks/#validating-github-webhook-deliveries","text":"TODO","title":"Validating GitHub Webhook Deliveries"},{"location":"github-webhooks/#local-development-with-github-webhooks","text":"In order to test webhook-server locally, it is necessary to use a webhook proxy URL to forward webhooks from GitHub to your computer. Instructions for how to do this are as follows: In your browser, nagivate to https://smee.io/ and click Start a new channel . Copy the full URL under Webhook Proxy URL . Install the corresponding smee-client package from npm as a dev dependency: npm i sme-client --save-dev . Start the smee-client as follows: smee --url --path --port . Go to a repository of interest in the PHACDataHub Github organization, go to Settings --> Code and automation --> Webhooks --> Add new webhook and paste the Webhook Proxy URL from step 1. Choose application/json for the content type. You can also choose which repo events get forwarded, or select \"sent me everything\" to receive all events. Start up the webhook-server . Trigger an event on the GitHub repo that you registered the webhook with. If everything is set up correctly, you should receive a request to webhook-server where req.body contains the JSON payload of the GitHub webhook event.","title":"Local Development with GitHub Webhooks"},{"location":"github-webhooks/#helpful-resources","text":"testing webhooks redelivering webhooks about webhooks","title":"Helpful Resources"},{"location":"graphql-api/","text":"","title":"GraphQL API"},{"location":"checks/source-code-repo-checks/","text":"","title":"Source code repo checks"}]} \ No newline at end of file +{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-\\.]+"},"docs":[{"location":"","text":"Observatory (R U OK?) Observatory is an automated real-time scanning framework for products whose source code is managed on PHACDataHub . The purpose of Observatory is to ensure compliance with requirements around concerns such as security and accessibility. Term Glossary For the purposes of Observatory, we use the glossary below to define several terms used throughout our GraphQL Schema and data models. Term Meaning Product Any software product managed under PHACDataHub . Service Any software product managed under PHACDataHub that is exposed through one or more service URLs (i.e. not all products deploy services).","title":"Observatory (R U OK?)"},{"location":"#observatory-r-u-ok","text":"Observatory is an automated real-time scanning framework for products whose source code is managed on PHACDataHub . The purpose of Observatory is to ensure compliance with requirements around concerns such as security and accessibility.","title":"Observatory (R U OK?)"},{"location":"#term-glossary","text":"For the purposes of Observatory, we use the glossary below to define several terms used throughout our GraphQL Schema and data models. Term Meaning Product Any software product managed under PHACDataHub . Service Any software product managed under PHACDataHub that is exposed through one or more service URLs (i.e. not all products deploy services).","title":"Term Glossary"},{"location":"architecture/","text":"RUOK Architecture The core architecture relies on an event-driven workflow based on GitHub Webhooks for repository events. A webhook server listens for repository events from GitHub. When a webhook event is received, the webhook server verifies the authenticity of the event (i.e. that it actually originated from GitHub.com), then publishes a repository event in a NATS queue. Multiple scanners are subscribed to NATS queue groups, where each scanner performs certain kinds of checks. For example, the \"Clone Repo Scanner\" shown on the diagram above may clone the repository on which an event was detected and perform certain compliance checks on the cloned repository, whereas the \"Octokit API scanner\" may call the GitHub API to verify certain properties of the repository. Scanners write their results to the GraphQL API as a mutation query. The GraphQL API in turn writes the requested changes to the appropriate document in ArangoDB. A small web application reads the data from ArangoDB by making the appropriate GraphQL query to the GraphQL API to report on products' health, compliance, security posture, and any other properties of interest.","title":"Architecture"},{"location":"architecture/#ruok-architecture","text":"The core architecture relies on an event-driven workflow based on GitHub Webhooks for repository events. A webhook server listens for repository events from GitHub. When a webhook event is received, the webhook server verifies the authenticity of the event (i.e. that it actually originated from GitHub.com), then publishes a repository event in a NATS queue. Multiple scanners are subscribed to NATS queue groups, where each scanner performs certain kinds of checks. For example, the \"Clone Repo Scanner\" shown on the diagram above may clone the repository on which an event was detected and perform certain compliance checks on the cloned repository, whereas the \"Octokit API scanner\" may call the GitHub API to verify certain properties of the repository. Scanners write their results to the GraphQL API as a mutation query. The GraphQL API in turn writes the requested changes to the appropriate document in ArangoDB. A small web application reads the data from ArangoDB by making the appropriate GraphQL query to the GraphQL API to report on products' health, compliance, security posture, and any other properties of interest.","title":"RUOK Architecture"},{"location":"deployment/","text":"Deploying on Kubernetes This document outlines how to deploy the Kubernetes application for ruok-service-autochecker . Deploying on a Local Kubernetes Cluster To deploy the ruok-service-autochecker application onto a local Kubernetes environment, ensure your current context is set to your local cluster (i.e. kubectl config set-context ). You can verify your Kubernetes context by running kubectl config get-contexts ; your current context will be indicated with * . Before deploying the application, it is necessary to first build and tag all of the images in this repository. You can build and tag all of the images by running make build . Note that you may need to perform an extra step of loading your locally built images into your local cluster's image registry (see Loading an image into the KinD Cluster , for example). Once connected to your local cluster, run make k8s to deploy the various manifests and kustomization.yaml files associated with the application. Continuous Deployment onto GKE TODO","title":"Deployment"},{"location":"deployment/#deploying-on-kubernetes","text":"This document outlines how to deploy the Kubernetes application for ruok-service-autochecker .","title":"Deploying on Kubernetes"},{"location":"deployment/#deploying-on-a-local-kubernetes-cluster","text":"To deploy the ruok-service-autochecker application onto a local Kubernetes environment, ensure your current context is set to your local cluster (i.e. kubectl config set-context ). You can verify your Kubernetes context by running kubectl config get-contexts ; your current context will be indicated with * . Before deploying the application, it is necessary to first build and tag all of the images in this repository. You can build and tag all of the images by running make build . Note that you may need to perform an extra step of loading your locally built images into your local cluster's image registry (see Loading an image into the KinD Cluster , for example). Once connected to your local cluster, run make k8s to deploy the various manifests and kustomization.yaml files associated with the application.","title":"Deploying on a Local Kubernetes Cluster"},{"location":"deployment/#continuous-deployment-onto-gke","text":"TODO","title":"Continuous Deployment onto GKE"},{"location":"development-environment/","text":"Development Environment This page outlines how to set up a development environment for this project. This document is meant to serve as a high-level mental model for how to set up a development environment. There are many ways to substitute certain components if a developer prefers one tool over another. Overview The diagram below shows a high-level overview of the development environment. VSCode is used as the integrated development environment. VSCode is run in client-server mode: The desktop VSCode application is downloaded for the operating system of choice, and a project-specific VSCode Dev Container is used to run VSCode server as a dev container. The VSCode Dev Container is attached to the host network, so the development container can access ports exposed on 127.0.0.1 , for example. K9s is used as a kubernetes dashboard, which provides a user interface for the developer to interact with the Kubernetes cluster. Podman is a daemonless and rootless OCI-compliant runtime and container manager that can be used to build OCI images and run containers on your development machine. Kubernetes in Docker (KinD) is a tool for running local kubernetes clusters entirely in OCI containers (i.e. OCI containers are used to run Kubernetes nodes). The sections below outline how to set up each component of this environment. VSCode Development Containers TLDR : The .devcontainer/devcontainer.json file contains the dev container configuration for this project. If you install the VSCode Dev Container extension and build/run the dev container, the dev container will be setup automatically. The section below highlights specific issues that you might encounter along with helpful resources to troubleshoot potential issues. Starting Dev Container as non-root user I added the \"containerUser\": \"node\" key to start the dev container as the default non-root node user for the dev container. Since I am running my dev container on Ubuntu Linux, I also needed to add the following line to my devcontainer.json file: 1 2 3 4 5 ... , \"runArgs\" : [ \"--userns=keep-id\" ], ... This line of configuration is necessary because, on Linux, podman maps the user ID (UID) that launched the container process to the root user of the container. By default, this means that my current user ID (usually 1000 in most cases) maps to the UID 1 (i.e. root user of the container user namespace). You can run podman unshare cat /proc/self/uid_map on the host machine to see how host UIDs map to UIDs in the container process namespaces. This caused problems as the files/folders in the repo are mounted to the container filesystem with root as the owner, so the node user didn't have permission to write to these files. Setting --userns=keep-id keeps the UID of 1000 in the container, so the repo files/folders that get mounted to the container filesystem are correctly owned by UID 1000 (i.e. node user), and it is possible to write to files in the container as the non-root user. See this stackoverflow answer for a more detailed explanation of how this works. Attach Development Container to Host Network As per this thread answer , add the following key in devcontainer.json . 1 2 3 4 5 ... , \"runArgs\" : [ \"--network=host\" ], ... VSCode Development Tools VSCode Integrated Debugger Debug configurations can be found in the .vscode/launch.json file in the project root. For information on how to use VSCode's integrated debugger, see the VSCode Debugging documentation . Environment Variable Management with direnv In order to run or debug a given application in a dev container, it may be necessary load a specific set of environment variables to configure that application. direnv is a tool that automatically loads environment variables into your shell when you cd into a folder. You may need to run direnv allow in a directory upon making changes to its .envrc file. Podman Instructions for installing the Podman runtime on all platforms can be found at this link . Additionally (and optionally), you can install Podman Desktop , which provides a graphical tool to facilitate working with podman. Using Podman with KinD It might be necessary to follow the steps in Kind - Rootless . After following these instructions, I had to run systemd-run --user --scope --property=Delegate=yes kind create cluster to create my kind cluster. This Linkedin Arcticle is also a good resource that reviews step-by-step setup of a KIND cluster using podman on Ubuntu Linux. Loading an image into the KinD Cluster KinD doesn't spin up a local registry out of the box, so it's necessary to run kind load docker-image to load a locally build container image into the KinD cluster. If you're using Podman Desktop, there is a UI convenience for this by navigating to the Images tab, then for the image(s) you want to load into the KinD cluster, click \"Push image to Kind cluster\" (see screenshot below). Related Issues KinD - Running with rootless podman doesn't work as documented KinD - Podman creation fails KinD - How I Wasted a Day Loading Local Docker Images","title":"Development Environment"},{"location":"development-environment/#development-environment","text":"This page outlines how to set up a development environment for this project. This document is meant to serve as a high-level mental model for how to set up a development environment. There are many ways to substitute certain components if a developer prefers one tool over another.","title":"Development Environment"},{"location":"development-environment/#overview","text":"The diagram below shows a high-level overview of the development environment. VSCode is used as the integrated development environment. VSCode is run in client-server mode: The desktop VSCode application is downloaded for the operating system of choice, and a project-specific VSCode Dev Container is used to run VSCode server as a dev container. The VSCode Dev Container is attached to the host network, so the development container can access ports exposed on 127.0.0.1 , for example. K9s is used as a kubernetes dashboard, which provides a user interface for the developer to interact with the Kubernetes cluster. Podman is a daemonless and rootless OCI-compliant runtime and container manager that can be used to build OCI images and run containers on your development machine. Kubernetes in Docker (KinD) is a tool for running local kubernetes clusters entirely in OCI containers (i.e. OCI containers are used to run Kubernetes nodes). The sections below outline how to set up each component of this environment.","title":"Overview"},{"location":"development-environment/#vscode-development-containers","text":"TLDR : The .devcontainer/devcontainer.json file contains the dev container configuration for this project. If you install the VSCode Dev Container extension and build/run the dev container, the dev container will be setup automatically. The section below highlights specific issues that you might encounter along with helpful resources to troubleshoot potential issues.","title":"VSCode Development Containers"},{"location":"development-environment/#starting-dev-container-as-non-root-user","text":"I added the \"containerUser\": \"node\" key to start the dev container as the default non-root node user for the dev container. Since I am running my dev container on Ubuntu Linux, I also needed to add the following line to my devcontainer.json file: 1 2 3 4 5 ... , \"runArgs\" : [ \"--userns=keep-id\" ], ... This line of configuration is necessary because, on Linux, podman maps the user ID (UID) that launched the container process to the root user of the container. By default, this means that my current user ID (usually 1000 in most cases) maps to the UID 1 (i.e. root user of the container user namespace). You can run podman unshare cat /proc/self/uid_map on the host machine to see how host UIDs map to UIDs in the container process namespaces. This caused problems as the files/folders in the repo are mounted to the container filesystem with root as the owner, so the node user didn't have permission to write to these files. Setting --userns=keep-id keeps the UID of 1000 in the container, so the repo files/folders that get mounted to the container filesystem are correctly owned by UID 1000 (i.e. node user), and it is possible to write to files in the container as the non-root user. See this stackoverflow answer for a more detailed explanation of how this works.","title":"Starting Dev Container as non-root user"},{"location":"development-environment/#attach-development-container-to-host-network","text":"As per this thread answer , add the following key in devcontainer.json . 1 2 3 4 5 ... , \"runArgs\" : [ \"--network=host\" ], ...","title":"Attach Development Container to Host Network"},{"location":"development-environment/#vscode-development-tools","text":"","title":"VSCode Development Tools"},{"location":"development-environment/#vscode-integrated-debugger","text":"Debug configurations can be found in the .vscode/launch.json file in the project root. For information on how to use VSCode's integrated debugger, see the VSCode Debugging documentation .","title":"VSCode Integrated Debugger"},{"location":"development-environment/#environment-variable-management-with-direnv","text":"In order to run or debug a given application in a dev container, it may be necessary load a specific set of environment variables to configure that application. direnv is a tool that automatically loads environment variables into your shell when you cd into a folder. You may need to run direnv allow in a directory upon making changes to its .envrc file.","title":"Environment Variable Management with direnv"},{"location":"development-environment/#podman","text":"Instructions for installing the Podman runtime on all platforms can be found at this link . Additionally (and optionally), you can install Podman Desktop , which provides a graphical tool to facilitate working with podman.","title":"Podman"},{"location":"development-environment/#using-podman-with-kind","text":"It might be necessary to follow the steps in Kind - Rootless . After following these instructions, I had to run systemd-run --user --scope --property=Delegate=yes kind create cluster to create my kind cluster. This Linkedin Arcticle is also a good resource that reviews step-by-step setup of a KIND cluster using podman on Ubuntu Linux.","title":"Using Podman with KinD"},{"location":"development-environment/#loading-an-image-into-the-kind-cluster","text":"KinD doesn't spin up a local registry out of the box, so it's necessary to run kind load docker-image to load a locally build container image into the KinD cluster. If you're using Podman Desktop, there is a UI convenience for this by navigating to the Images tab, then for the image(s) you want to load into the KinD cluster, click \"Push image to Kind cluster\" (see screenshot below).","title":"Loading an image into the KinD Cluster"},{"location":"development-environment/#related-issues","text":"KinD - Running with rootless podman doesn't work as documented KinD - Podman creation fails KinD - How I Wasted a Day Loading Local Docker Images","title":"Related Issues"},{"location":"github-webhooks/","text":"GitHub Webhooks webhook-server/ contains the implementation of the GitHub webhook server portion of this project. The purpose of this server is to listen for events triggered by certain events of interest on GitHub resources. Validating GitHub Webhook Deliveries TODO Local Development with GitHub Webhooks In order to test webhook-server locally, it is necessary to use a webhook proxy URL to forward webhooks from GitHub to your computer. Instructions for how to do this are as follows: In your browser, nagivate to https://smee.io/ and click Start a new channel . Copy the full URL under Webhook Proxy URL . Install the corresponding smee-client package from npm as a dev dependency: npm i sme-client --save-dev . Start the smee-client as follows: smee --url --path --port . Go to a repository of interest in the PHACDataHub Github organization, go to Settings --> Code and automation --> Webhooks --> Add new webhook and paste the Webhook Proxy URL from step 1. Choose application/json for the content type. You can also choose which repo events get forwarded, or select \"sent me everything\" to receive all events. Start up the webhook-server . Trigger an event on the GitHub repo that you registered the webhook with. If everything is set up correctly, you should receive a request to webhook-server where req.body contains the JSON payload of the GitHub webhook event. Helpful Resources testing webhooks redelivering webhooks about webhooks","title":"GitHub Webhooks"},{"location":"github-webhooks/#github-webhooks","text":"webhook-server/ contains the implementation of the GitHub webhook server portion of this project. The purpose of this server is to listen for events triggered by certain events of interest on GitHub resources.","title":"GitHub Webhooks"},{"location":"github-webhooks/#validating-github-webhook-deliveries","text":"TODO","title":"Validating GitHub Webhook Deliveries"},{"location":"github-webhooks/#local-development-with-github-webhooks","text":"In order to test webhook-server locally, it is necessary to use a webhook proxy URL to forward webhooks from GitHub to your computer. Instructions for how to do this are as follows: In your browser, nagivate to https://smee.io/ and click Start a new channel . Copy the full URL under Webhook Proxy URL . Install the corresponding smee-client package from npm as a dev dependency: npm i sme-client --save-dev . Start the smee-client as follows: smee --url --path --port . Go to a repository of interest in the PHACDataHub Github organization, go to Settings --> Code and automation --> Webhooks --> Add new webhook and paste the Webhook Proxy URL from step 1. Choose application/json for the content type. You can also choose which repo events get forwarded, or select \"sent me everything\" to receive all events. Start up the webhook-server . Trigger an event on the GitHub repo that you registered the webhook with. If everything is set up correctly, you should receive a request to webhook-server where req.body contains the JSON payload of the GitHub webhook event.","title":"Local Development with GitHub Webhooks"},{"location":"github-webhooks/#helpful-resources","text":"testing webhooks redelivering webhooks about webhooks","title":"Helpful Resources"},{"location":"graphql-api/","text":"","title":"GraphQL API"},{"location":"checks/source-code-repo-checks/","text":"","title":"Source code repo checks"},{"location":"checks/url-checks/","text":"URL (Service) Checks Some products have one or more services exposed through URLs. URL compliance checks perform a series of automated accessibility and security compliance checks using information that can be retrieved via these public URLs. GraphQL Schema 1 2 3 4 5 6 7 type URLCheck { accessibility : AccessibilityReport } type AccessibilityReport { minimumColourContrast : ComplianceCheck ariaLabelsIncluded : ComplianceCheck","title":"URL (Service) Checks"},{"location":"checks/url-checks/#url-service-checks","text":"Some products have one or more services exposed through URLs. URL compliance checks perform a series of automated accessibility and security compliance checks using information that can be retrieved via these public URLs.","title":"URL (Service) Checks"},{"location":"checks/url-checks/#graphql-schema","text":"1 2 3 4 5 6 7 type URLCheck { accessibility : AccessibilityReport } type AccessibilityReport { minimumColourContrast : ComplianceCheck ariaLabelsIncluded : ComplianceCheck","title":"GraphQL Schema"}]} \ No newline at end of file diff --git a/sitemap.xml b/sitemap.xml index 475cd3d..04adf40 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -1,5 +1,10 @@ + + https://phacdatahub.github.io/ruok-service-autochecker/ + 2023-10-25 + daily + https://phacdatahub.github.io/ruok-service-autochecker/architecture/ 2023-10-25 @@ -30,4 +35,9 @@ 2023-10-25 daily + + https://phacdatahub.github.io/ruok-service-autochecker/checks/url-checks/ + 2023-10-25 + daily + \ No newline at end of file diff --git a/sitemap.xml.gz b/sitemap.xml.gz index e2ee13f300214a7b3648214744bf8c121142f752..62c84fd82b0eb939ec84ffd9c7bba5618fd00928 100644 GIT binary patch literal 307 zcmV-30nGj%iwFoRfjMOY|8r?{Wo=<_E_iKh0M(UEZp0uAh4*ucD0@OCRi(B{m|aiM z9)KZkKtnKNNYc4|$&acWpsEya4Ce9lnT4q@-@VO7pkUB7`MD_b44lH&xUR`RKi=6( zei5g7AR8cNN$f(C>lpnT=hHM5!9?h#4+T=kgVJde_*Ud)@tTWMmSQ$oS4-3um6%;Z zvhiA~Rz|6ZYtflFCxe^@ys-c@8U;)a5tFyN0r8s8m-k*W#2#BwmDLkFm#lhDlC8Fr zDJ@+GUj%p2N@E{2-&Iyf{!96Xypoho@1f#Aa5(rDyv0WkE*=nl1dD!VXW&Ld=nmP( zDq#~`HR3HCkDsL1cgv(VhhtxInrAprI!R*@7=cH&)eqWEGW@p=mXy8@@dJ-1d5LNU F007ssi%|do literal 299 zcmV+`0o48WQ68 zRy`-nrtNG>OV_~{!Ckb{*hkHG%1X?Ck^d0B1#j`ugNp}5AHkxZ*%`Re5V}L|v0B&! xSB-cJ$KxmI_1!Y*&EeRWp6&w1FZTi2jv$S-`#18;^w7vKQ006xfm!<#!