See wasmCloud/wasmCloud#2230 for context.

Until we can support WASI providers, wasmCloud doesn't have the resources to provider language-specific SDKs for languages other than Rust (and Go, thanks to @jordan-rash). We should add a simple page to https://wasmcloud.com/docs/fundamentals/capabilities/create-provider/rust which makes this explicit, and describes how interested parties can "roll their own" providers in any language:

• accept HostData via stdin on startup
• subscribe to/emit RPC messages with appropriate Invocation and InvocationResponse payloads
• process link definitions
• respond to health checks
• shut down gracefully when instructed by the host

Note that the current page shares this list, but doesn't provide details on how to fulfill these requirements. I'm suggesting that list be moved to this new page and include the details on the "how."

Relevant structs we should point folks to for over-the-wire payloads: https://github.com/wasmCloud/wasmCloud/blob/main/crates/core/src/lib.rs#L110

It doesn't look like the reference documentation for the control topic has been updated since the release of wasmCloud 1.0:
https://wasmcloud.com/docs/hosts/lattice-protocols/control-interface#commands

These commands should ideally be generated, but for now the docs should be updated to reflect the current state.

Currently we have documentation in wadm about how to create an operator, account, and user credentials to use with both a lattice and wadm. This information actually would be better suited to our sections on running/operating wasmcloud and the wadm docs can just link to it

wasm-compose is a powerful tool for composing components at build-time, and we should have documentation on when to use wasm-compose and how to use it.

WebAssembly compositions (aka wac) is a declarative superset of WIT for describing how components compose together. We should have documentation on how to use this tool in addition to runtime linking over the lattice.

#405 partially addresses this

We use the <Tabs> and <Tab> components to sync the language selected by the user, however, this requires maintaining the same id everywhere the components are used. It would be helpful to be able to use a component that handles the props for us.

For example:

<LangTabs>
  <LangTab lang="rust">...</LangTab>
  <LangTab lang="go">...</LangTab>
  ...etc
</LangTabs>

Alternatively, each language could be a specific component. This would enable specific API for props (i.e. marking a RustTab as a component vs module, or marking a GoTab as the "tiny" or main syntax)

<LangTabs>
  <RustTab>...</RustTab>
  <GoTab>...</GoTab>
  ...etc
</LangTabs>

It would also be useful to not have to import these components every time they are used in an mdx file.

Having contributors open PRs has highlighted a couple of changes that should be updated to make life easier to accept changes.

• Add CONTRIBUTING.md
• Add eslint configuration with a baseline recommended configuration
• Add husky pre-commit hooks for
  • lint
  • format
• Add CI check for linting/formatting

It might be helpful for new users if we include in our onboarding instructions and docs syntax highlighting:

https://github.com/bytecodealliance/vscode-wit/

A user ran into an issue where their actor was failing to communicate with a provider. I noticed the provider was running with a custom link name and wanted to point them to documentation around using new_with_link when constructing a Sender in our Rust SDK, but couldn't find any documentation covering this. I'm not sure where the best home is for this information, but wanted to file it as a gap

As provider-wit-bindgen code matures and sees use, the user-facing documentation around creating (and debugging) creating providers needs to be updated.

At the very least the following things need to be considered:

• information around the arguments to wasmcloud_provider_wit_bindgen::generate!
• debugging steps (use of RUST_LOG)

The Installation docs mention the simple install process for Debian:

curl -s https://packagecloud.io/install/repositories/wasmcloud/core/script.deb.sh | sudo bash
sudo apt install wash openssl

But docs should include a link to inspect the script that is about to be run, which is doing quite a bit. There may be some bullet points on what the install does to your system.

"We are hosting all wasmCloud-related packages on https://packagecloud.io and this script will configure apt to access the package repository when using the wash command line utility."

The script.deb.sh script:

#!/bin/bash

unknown_os ()
{
  echo "Unfortunately, your operating system distribution and version are not supported by this script."
  echo
  echo "You can override the OS detection by setting os= and dist= prior to running this script."
  echo "You can find a list of supported OSes and distributions on our website: https://packagecloud.io/docs#os_distro_version"
  echo
  echo "For example, to force Ubuntu Trusty: os=ubuntu dist=trusty ./script.sh"
  echo
  echo "Please email [email protected] and let us know if you run into any issues."
  exit 1
}

