Developer 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 Actors

The most common thing application developers will do is build actors. Actors encompass pure business logic, 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 an actor looks something like this:

1. Make code changes
2. Compile and sign the WebAssembly module, creating a _s.wasm file (using wash build in an actor project)
3. Test the module
   1. In the CLI
      1. Use the wash dev command to automatically watch actor files for changes
      2. Script wash call commands to invoke the actor
      3. Modify your actor code, run wash build to recompile and re-sign the actor, repeat the above step
   2. Leverage the wasmcloud:testing interface and the test provider
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 actor section for more details on how to use it.

Building Providers

The workflow for building a capability provider is similar to that of building an actor. 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

Creating new interfaces

Creating a new wasmCloud interface is probably the least commonly performed task, as generating new abstractions happens far less often than either consuming or providing that abstraction. Once you've created the scaffolding for a new interface library (which is available as a wash new command), the iteration loop looks something like this:

1. Make changes to the Smithy model (.smithy file)
2. Check it with wash lint and wash validate
3. Build it (make or cargo build, if it has Rust code)
4. Test the library

When the library is ready to release, it can be published. For example, interfaces made with our Rust SDK can be published to crates.io.

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 actors and capability providers to the registry using wash push. For example:

bash

wash push localhost:5000/myactor:0.1.0 ./build/my_actor_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 refactoring 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.