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.
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:
- Make code changes
- Compile and sign the WebAssembly module, creating a
wash buildin an actor project)
- Test the module
- In the CLI
- Use the
wash devcommand to automatically watch actor files for changes
wash callcommands to invoke the actor
- Modify your actor code, run
wash buildto recompile and re-sign the actor, repeat the above step
- Use the
- Leverage the
wasmcloud:testinginterface and the test provider
- In the CLI
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.
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:
- Make code changes
- Execute tests (
- Compile native executable binary
- Create and sign JWT
- Embed JWT and executable in a
.par.gz(provider archive) file. (Steps 3-5 can be done with the single command
makeusing the generated project Makefiles).
.PARfile to local or remote OCI registry (
- Test/Utilize the provider in the context of a host/lattice
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:
- Make changes to the Smithy model (
- Check it with
- Build it (
cargo build, if it has Rust code)
- 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
docker compose up -d registry
Once it's running, you can push actors and capability providers to the registry using
wash push. For example:
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
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.