Hello World

A familiar starting example to get you up and running with wasmCloud.

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 the two main components of wasmCloud: actors and capability providers. All wasmCloud applications need a host to run on, so let's use wash to start one now.

Starting a Host

To start a host, simply run wash up. The default settings should work well for this tutorial. The host can be killed at any time with CTRL+c

This command does a lot behind the scenes, but most importantly it spins up 3 core processes:

• the wasmCloud host which manages the execution of actors and capability providers
• a NATS server to manage communications between application components
• a wadm process which monitors the lattice and maintains the state of managed deployments

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).

Generating a New Project

Now that our wasmCloud host is running, let's generate a new actor project. This is where our "Hello World" example begins. If you're running your host in the foreground, just switch to another terminal window to run these commands.

This command generates a new actor project in the ./hello directory:

wash new actor -t hello hello

This actor is a simple Rust project with a few extra goodies included for wasmCloud. At a high level, the important pieces are:

1. src/lib.rs: Where the business logic is implemented
2. wasmcloud.toml: Actor metadata and capability permissions
3. wadm.yaml: A declarative manifest for running the full application

We'll take a look at each of these in depth later, but for now let's run the example.

Starting our Application

We'll use wash and wadm, the wasmCloud application deployment manager, to start this actor, the httpserver capability, and link them together to configure them.

wash app deploy wadm.yaml

wadm will take care of taking this manifest and scheduling the resources on the host that you launched earlier. You should see output in the host logs when your actor and capability start up, and then you can query it yourself:

$ curl localhost:8080
Hello, world!

Congratulations, you just ran a WebAssembly application in wasmCloud!

How does it work?

When you send your HTTP request to localhost:8080, that request is received by the HTTP Server capability provider. The HTTP Server capability provider then forwards that request to the actor, which responds with the string "Hello, world!". This loose coupling of capability providers and actors provides flexibility, security, and it lets our actor code be loosely coupled to non-functional requirements. Let's take a look at that code now in src/lib.rs:

use wasmbus_rpc::actor::prelude::*;
use wasmcloud_interface_httpserver::{HttpRequest, HttpResponse, HttpServer, HttpServerReceiver};

#[derive(Debug, Default, Actor, HealthResponder)]
#[services(Actor, HttpServer)]
struct HelloActor {}

/// Implementation of the HttpServer capability contract
#[async_trait]
impl HttpServer for HelloActor {
    async fn handle_request(&self, _ctx: &Context, _req: &HttpRequest) -> RpcResult<HttpResponse> {
        Ok(HttpResponse::ok("Hello, World!"))
    }
}

This actor is set up to receive requests from the HttpServer capability, with a single function handle_request that matches what the capability provider expects. All you need to worry about as an applicaiton developer is what functional logic you want to apply when you receive an HttpRequest, and what HttpResponse you want to return. There's no mention of ports, certificates, HTTP libraries, and if those things change this actor will work all the same.

info

Capabilities are deny by default, and if you take a look in wasmcloud.toml you'll see the only capability is wasmcloud:httpserver. This means that this actor can never access files on disk, make network requests of its own, or even access the system time, it's blocked by the wasmCloud runtime.

When you ran wash app deploy wadm.yaml, wadm takes the application manifest and schedules the components on hosts according to the scale you specify. This example has a minimal manifest, let's take a look at it:

# Metadata
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: hello
  annotations:
    version: v0.0.1
    description: "wasmCloud Hello World Example"
spec:
  components:
    # Your actor component, started from the wasmCloud example OCI artifact
    - name: hello
      type: actor
      properties:
        image: wasmcloud.azurecr.io/hello:0.1.7
      traits:
        # One replica of this actor will run
        - type: spreadscaler
          properties:
            replicas: 1
        # The link configuration tells the httpserver to listen on 8080
        - type: linkdef
          properties:
            target: httpserver
            values:
              address: 0.0.0.0:8080

    # The httpserver capability provider, started from the official wasmCloud OCI artifact
    - name: httpserver
      type: capability
      properties:
        image: wasmcloud.azurecr.io/httpserver:0.17.0
        contract: wasmcloud:httpserver

Scaling up 📈

WebAssembly can be easily scaled due to its small size, portability, and wasmtime's ability to efficiently instantiate multiple instances of a single WebAssembly module. We leverage these aspects to make it simple to scale your applications with wasmCloud. Let's scale up our hello world application to 50 replicas by editing wadm.yaml:

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: hello
  annotations:
    # Make sure to bump the version so wadm knows to update the application
    version: v0.0.2
    description: "wasmCloud Hello World Example"
spec:
  components:
    - name: hello
      type: actor
      properties:
        image: wasmcloud.azurecr.io/hello:0.1.7
      traits:
        - type: spreadscaler
          properties:
            # Update the scale to 50
            replicas: 50

Now your hello application is ready to deploy v0.0.2 with 50 replicas. Just run wash app deploy wadm.yaml again, and you'll see the logs start flowing in. It's a little easier to visualize this in the wasmCloud dashboard, so let's take a look at that next.

Viewing the wasmCloud dashboard (experimental)

To view the wasmCloud dashboard, you'll have to launch wash with the option --nats-websocket-port 4001. This is currently an experimental command because the dashboard is still in rapid development. Go ahead and CTRL+c or wash down to stop your previous host, and then relaunch it with the new option:

wash up --nats-websocket-port 4001

Then, you can launch the wasmCloud dashboard using wash ui --experimental, which will launch the dashboard on http://localhost:3030. This is a great way to visualize what is running on your host, even multiple hosts that are connected to the same NATS server.

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

Next steps

Congratulations! You've made it through the first guide to wasmCloud. You started your first application and got familiar with the fundamentals of wash, wadm, and the wasmCloud dashboard. You should now feel comfortable exploring the ecosystem. We recommend proceeding onto the next guide, where you can build your own application and get into the developer loop.