Skip to content

docs: add OCI Registry example and awesome-wasmcloud to Templates & Examples #1237

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ericgregory wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add OCI Registry example and awesome-wasmcloud to Templates & Examples #1237

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 23 additions & 3 deletions docs/examples.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ wash new https://github.com/wasmCloud/wasmCloud.git --name my-project --subfolde

#### HTTP API with Distributed Workloads (Rust)

A two-component Rust workspace demonstrating distributed workloads over messaging. An `http-api` component receives `POST /task` requests and dispatches work via `wasmcloud:messaging/consumer`; a `task-leet` component exports `wasmcloud:messaging/handler` and transforms the payload (e.g., text → "leet speak"). During `wash dev`, the runtime routes calls between components in-process — no NATS server required.
A two-component Rust workspace demonstrating distributed workloads over messaging. An `http-api` component receives `POST /task` requests and dispatches work via `wasmcloud:messaging/consumer`; a `task-leet` component exports `wasmcloud:messaging/handler` and transforms the payload (e.g., text → "leet speak"). During `wash dev`, the runtime routes calls between components in-process — no NATS server required. When deployed with multiple replicas (as of wasmCloud 2.6.0), replicas join a per-component consumer group by default so that one replica handles each message; set `consumer_group` to `broadcast` in the component's configuration to deliver every message to every replica.

