diff --git a/docs/contribute/pipelines/lind-wasm.md b/docs/contribute/pipelines/lind-wasm.md new file mode 100644 index 000000000..8baf0b4c7 --- /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 000000000..4109abf72 --- /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 f72c24658..6890b9133 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -36,6 +36,9 @@ 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 - Community: - community/index.md - Team: community/team.md