Skip to main content
Version: 1.0

Workflows

As a developer using wasmCloud, there are a number of common day-to-day workflows that you will experience.

The following is a list of developer workflows sorted from most to least common.

Building Components​

The most common thing application developers will do is build components. Components encompass pure business logic in wasmCloud, and only communicate with non-functional requirements through capability providers and abstract interfaces.

Once you've established a dependency on a library that exposes the interface abstraction you're looking for, you can start your iteration loop.

The developer's iteration loop for building a component looks something like this:

  1. Make code changes
  2. Compile and sign the WebAssembly module, creating a _s.wasm file (using wash build in a component project)
  3. Test the module
    1. In the CLI
      1. Use the wash dev command to automatically watch component files for changes
      2. Script wash call commands to invoke the component
      3. Modify your component code, run wash build to recompile and re-sign the component, repeat the above step
  4. Repeat

As of wash 0.18.0, there is now a wash dev command that automates this process for you. See the Customizing the component section for more details on how to use it.

Building Providers​

The workflow for building a capability provider is similar to that of building a component. Once you've located and declared a dependency on the interface implemented by your capability provider, the iteration loop looks something like this:

  1. Make code changes
  2. Execute tests (make test)
  3. Compile native executable binary
  4. Create and sign JWT
  5. Embed JWT and executable in a .par.gz (provider archive) file. (Steps 3-5 can be done with the single command make using the generated project Makefiles).
  6. Publish .PAR file to local or remote OCI registry (make push)
  7. Test/Utilize the provider in the context of a host/lattice
  8. Repeat

Running a local OCI registry​

While it isn't called out as a specific pre-requisite, many of the steps in the developer iteration loops involve interacting with an OCI registry. Unless you've got a public one that you can use, you'll likely want to use a local one for testing.

To start a local OCI registry, download the sample Docker Compose file into the current folder and run

bash
docker compose up -d registry

Once it's running, you can push components and capability providers to the registry using wash push. For example:

bash
wash push localhost:5000/my component:0.1.0 ./build/my_ component_s.wasm
wash push localhost:5000/myprovider:0.1.0 ./build/my_provider.par.gz
info

Previous guides used wash reg push, which is now deprecated and will be removed in a future version. See the wash command ref componenting RFC for more information and to provide feedback

Allowing unauthenticated OCI registry access​

The wasmCloud host runtime will, by default, require that all OCI references use authentication in order to resolve and download. This is a security measure that is enabled by default to keep the system as secure as possible.

However, if you're running the local docker-supplied registry with its default settings, that registry will not have any authentication requirements. If you want your wasmCloud host to be able to talk to this registry, you'll need to enable unauthenticated OCI registry access.

This can be done by setting the environment variable WASMCLOUD_OCI_ALLOWED_INSECURE to include the URL of your local registry, e.g. localhost:5000. You can either supply this as an environment variable directly when you start a local wasmCloud host via iex or the release binary, or you can modify your shell profile to always set this variable on your development workstation.

Purging the OCI cache​

The wasmCloud host runtime caches the files that it receives from OCI registries beneath whatever temp directory your operating system prefers. Because images in an OCI registry are supposed to be immutable (another reason we recommend against using latest when requesting an image version), the wasmCloud host has no reason to automatically purge or overwrite these files in the cache.

During your local development iterations, you will likely find yourself pushing the same file with the same OCI reference over and over again. In order for the wasmCloud host to see these changes, you'll need to drain the wasmCloud host cache. This can be done by executing one of the variants of wash drain, such as wash drain all.