Skip to main content

Building An Echo Service

Build and run your first wasmCloud actor

info

If you have not installed wash, follow the installation guide first.

In this guide, we'll be taking a tour through some of the most common activities in the wasmCloud ecosystem like starting and configuring actors and capability providers. You'll get to build your own actors and providers in upcoming tutorials, but for now let's get familiar with the runtime and tooling.

Starting a host

To start a host, simply run wash up.

By default, wash will run the host in interactive mode. If you'd rather run the host in the background, run wash up --detached (or wash up -d, for short).

Log files

If you encounter any problems, the host log files may contain useful error messages, and it's good to know how to find them. The tabs below, organized by how you started the wasmCloud host, show you where to find logs:

By default, logs from wash up are automatically output to your terminal. If you ran the command with the --detached flag, logs can be found in ~/.wash/downloads/wasmcloud.log

Viewing the wasmCloud dashboard

Open a browser tab to the URL http://localhost:4000. This is the wasmCloud dashboard (or washboard), a GUI that you will use quite often as you learn to build distributed applications in this ecosystem.

empty wasmCloud dashboard
info

By default, wasmCloud hosts connect to port 4000. If this port isn't available, you won't see the wasmCloud dashboard. If you need to change the port number, you can set the environment variable WASMCLOUD_DASHBOARD_PORT to a new number before starting a host.

Querying hosts with wash

Querying for running hosts

To see a list of running hosts, run the following command:

wash ctl get hosts

You'll see output like this:

⢈⠩  Retrieving Hosts ...

Host ID Uptime (seconds)
NCPGH5CVPO3BAZ5OSQKXYHDKPBT3JXLG5EAOTG7XOXUWJ6AHZCFT57SI 711

Querying a host's inventory

Now let's check the host's inventory. Using your host ID (not the one in this guide):

wash ctl get inventory NCPGH5CVPO3BAZ5OSQKXYHDKPBT3JXLG5EAOTG7XOXUWJ6AHZCFT57SI

You'll see output similar to the following (your host ID will be different):

 Host Inventory (NCPGH5CVPO3BAZ5OSQKXYHDKPBT3JXLG5EAOTG7XOXUWJ6AHZCFT57SI)

hostcore.os linux
hostcore.osfamily unix
hostcore.arch x86_64

No actors found

No providers found

The start of the output displays a host's labels. By default, this includes the operating system and architecture the host is running on. These labels are prefixed by hostcore.

The rest of the inventory includes a list of actors and capability providers. Since we haven't started any actors or providers, these lists are empty.

The terminal output you've seen so far is also reflected in the dashboard. Throughout our guides and tutorials, we may alternate between the wasmCloud dashboard UI and terminal-based CLI. When it comes to managing a host's inventory, everything you can do in one view, you can do in the other.

Running an actor

We'll return to the dashboard UI now. (If you're interested in doing this with wash, refer to this page). From the dashboard, click the Start Actor button and choose the From Registry option. When prompted for an OCI reference URL, enter wasmcloud.azurecr.io/echo:0.3.8. For now, choose 1 for the number of replicas:

Starting an actor modal

Click Submit, and after a few seconds, you should have a running actor on your host:

Running echo actor

Running a capability provider

For this actor to receive HTTP requests, we need to start the HTTP Server capability provider. Actors are signed WebAssembly modules, and as such they have embedded claims declaring their ability to communicate with capability providers like the HTTP Server. Actors cannot communicate with any capability provider for which they have not been signed.

Let's use wash to inspect the set of capabilities this actor has:

wash claims inspect wasmcloud.azurecr.io/echo:0.3.8
                               Echo - Module
Account ACOJJN6WUP4ODD75XEBKKTCCUJJCY5ZKQ56XVKYK4BEJWGVAOOQHZMCW
Module MBCFOPM6JW2APJLXJD3Z5O4CN7CPYJ2B4FTKLJUR5YR5MITIU7HD3WD5
Expires never
Can Be Used immediately
Version 0.3.8 (4)
Call Alias (Not set)
Capabilities
HTTP Server
Logging
Tags
None

To start the HTTP server capability provider, click Start Provider and then select From Registry. Supply the OCI URL wasmcloud.azurecr.io/httpserver:0.17.0 and leave the link name set to default. You should now see this capability provider running, and within 30 seconds it should report its status as Healthy.

Running HTTP server

Let's return to wash now and re-query the host's inventory. Re-run the command wash ctl get inventory. You should see something like the following (again, your Host ID will be different):

Host Inventory (NCPGH5CVPO3BAZ5OSQKXYHDKPBT3JXLG5EAOTG7XOXUWJ6AHZCFT57SI)

hostcore.osfamily unix
hostcore.os macos
hostcore.arch aarch64

Actor ID Name Image Reference
MBCFOPM6JW2APJLXJD3Z5O4CN7CPYJ2B4FTKLJUR5YR5MITIU7HD3WD5 Echo wasmcloud.azurecr.io/echo:0.3.8

Provider ID Name Link Name Image Reference
VAG3QITQQ2ODAOWB5TTQSDJ53XK3SHBEIFNK4AYJ5RKAX2UNSCAPHA5M HTTP Server default wasmcloud.azurecr.io/httpserver:0.17.0

Linking actors and capability providers

Since the HTTP server provider hasn't been linked to any actor yet, it hasn't yet opened a port to listen to web requests to forward to the actor. To allow the actor and provider to communicate, they need to be linked.

Go back to the web UI and click Define Link. Select the actor and provider from the dropdown boxes, as shown below. Leave the Link Name as default, and set the Contract ID to wasmcloud:httpserver. For the Values field, you'll need to provide an address including hostname and port. Enter the following in the Values field:

address=0.0.0.0:8080
Link definition modal

Once you see that the link has been added to the dashboard, you are ready to send a request to your actor.

Interacting with your actor

In another terminal window, run the following command:

curl localhost:8080/echo

In response, you should receive your request object (notice the path argument):

{"body":[],"method":"GET","path":"/echo","query_string":""}

Feel free to try out different methods of making a request to your actor, including adding headers or using a different HTTP method, to see different outputs.

Congratulations! You've made it through the first guide to wasmCloud. You should now feel comfortable exploring the ecosystem, starting and stopping the host runtime, interacting with the wasmCloud dashboard UI, and interacting with hosts using wash.

To learn more about actors, providers, and other topics, continue on to the Fundamentals section.