From d867a804dbfcb6d917b3b86e83dd5b4c3d24a7bf Mon Sep 17 00:00:00 2001 From: Uk-jake Date: Wed, 13 May 2026 15:26:10 -0400 Subject: [PATCH 1/2] add ci/cd pipeline documentation --- docs/contribute/pipelines/lind-wasm-apps.md | 45 ++++++++++ .../pipelines/lind-wasm-example-grates.md | 42 +++++++++ docs/contribute/pipelines/lind-wasm.md | 90 +++++++++++++++++++ docs/contribute/pipelines/overview.md | 39 ++++++++ mkdocs.yml | 5 ++ 5 files changed, 221 insertions(+) create mode 100644 docs/contribute/pipelines/lind-wasm-apps.md create mode 100644 docs/contribute/pipelines/lind-wasm-example-grates.md create mode 100644 docs/contribute/pipelines/lind-wasm.md create mode 100644 docs/contribute/pipelines/overview.md diff --git a/docs/contribute/pipelines/lind-wasm-apps.md b/docs/contribute/pipelines/lind-wasm-apps.md new file mode 100644 index 0000000000..0c27e68403 --- /dev/null +++ b/docs/contribute/pipelines/lind-wasm-apps.md @@ -0,0 +1,45 @@ +# lind-wasm-apps + +Its pipeline covers scheduled Docker image builds that cross-compile applications to run on the Lind runtime. + +## Overview + +This repository uses GCP for the Docker image build that publishes the applications image to Docker Hub. +GHA is not currently configured for this repository, but workflows will be added if validation pipelines are needed in the future. + +| Platform | Role | +| --- | --- | +| GitHub Actions | Not currently configured | +| Google Cloud Platform | Builds and publishes `securesystemslab/lind-wasm-apps` to Docker Hub on a scheduled basis | + +## GCP Cloud Build + +Build configuration files are located under `scripts/` in the repository. + +### Workflows + +- **`app-build`** — Cloning the `main` branch at the time of execution. Builds the repository `Dockerfile` on top of `securesystemslab/lind-wasm-dev` and publishes the resulting image to Docker Hub as `securesystemslab/lind-wasm-apps`. + +## Docker Images + +The `lind-wasm-apps` pipeline publishes one Docker image to Docker Hub. + +### `securesystemslab/lind-wasm-apps` + +The runtime image containing the Lind environment and cross-compiled WASM application binaries, ready to execute immediately. Built on top of `securesystemslab/lind-wasm-dev`. + +| Property | Detail | +| --- | --- | +| Source | `Dockerfile` in the repository root | +| Base image | `securesystemslab/lind-wasm-dev:latest` | +| Published by | GCP `app-build` | +| Tags | `latest` — most recent build; `sha-` — immutable snapshot for rollback | + +The image currently includes the following applications: bash, coreutils, cpython, lmbench, sed, nginx, grep, curl, git, and postgres. Additional applications will be added in the future. + +### Pulling the Images + +```bash +# Latest applications image +docker pull securesystemslab/lind-wasm-apps:latest +``` diff --git a/docs/contribute/pipelines/lind-wasm-example-grates.md b/docs/contribute/pipelines/lind-wasm-example-grates.md new file mode 100644 index 0000000000..7750f24631 --- /dev/null +++ b/docs/contribute/pipelines/lind-wasm-example-grates.md @@ -0,0 +1,42 @@ +# lind-wasm-example-grates + +Its pipeline covers scheduled Docker image builds that compile syscall interceptors (grates) to run on the Lind runtime. + +## Overview + +This repository uses GCP for the Docker image build that publishes the grates image to Docker Hub. GHA is not currently configured for this repository, but workflows will be added if validation pipelines are needed in the future. + +| Platform | Role | +| --- | --- | +| GitHub Actions | Not currently configured | +| Google Cloud Platform | Builds and publishes `securesystemslab/lind-wasm-grates-examples` to Docker Hub on a scheduled basis | + +## GCP Cloud Build + +Build configuration files are located under `scripts/` in the repository. + +### Workflows + +- **`grates-build`** — Cloning the `main` branch at the time of execution. Builds the repository `Dockerfile` on top of `securesystemslab/lind-wasm-dev`, runs the grates test suite, and publishes the resulting image to Docker Hub as `securesystemslab/lind-wasm-grates-examples`. The image is pushed even when tests fail, so developers can inspect the container state to diagnose failures. + +## Docker Images + +The `lind-wasm-example-grates` pipeline publishes one Docker image to Docker Hub. + +### `securesystemslab/lind-wasm-grates-examples` + +The dev image containing the Lind runtime and compiled grates, primarily used for debugging test failures in-container. Built on top of `securesystemslab/lind-wasm-dev`. + +| Property | Detail | +| --- | --- | +| Source | `Dockerfile` in the repository root | +| Base image | `securesystemslab/lind-wasm-dev:latest` | +| Published by | GCP `grates-build` | +| Tags | `latest` — most recent build; `sha-` — immutable snapshot for rollback | + +### Pulling the Images + +```bash +# Latest grates image +docker pull securesystemslab/lind-wasm-grates-examples:latest +``` \ No newline at end of file diff --git a/docs/contribute/pipelines/lind-wasm.md b/docs/contribute/pipelines/lind-wasm.md new file mode 100644 index 0000000000..8baf0b4c76 --- /dev/null +++ b/docs/contribute/pipelines/lind-wasm.md @@ -0,0 +1,90 @@ +# lind-wasm + +Its pipeline covers both code validation on pull requests and scheduled Docker image builds. + +## Overview + +This repository uses both GHA and GCP. GHA validates code on every pull request, +while GCP handles the scheduled Docker image build that publishes the development image to Docker Hub. + +| Platform | Role | +| --- | --- | +| GitHub Actions | Runs lint, end-to-end tests, and security scans on pull requests targeting `main`; publishes the release image | +| Google Cloud Platform | Builds and publishes `securesystemslab/lind-wasm-dev` to Docker Hub on a daily schedule | + +## GitHub Actions + +Workflow files are located under `.github/workflows/` in the repository. + +### Workflows + +- **`lint.yml`** — Runs `cargo fmt --check` and `cargo clippy` for code formatting +and static analysis. + +- **`e2e.yml`** — Builds and runs the full test suite inside a container. Uploads +HTML and JSON test reports as artifacts and posts a summary comment to the PR. + +- **`zizmor.yml`** — Scans GHA workflow files for security vulnerabilities such as +script injection and overly broad permissions. + +- **`docs.yml`** — Builds and deploys the project documentation site to GitHub Pages. + +- **`pr-cache-cleanup.yml`** — Removes the GHA build cache associated with a closed +PR to keep storage usage under control. + +- **`release.yml`** — Builds and pushes the `release` stage as `securesystemslab/lind-wasm` to Docker Hub. + +### Workflow Triggers + +| Event | Workflows Triggered | +| --- | --- | +| PR opened or updated | `lint.yml`, `e2e.yml`, `zizmor.yml` | +| Push to `main` | `lint.yml`, `e2e.yml`, `docs.yml` | +| PR closed | `pr-cache-cleanup.yml` | +| Monthly schedule (1st of each month, 08:00 UTC) | `release.yml` | +| Manual (`workflow_dispatch`) | `release.yml` | + + +## GCP Cloud Build + +Build configuration files are located under `scripts/` in the repository. + +### Workflows + +- **`dev-build`** — Cloning the `main` branch at the time of execution. Builds `Docker/Dockerfile.dev` and publishes the resulting image to Docker Hub as `securesystemslab/lind-wasm-dev`. + +## Docker Images + +The `lind-wasm` pipeline publishes two Docker images to Docker Hub. + +### `securesystemslab/lind-wasm-dev` + +The development image containing the full Lind toolchain for building and running WASM applications. + +| Property | Detail | +| --- | --- | +| Source | `Docker/Dockerfile.dev` | +| Published by | GCP `dev-build` (daily) | +| Tags | `latest` — most recent build; `sha-` — immutable snapshot for rollback | +| Update frequency | Daily at 08:00 America/New_York | + +### `securesystemslab/lind-wasm` + +The release image built from the `release` stage of `Docker/Dockerfile.e2e`. + +| Property | Detail | +| --- | --- | +| Source | `Docker/Dockerfile.e2e` (`release` stage) | +| Published by | GHA `release.yml` (monthly) | +| Tags | `latest` — most recent build; `sha-` — immutable snapshot for rollback | +| Update frequency | Monthly (1st of each month, 08:00 UTC) | + +### Pulling the Images + +```bash +# Latest development image +docker pull securesystemslab/lind-wasm-dev:latest + +# Latest release image +docker pull securesystemslab/lind-wasm:latest +``` \ No newline at end of file diff --git a/docs/contribute/pipelines/overview.md b/docs/contribute/pipelines/overview.md new file mode 100644 index 0000000000..4109abf724 --- /dev/null +++ b/docs/contribute/pipelines/overview.md @@ -0,0 +1,39 @@ +# Pipelines + +We use two CI/CD platforms across three repositories. This section documents the +pipeline setup for each repository. + +## Platforms + +Pipelines run on **GitHub Actions (GHA)** and **Google Cloud Platform (GCP)**. +The two platforms have separate responsibilities and operate independently. + +| Platform | Role | +| --- | --- | +| GitHub Actions | Code validation on every pull request — lint checks, end-to-end tests, and security scans | +| Google Cloud Platform | Docker image builds and publishing — runs resource-intensive builds that exceed GHA's disk and CPU limits | + +GCP is used for builds that exceed GHA runner disk and CPU limits — primarily +Docker image builds that compile large codebases from source. + + + +## Image Dependencies + +The Lind project consists of three repositories with a clear dependency chain. +`lind-wasm` is the core runtime; the other two repositories build on top of it. + +``` +lind-wasm + │ + │ produces + ▼ +securesystemslab/lind-wasm-dev + │ + ├──────────────────────────────┐ + │ │ + ▼ ▼ +lind-wasm-apps lind-wasm-example-grates +``` + +`lind-wasm-apps` and `lind-wasm-example-grates` both pull the `lind-wasm-dev` image as their base. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index f72c24658f..3a68b9fe62 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -36,6 +36,11 @@ nav: - Security policy: contribute/security.md - Docker Hub release workflow: contribute/docker-release-workflow.md - End-to-End Testing: contribute/e2e-testing.md + - Pipelines: + - Overview: contribute/pipelines/overview.md + - lind-wasm: contribute/pipelines/lind-wasm.md + - lind-wasm-apps: contribute/pipelines/lind-wasm-apps.md + - lind-wasm-example-grates: contribute/pipelines/lind-wasm-example-grates.md - Community: - community/index.md - Team: community/team.md From e1fd075c8a353c4197f02a6f058c2fc1254bcae8 Mon Sep 17 00:00:00 2001 From: Uk-jake Date: Mon, 8 Jun 2026 19:11:24 +0000 Subject: [PATCH 2/2] delete grate, apps docs --- docs/contribute/pipelines/lind-wasm-apps.md | 45 ------------------- .../pipelines/lind-wasm-example-grates.md | 42 ----------------- mkdocs.yml | 2 - 3 files changed, 89 deletions(-) delete mode 100644 docs/contribute/pipelines/lind-wasm-apps.md delete mode 100644 docs/contribute/pipelines/lind-wasm-example-grates.md diff --git a/docs/contribute/pipelines/lind-wasm-apps.md b/docs/contribute/pipelines/lind-wasm-apps.md deleted file mode 100644 index 0c27e68403..0000000000 --- a/docs/contribute/pipelines/lind-wasm-apps.md +++ /dev/null @@ -1,45 +0,0 @@ -# lind-wasm-apps - -Its pipeline covers scheduled Docker image builds that cross-compile applications to run on the Lind runtime. - -## Overview - -This repository uses GCP for the Docker image build that publishes the applications image to Docker Hub. -GHA is not currently configured for this repository, but workflows will be added if validation pipelines are needed in the future. - -| Platform | Role | -| --- | --- | -| GitHub Actions | Not currently configured | -| Google Cloud Platform | Builds and publishes `securesystemslab/lind-wasm-apps` to Docker Hub on a scheduled basis | - -## GCP Cloud Build - -Build configuration files are located under `scripts/` in the repository. - -### Workflows - -- **`app-build`** — Cloning the `main` branch at the time of execution. Builds the repository `Dockerfile` on top of `securesystemslab/lind-wasm-dev` and publishes the resulting image to Docker Hub as `securesystemslab/lind-wasm-apps`. - -## Docker Images - -The `lind-wasm-apps` pipeline publishes one Docker image to Docker Hub. - -### `securesystemslab/lind-wasm-apps` - -The runtime image containing the Lind environment and cross-compiled WASM application binaries, ready to execute immediately. Built on top of `securesystemslab/lind-wasm-dev`. - -| Property | Detail | -| --- | --- | -| Source | `Dockerfile` in the repository root | -| Base image | `securesystemslab/lind-wasm-dev:latest` | -| Published by | GCP `app-build` | -| Tags | `latest` — most recent build; `sha-` — immutable snapshot for rollback | - -The image currently includes the following applications: bash, coreutils, cpython, lmbench, sed, nginx, grep, curl, git, and postgres. Additional applications will be added in the future. - -### Pulling the Images - -```bash -# Latest applications image -docker pull securesystemslab/lind-wasm-apps:latest -``` diff --git a/docs/contribute/pipelines/lind-wasm-example-grates.md b/docs/contribute/pipelines/lind-wasm-example-grates.md deleted file mode 100644 index 7750f24631..0000000000 --- a/docs/contribute/pipelines/lind-wasm-example-grates.md +++ /dev/null @@ -1,42 +0,0 @@ -# lind-wasm-example-grates - -Its pipeline covers scheduled Docker image builds that compile syscall interceptors (grates) to run on the Lind runtime. - -## Overview - -This repository uses GCP for the Docker image build that publishes the grates image to Docker Hub. GHA is not currently configured for this repository, but workflows will be added if validation pipelines are needed in the future. - -| Platform | Role | -| --- | --- | -| GitHub Actions | Not currently configured | -| Google Cloud Platform | Builds and publishes `securesystemslab/lind-wasm-grates-examples` to Docker Hub on a scheduled basis | - -## GCP Cloud Build - -Build configuration files are located under `scripts/` in the repository. - -### Workflows - -- **`grates-build`** — Cloning the `main` branch at the time of execution. Builds the repository `Dockerfile` on top of `securesystemslab/lind-wasm-dev`, runs the grates test suite, and publishes the resulting image to Docker Hub as `securesystemslab/lind-wasm-grates-examples`. The image is pushed even when tests fail, so developers can inspect the container state to diagnose failures. - -## Docker Images - -The `lind-wasm-example-grates` pipeline publishes one Docker image to Docker Hub. - -### `securesystemslab/lind-wasm-grates-examples` - -The dev image containing the Lind runtime and compiled grates, primarily used for debugging test failures in-container. Built on top of `securesystemslab/lind-wasm-dev`. - -| Property | Detail | -| --- | --- | -| Source | `Dockerfile` in the repository root | -| Base image | `securesystemslab/lind-wasm-dev:latest` | -| Published by | GCP `grates-build` | -| Tags | `latest` — most recent build; `sha-` — immutable snapshot for rollback | - -### Pulling the Images - -```bash -# Latest grates image -docker pull securesystemslab/lind-wasm-grates-examples:latest -``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 3a68b9fe62..6890b91332 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -39,8 +39,6 @@ nav: - Pipelines: - Overview: contribute/pipelines/overview.md - lind-wasm: contribute/pipelines/lind-wasm.md - - lind-wasm-apps: contribute/pipelines/lind-wasm-apps.md - - lind-wasm-example-grates: contribute/pipelines/lind-wasm-example-grates.md - Community: - community/index.md - Team: community/team.md