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:

Wash Up

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

Docker

Logs from hosts running in Docker, if started with our docker compose, can be found by running docker logs wasmcloud

Manual

If you manually installed the host from a downloaded release, look in var/log/erlang.log.1 relative to the folder where you extracted the release tar file.

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.

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:

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

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.

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

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.