- **Source**: [`wasmCloud/wasmCloud — templates/http-api-with-distributed-workloads`](https://github.com/wasmCloud/wasmCloud/tree/main/templates/http-api-with-distributed-workloads)
- **`http-api` interfaces**: Imports `wasmcloud:messaging/consumer@0.2.0`; exports `wasi:http/incoming-handler` (via the `wstd` `#[http_server]` proc macro)
Expand Down Expand Up @@ -252,7 +252,7 @@ wash new https://github.com/wasmCloud/typescript.git --name my-project --subfold

#### HTTP API with Distributed Workloads

A two-component TypeScript project demonstrating component-to-component coordination over `wasmcloud:messaging`. An `http-api` component accepts `POST /task` requests and dispatches work via `wasmcloud:messaging/consumer`; a `task-worker` component exports `wasmcloud:messaging/handler`, processes the payload, and returns a reply. During `wash dev`, the runtime routes calls between components in-process — no NATS server required.
A two-component TypeScript project demonstrating component-to-component coordination over `wasmcloud:messaging`. An `http-api` component accepts `POST /task` requests and dispatches work via `wasmcloud:messaging/consumer`; a `task-worker` component exports `wasmcloud:messaging/handler`, processes the payload, and returns a reply. During `wash dev`, the runtime routes calls between components in-process — no NATS server required. When deployed with multiple replicas (as of wasmCloud 2.6.0), replicas join a per-component consumer group by default so that one replica handles each message; set `consumer_group` to `broadcast` in the component's configuration to deliver every message to every replica.

- **Source**: [`wasmCloud/typescript — templates/http-api-with-distributed-workloads`](https://github.com/wasmCloud/typescript/tree/main/templates/http-api-with-distributed-workloads)
- **`http-api` interfaces**: Imports `wasmcloud:messaging/consumer@0.2.0`; exports `wasi:http/incoming-handler@0.2.6`
Expand Down Expand Up @@ -280,12 +280,13 @@ wash new https://github.com/wasmCloud/typescript.git --name my-project --subfold

## Examples

Complete example applications are available in the [`examples/` directory of `wasmCloud/wasmCloud`](https://github.com/wasmCloud/wasmCloud/tree/main/examples) (Rust) and the [`examples/components/` directory of `wasmCloud/typescript`](https://github.com/wasmCloud/typescript/tree/main/examples/components) (TypeScript). Run `wash dev` from any example directory to build and start a local development environment.
Complete example applications are available in the [`examples/` directory of `wasmCloud/wasmCloud`](https://github.com/wasmCloud/wasmCloud/tree/main/examples) (Rust) and the [`examples/components/` directory of `wasmCloud/typescript`](https://github.com/wasmCloud/typescript/tree/main/examples/components) (TypeScript). Run `wash dev` from any example directory to build and start a local development environment (check individual entries for any additional build requirements).

| Example | Language | OCI Artifact |
|---|---|---|
| [Blobby](#blobby) | Rust | [`ghcr.io/wasmcloud/components/blobby`](https://github.com/orgs/wasmCloud/packages/container/package/components%2Fblobby) |
| [gRPC Hello World](#grpc-hello-world) | Rust | [`components/grpc-hello-world-client`](https://github.com/orgs/wasmCloud/packages/container/package/components%2Fgrpc-hello-world-client), [`components/grpc-hello-world-server`](https://github.com/orgs/wasmCloud/packages/container/package/components%2Fgrpc-hello-world-server) |
| [OCI Registry](#oci-registry) | Rust | — |
| [OpenTelemetry Config](#opentelemetry-config) | Rust | [`ghcr.io/wasmcloud/components/otel-config`](https://github.com/orgs/wasmCloud/packages/container/package/components%2Fotel-config) |
| [QR Code Generator](#qr-code-generator) | Rust | [`ghcr.io/wasmcloud/components/qrcode`](https://github.com/orgs/wasmCloud/packages/container/package/components%2Fqrcode) |
| [HTTP Axios](#http-axios) | TypeScript | — |
Expand Down Expand Up @@ -315,6 +316,17 @@ Two components demonstrating how to make and serve gRPC calls from a wasmCloud c
- **`component-client` interfaces**: Imports `wasi:http/outgoing-handler`; exports `wasi:http/incoming-handler` (via `wstd`)
- **`component-server` interfaces**: Exports `wasi:http/incoming-handler` (via `wstd`)

#### OCI Registry

A minimal [OCI Distribution Spec (v2)](https://github.com/opencontainers/distribution-spec/blob/main/spec.md) registry implemented as a single WASI P3 component. The registry API is served over the async `wasi:http/handler@0.3.0` export, and every blob, manifest, and tag is stored through the async, natively-streaming `wasmcloud:blobstore` interface — so the same component runs against any blobstore backend (in-memory, filesystem, NATS) without code changes. Spec-compliant as a drop-in target for clients like [`oras`](https://oras.land) and `docker`/`podman`: blob and manifest CRUD, resumable uploads, tag listing, and the referrers API. HTTP Basic auth is required on every request — including the `/v2/` version probe — with credentials read through `wasmcloud:secrets`, served by a [host component plugin](/docs/overview/hosts/plugins/); without a configured secrets backend, the registry denies all requests rather than serving unauthenticated.

- **Source**: [`wasmCloud/wasmCloud — examples/oci-registry`](https://github.com/wasmCloud/wasmCloud/tree/main/examples/oci-registry)
- **Interfaces**: Imports `wasmcloud:blobstore/{blobstore,container,types}@0.1.0`, `wasmcloud:secrets/{store,reveal}@2.1.0`, and `wasi:random/random@0.3.0`; exports `wasi:http/handler@0.3.0`

:::note[Build requirements]
This example depends on the async `wasmcloud:blobstore` host plugin (behind the `wasm_component_model_implements` feature) and WASI P3 component builds from the in-progress async-backends line of `wash` — a released `wash` (≤ 2.x) can't run it yet. See the [example README](https://github.com/wasmCloud/wasmCloud/tree/main/examples/oci-registry) for current build prerequisites. (At the time of writing, the README's feature notes lag the code — auth landed after it was written.)
:::

#### OpenTelemetry Config

A component instrumented with OpenTelemetry through the `wasi:otel` interfaces, with its OTel `Resource` (service name, environment, etc.) sourced from `wasi:config/store`. Each operation emits tracing, log, and metric data; the same component identifies itself differently per environment because `workload.config` and the OTel `Resource` are wired together at deploy time rather than at compile time.
Expand Down Expand Up @@ -387,3 +399,11 @@ An HTTP component that reads runtime configuration via the `wasi:config/store` i

- **Source**: [`wasmCloud/typescript — examples/components/wasi-config-from-k8s-env`](https://github.com/wasmCloud/typescript/tree/main/examples/components/wasi-config-from-k8s-env)
- **Interfaces**: Imports `wasi:config/store@0.2.0-rc.1`; exports `wasi:http/incoming-handler@0.2.6`

## Community projects: awesome-wasmcloud

Beyond the first-party templates and examples above, the community maintains [awesome-wasmcloud](https://github.com/wasmCloud/awesome-wasmcloud) — a collection of community-built **components**, **host plugins** (native and host component plugins), **workload examples**, and **tools**. Projects can be hosted directly in the repository or linked from their own repositories; each entry is tagged `(hosted)` or `(linked)`.

The first entry is [wasi-ai-app](https://github.com/bharattech/wasi-ai-app), a local AI meeting-notes pipeline built from three Rust components — a transcriber, a summarizer, and a web UI — that runs inference entirely on-device.

Have something to share? See the repository's [contributing guide](https://github.com/wasmCloud/awesome-wasmcloud/blob/main/CONTRIBUTING.md) to add your project. Note that community projects are maintained by their authors: inclusion is not an endorsement or security review, so read the code before running it.
Loading