gpg_check ()
{
  echo "Checking for gpg..."
  if command -v gpg > /dev/null; then
    echo "Detected gpg..."
  else
    echo "Installing gnupg for GPG verification..."
    apt-get install -y gnupg
    if [ "$?" -ne "0" ]; then
      echo "Unable to install GPG! Your base system has a problem; please check your default OS's package repositories because GPG should work."
      echo "Repository installation aborted."
      exit 1
    fi
  fi
}

curl_check ()
{
  echo "Checking for curl..."
  if command -v curl > /dev/null; then
    echo "Detected curl..."
  else
    echo "Installing curl..."
    apt-get install -q -y curl
    if [ "$?" -ne "0" ]; then
      echo "Unable to install curl! Your base system has a problem; please check your default OS's package repositories because curl should work."
      echo "Repository installation aborted."
      exit 1
    fi
  fi
}

install_debian_keyring ()
{
  if [ "${os,,}" = "debian" ]; then
    echo "Installing debian-archive-keyring which is needed for installing "
    echo "apt-transport-https on many Debian systems."
    apt-get install -y debian-archive-keyring &> /dev/null
  fi
}


detect_os ()
{
  if [[ ( -z "${os}" ) && ( -z "${dist}" ) ]]; then
    # some systems dont have lsb-release yet have the lsb_release binary and
    # vice-versa
    if [ -e /etc/lsb-release ]; then
      . /etc/lsb-release

      if [ "${ID}" = "raspbian" ]; then
        os=${ID}
        dist=`cut --delimiter='.' -f1 /etc/debian_version`
      else
        os=${DISTRIB_ID}
        dist=${DISTRIB_CODENAME}

        if [ -z "$dist" ]; then
          dist=${DISTRIB_RELEASE}
        fi
      fi

    elif [ `which lsb_release 2>/dev/null` ]; then
      dist=`lsb_release -c | cut -f2`
      os=`lsb_release -i | cut -f2 | awk '{ print tolower($1) }'`

    elif [ -e /etc/debian_version ]; then
      # some Debians have jessie/sid in their /etc/debian_version
      # while others have '6.0.7'
      os=`cat /etc/issue | head -1 | awk '{ print tolower($1) }'`
      if grep -q '/' /etc/debian_version; then
        dist=`cut --delimiter='/' -f1 /etc/debian_version`
      else
        dist=`cut --delimiter='.' -f1 /etc/debian_version`
      fi

    else
      unknown_os
    fi
  fi

  if [ -z "$dist" ]; then
    unknown_os
  fi

  # remove whitespace from OS and dist name
  os="${os// /}"
  dist="${dist// /}"

  echo "Detected operating system as $os/$dist."
}

detect_apt_version ()
{
  apt_version_full=`apt-get -v | head -1 | awk '{ print $2 }'`
  apt_version_major=`echo $apt_version_full | cut -d. -f1`
  apt_version_minor=`echo $apt_version_full | cut -d. -f2`
  apt_version_modified="${apt_version_major}${apt_version_minor}0"

  echo "Detected apt version as ${apt_version_full}"
}

main ()
{
  detect_os
  curl_check
  gpg_check
  detect_apt_version

  # Need to first run apt-get update so that apt-transport-https can be
  # installed
  echo -n "Running apt-get update... "
  apt-get update &> /dev/null
  echo "done."

  # Install the debian-archive-keyring package on debian systems so that
  # apt-transport-https can be installed next
  install_debian_keyring

  echo -n "Installing apt-transport-https... "
  apt-get install -y apt-transport-https &> /dev/null
  echo "done."


  gpg_key_url="https://packagecloud.io/wasmCloud/core/gpgkey"
  apt_config_url="https://packagecloud.io/install/repositories/wasmCloud/core/config_file.list?os=${os}&dist=${dist}&source=script"

  apt_source_path="/etc/apt/sources.list.d/wasmCloud_core.list"
  apt_keyrings_dir="/etc/apt/keyrings"
  if [ ! -d "$apt_keyrings_dir" ]; then
    mkdir -p "$apt_keyrings_dir"
  fi
  gpg_keyring_path="$apt_keyrings_dir/wasmCloud_core-archive-keyring.gpg"
    gpg_key_path_old="/etc/apt/trusted.gpg.d/wasmCloud_core.gpg"

  echo -n "Installing $apt_source_path..."

  # create an apt config file for this repository
  curl -sSf "${apt_config_url}" > $apt_source_path
  curl_exit_code=$?

  if [ "$curl_exit_code" = "22" ]; then
    echo
    echo
    echo -n "Unable to download repo config from: "
    echo "${apt_config_url}"
    echo
    echo "This usually happens if your operating system is not supported by "
    echo "packagecloud.io, or this script's OS detection failed."
    echo
    echo "You can override the OS detection by setting os= and dist= prior to running this script."
    echo "You can find a list of supported OSes and distributions on our website: https://packagecloud.io/docs#os_distro_version"
    echo
    echo "For example, to force Ubuntu Trusty: os=ubuntu dist=trusty ./script.sh"
    echo
    echo "If you are running a supported OS, please email [email protected] and report this."
    [ -e $apt_source_path ] && rm $apt_source_path
    exit 1
  elif [ "$curl_exit_code" = "35" -o "$curl_exit_code" = "60" ]; then
    echo "curl is unable to connect to packagecloud.io over TLS when running: "
    echo "    curl ${apt_config_url}"
    echo "This is usually due to one of two things:"
    echo
    echo " 1.) Missing CA root certificates (make sure the ca-certificates package is installed)"
    echo " 2.) An old version of libssl. Try upgrading libssl on your system to a more recent version"
    echo
    echo "Contact [email protected] with information about your system for help."
    [ -e $apt_source_path ] && rm $apt_source_path
    exit 1
  elif [ "$curl_exit_code" -gt "0" ]; then
    echo
    echo "Unable to run: "
    echo "    curl ${apt_config_url}"
    echo
    echo "Double check your curl installation and try again."
    [ -e $apt_source_path ] && rm $apt_source_path
    exit 1
  else
    echo "done."
  fi

  echo -n "Importing packagecloud gpg key... "
  # import the gpg key
  curl -fsSL "${gpg_key_url}" | gpg --dearmor > ${gpg_keyring_path}
  # grant 644 permisions to gpg keyring path
  chmod 0644 "${gpg_keyring_path}"

  # move gpg key to old path if apt version is older than 1.1
  if [ "${apt_version_modified}" -lt 110 ]; then
    # move to trusted.gpg.d

    mv ${gpg_keyring_path} ${gpg_key_path_old}
    # grant 644 permisions to gpg key path
    chmod 0644 "${gpg_key_path_old}"

    # deletes the keyrings directory if it is empty
    if ! ls -1qA $apt_keyrings_dir | grep -q .;then
      rm -r $apt_keyrings_dir
    fi
    echo "Packagecloud gpg key imported to ${gpg_key_path_old}"
  else
    echo "Packagecloud gpg key imported to ${gpg_keyring_path}"
  fi
  echo "done."

  echo -n "Running apt-get update... "
  # update apt on this system
  apt-get update &> /dev/null
  echo "done."

  echo
  echo "The repository is setup! You can now install packages."
}

main

wasmCloud/wadm#223 changed two of the status names. The documentation should be updated to reflect this.

We have a few architecture diagrams in the quickstart that should be reevaluated for relationships (how to represent the lattice vs host) and we have additional need on our concepts page for more diagrams for how things relate.

As a rule of thumb, if we're introducing a new concept, we should have a diagram showing how it all relates. Over the quickstart it could be helpful to have an evolving diagram with increasing complexity

NATS is a core part of our ability to run distributed Wasm components, and there's a few big pieces we should document and describe better for those looking to dive deeper.

• How queue subscriptions work
• The wRPC implementation for NATS
• Our use of NATS APIs (core NATS for pubsub RPC and ctl API, KV buckets / Jetstream for persistent storage)
• Supercluster pattern, with geo-affinity + leaf nodes
• Identity and authentication to a lattice with accounts and users
• Websocket connections

Basically once wasmCloud/wadm#252 merges and is released, we can remove the extraneous wash config puts in the docs.

There's a TODO on this page which can be TODONE once the next version of wash is released :)

1.0 document changed ENV vars.

For example this one still has LATTICE_PREFIX:
https://wasmcloud.com/docs/1.0/reference/host-config

I've created this here repo: ceejimus/learning-wasmcloud

The README should say it all. I'm hoping this can be used to help improve or supplement the existing getting-started docs. You could say I'm partial to hand-holding.

Any feedback appreciated!

I didn't feel qualified to write this in #259, but it's sorely needed!

But the wash README does: Nix install

there is a small typo in the first paragraph of the docs page https://wasmcloud.com/docs/tour/why-wasmcloud

From the 06-20 community call, we spoke extensively about the use of link names in wasmCloud to use logically named different links, potentially between the same two components. The search docs don't pull up a heading for this, so there must not be a piece under the linking at runtime docs that mention link names.

It would be great to have a few pages/headings including information about:

• What is an import/export
• When to use an import/export
• How to design a WIT interface (best practices)
• When to use/not use resources

This have not been updated for the latest 1.0 topics. Most data is still accurate, but we need to update the topics and remove old things we aren't using

https://wasmcloud.com/docs/reference/cloud-event-list contains some outdated information and should be updated to match the 1.0 events structures.

As a side note, it would be great for these events to be specified as a spec instead of the JSON examples in the repository

wash build will fail if the language toolchain isn't set up beforehand. We should include/link to instructions on how to get set up for building Rust and TinyGo actors

In the docs there's a link in a 🔥 Danger popout to the top-level wasm repo issues page. Should it link to this: wasmCloud/wadm#113 ?

I've got another branch for random docs updates on my fork so I could easily update this.

Now that wash call works again, we should document it among https://wasmcloud.com/docs/category/cli-wash

No e2e example of actor to actor communication.
The docs explain some of this but I'd like to see an example with all parts are included, when I current try to make actor talk to another actor via actorReceive: true flag in interface, I get the following error:

Host send error Guest call failed for method Rpc.Convert: method not handled Rpc.Convert - unknown method

Document that the wash new component command can also be used with a path to a template, a git URL for a template, or a favorites file with your templates.

We should document the difference between built-ins and external providers. Specifically the pros and cons.

• External providers may be updated at runtime independent of the host.
• External providers may scale independent of a host.
• Built-ins do not go over NATS and run in the same process as the host process.
• Updating a built-in requires a host update.

We basically need the equivalent of https://wasmcloud.com/docs/hosts/elixir/host_configure for the rust host

change the font size on the drop down

Including specific documentation for each first-party provider in the docs will make it easier for users to get started with those providers, and will give us a centralized spot to document them.

We could use some meatier examples for wasmCloud apps, e.g. full CRUD API examples like blobby, in showcases on the website that demonstrate "twelve factor wasmCloud apps"

After wasmCloud/wasmCloud#1890, we both no longer need to specify the websocket port AND it changed to 4223. Should be easy to accomplish to scan through docs for 4001.

This should be changed on the 1.0 documentation front as it remains 4001 for 0.82

0.5.0 implements manifest upgrades which should be used instead of undeploy/deploy

When it comes to debugging, it's important for developers to know where to look for issues. Under a debugging document we should have pointers to:

• Where log files exist
• How to debug (logging, printing to stderr)
• How to increase the verbosity of logging
• Common issues / FAQ (some of this exists already)
• How to use the NATS CLI to debug (subbing on topics for events, rpc, etc)

Docusaurus has released a new major version which includes support for React 18.

https://github.com/facebook/docusaurus/releases/tag/v3.0.0

They have released an upgrade guide, which is quite detailed. The biggest change—aside from React 18—is that it now uses MDX 3 instead of MDX 1. This may mean that some of the markdown content needs to be adjusted. Fortunately, the build will highlight issues pretty quickly.

It would be great to make this upgrade for the wasmCloud docs sooner rather than later. If someone from the community would like to create a PR, please comment and I'll assign the issue.

@jordan-rash wrote wash build docs over in the wash repo in wasmCloud/wash#529, we should add these to wasmcloud.com directly

It would be awesome for this repository to include a devcontainer with at the very least NPM installed so that developers can directly edit the site using the codebase and use npm run start to view the live changes in the site. Ideally we should also run npm i as a part of the devcontainer startup

We have one documentation page on our RPC/CTL connections https://wasmcloud.com/docs/deployment/security/nats, but it does not include examples on how to create a lattice with stronger security boundaries. As per wasmCloud/wasmCloud#1119, we depend on our NATS connection security to protect the lattice from bad actors.

We should offer recommendations and pointers to NATS documentation on how to set up a secure NATS server environment.