Installation
First, we'll install wash
, the WAsmcloud SHell, which we'll use to
install, run, and manage our wasmCloud components.
Select your preferred installation method below, then run the displayed commands in your favorite terminal.
- Ubuntu/Debian
- Fedora
- MacOS
- Windows
- Rust
- Source
- Docker Compose
curl -s https://packagecloud.io/install/repositories/wasmcloud/core/script.deb.sh | sudo bash
sudo apt install wash
Details
What's in that install script?
It is always a good idea to inspect scripts before piping them directly intosudo bash
.Below are the contents of script.deb.sh
for your verification.
#!/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 support@packagecloud.io 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 support@packagecloud.io 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 support@packagecloud.io 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
curl -s https://packagecloud.io/install/repositories/wasmcloud/core/script.rpm.sh | sudo bash
sudo dnf install wash
Details
What's in that install script?
It is always a good idea to inspect scripts before piping them directly intosudo bash
. Below are the contents of script.rpm.sh
for your verification.#!/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 CentOS 6: os=el dist=6 ./script.sh"
echo
echo "Please email support@packagecloud.io and let us know if you run into any issues."
exit 1
}
curl_check ()
{
echo "Checking for curl..."
if command -v curl > /dev/null; then
echo "Detected curl..."
else
echo "Installing curl..."
yum install -d0 -e0 -y curl
fi
}
detect_os ()
{
if [[ ( -z "${os}" ) && ( -z "${dist}" ) ]]; then
if [ -e /etc/os-release ]; then
. /etc/os-release
os=${ID}
if [ "${os}" = "poky" ]; then
dist=`echo ${VERSION_ID}`
elif [ "${os}" = "sles" ]; then
dist=`echo ${VERSION_ID}`
elif [ "${os}" = "opensuse" ]; then
dist=`echo ${VERSION_ID}`
elif [ "${os}" = "opensuse-leap" ]; then
os=opensuse
dist=`echo ${VERSION_ID}`
elif [ "${os}" = "amzn" ]; then
dist=`echo ${VERSION_ID}`
else
dist=`echo ${VERSION_ID} | awk -F '.' '{ print $1 }'`
fi
elif [ `which lsb_release 2>/dev/null` ]; then
# get major version (e.g. '5' or '6')
dist=`lsb_release -r | cut -f2 | awk -F '.' '{ print $1 }'`
# get os (e.g. 'centos', 'redhatenterpriseserver', etc)
os=`lsb_release -i | cut -f2 | awk '{ print tolower($1) }'`
elif [ -e /etc/oracle-release ]; then
dist=`cut -f5 --delimiter=' ' /etc/oracle-release | awk -F '.' '{ print $1 }'`
os='ol'
elif [ -e /etc/fedora-release ]; then
dist=`cut -f3 --delimiter=' ' /etc/fedora-release`
os='fedora'
elif [ -e /etc/redhat-release ]; then
os_hint=`cat /etc/redhat-release | awk '{ print tolower($1) }'`
if [ "${os_hint}" = "centos" ]; then
dist=`cat /etc/redhat-release | awk '{ print $3 }' | awk -F '.' '{ print $1 }'`
os='centos'
elif [ "${os_hint}" = "scientific" ]; then
dist=`cat /etc/redhat-release | awk '{ print $4 }' | awk -F '.' '{ print $1 }'`
os='scientific'
else
dist=`cat /etc/redhat-release | awk '{ print tolower($7) }' | cut -f1 --delimiter='.'`
os='redhatenterpriseserver'
fi
else
aws=`grep -q Amazon /etc/issue`
if [ "$?" = "0" ]; then
dist='6'
os='aws'
else
unknown_os
fi
fi
fi
if [[ ( -z "${os}" ) || ( -z "${dist}" ) ]]; then
unknown_os
fi
# remove whitespace from OS and dist name
os="${os// /}"
dist="${dist// /}"
echo "Detected operating system as ${os}/${dist}."
if [[ "$os" = "ol" || "$os" = "el" ]] && [ $(($dist)) \> 7 ]; then
_skip_pygpgme=1
else
_skip_pygpgme=0
fi
}
finalize_yum_repo ()
{
if [ "$_skip_pygpgme" = 0 ]; then
echo "Installing pygpgme to verify GPG signatures..."
yum install -y pygpgme --disablerepo="${repo_config_name}"
pypgpme_check=`rpm -qa | grep -qw pygpgme`
if [ "$?" != "0" ]; then
echo
echo "WARNING: "
echo "The pygpgme package could not be installed. This means GPG verification is not possible for any RPM installed on your system. "
echo "To fix this, add a repository with pygpgme. Usualy, the EPEL repository for your system will have this. "
echo "More information: https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F"
echo
# set the repo_gpgcheck option to 0
sed -i'' 's/repo_gpgcheck=1/repo_gpgcheck=0/' /etc/yum.repos.d/$repo_config_name.repo
fi
fi
echo "Installing yum-utils..."
yum install -y yum-utils --disablerepo="${repo_config_name}"
yum_utils_check=`rpm -qa | grep -qw yum-utils`
if [ "$?" != "0" ]; then
echo
echo "WARNING: "
echo "The yum-utils package could not be installed. This means you may not be able to install source RPMs or use other yum features."
echo
fi
echo "Generating yum cache for ${repo_config_name}..."
yum -q makecache -y --disablerepo='*' --enablerepo="${repo_config_name}"
echo "Generating yum cache for ${repo_config_name}-source..."
yum -q makecache -y --disablerepo='*' --enablerepo="${repo_config_name}-source"
}
finalize_zypper_repo ()
{
zypper --gpg-auto-import-keys refresh $repo_config_name
zypper --gpg-auto-import-keys refresh $repo_config_name-source
}
main ()
{
repo_config_name=wasmCloud_core
detect_os
curl_check
yum_repo_config_url="https://packagecloud.io/install/repositories/wasmCloud/core/config_file.repo?os=${os}&dist=${dist}&source=script"
if [ "${os}" = "sles" ] || [ "${os}" = "opensuse" ]; then
yum_repo_path=/etc/zypp/repos.d/$repo_config_name.repo
else
yum_repo_path=/etc/yum.repos.d/$repo_config_name.repo
fi
echo "Downloading repository file: ${yum_repo_config_url}"
curl -sSf "${yum_repo_config_url}" > $yum_repo_path
curl_exit_code=$?
if [ "$curl_exit_code" = "22" ]; then
echo
echo
echo -n "Unable to download repo config from: "
echo "${yum_repo_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 CentOS 6: os=el dist=6 ./script.sh"
echo
echo "If you are running a supported OS, please email support@packagecloud.io and report this."
[ -e $yum_repo_path ] && rm $yum_repo_path
exit 1
elif [ "$curl_exit_code" = "35" -o "$curl_exit_code" = "60" ]; then
echo
echo "curl is unable to connect to packagecloud.io over TLS when running: "
echo " curl ${yum_repo_config_url}"
echo
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 support@packagecloud.io with information about your system for help."
[ -e $yum_repo_path ] && rm $yum_repo_path
exit 1
elif [ "$curl_exit_code" -gt "0" ]; then
echo
echo "Unable to run: "
echo " curl ${yum_repo_config_url}"
echo
echo "Double check your curl installation and try again."
[ -e $yum_repo_path ] && rm $yum_repo_path
exit 1
else
echo "done."
fi
if [ "${os}" = "sles" ] || [ "${os}" = "opensuse" ]; then
finalize_zypper_repo
else
finalize_yum_repo
fi
echo
echo "The repository is setup! You can now install packages."
}
main
brew install wasmcloud/wasmcloud/wash
For the smoothest experience, we recommend that Windows users run wasmCloud with Windows Subsystem for Linux (WSL) and follow the Ubuntu/Debian instructions throughout the documentation.
Microsoft provides documentation for getting started with WSL and using WSL with Visual Studio Code.
When using WSL, we recommend choosing the Ubuntu
distro (wsl --install -d Ubuntu
).
You may need to update git
to the latest version using the Ubuntu Git Maintainers' Personal Package Archive (PPA):
sudo add-apt-repository ppa:git-core/ppa
sudo apt-get update
sudo apt-get install git
When your WSL environment is ready, you can use the standard Ubuntu/Debian installation method:
curl -s https://packagecloud.io/install/repositories/wasmcloud/core/script.deb.sh | sudo bash
sudo apt install wash
If you are unable to use WSL, you can use the native binary installation below, but note that native Windows support is experimental.
choco install wash
If you're using the native Windows binary, you can install wasmCloud's supported language toolchains on Windows as follows:
Go toolchain
On Windows, you can use Scoop to install the Go toolchain (as well as the binaryen
tool to compile components on Windows):
scoop install go
scoop install tinygo@0.33.0
scoop install binaryen
Rust toolchain
On Windows, you can use Chocolatey to install rustup
, and then use rustup
to install the Windows toolchain:
choco install rustup.install
rustup toolchain install stable-msvc
Note: On Windows, you will also need Visual Studio's C++ tools.
Once you've installed Rust, use rustup
to add the wasm32-wasip2
target:
rustup target add wasm32-wasip2
TypeScript toolchain
On Windows, you can use Chocolatey to install npm
(and Node.js):
choco install nodejs
If your platform isn't listed, wash
can be installed with cargo
and a Rust toolchain.
cargo install --locked wash-cli
If you have cargo-binstall
installed, you can install even faster:
cargo binstall wash-cli
The wash project is open-source and can be cloned from GitHub and built locally with a Rust toolchain.
git clone https://github.com/wasmCloud/wasmCloud.git
cd wasmCloud/crates/wash-cli
cargo build --release
cd ../..
./target/release/wash
You'll also want to add wash
to your PATH
to easily run it. Refer to instructions specific to
your operating system for how to do this.
If you only use Docker Compose without installing wash
, you'll only be able to interact with
wasmCloud via the washboard.
Download the sample Docker Compose file and put it into your work directory. This compose file will run NATS, a local OCI registry, Grafana and Tempo for OTEL, and the wasmcloud_host
container. In this format it's easy to run all the necessary services for a wasmCloud host with only a docker installation.
With the docker-compose.yml
file in the current directory, start the processes with
docker compose up
The host will run until you type Ctrl-C or close the terminal window. To start the docker compose process in the background, add a -d
flag:
docker compose up -d
If the wasmCloud host is running in Docker in the background, you can view its logs (live) with
docker logs -f wasmcloud
Verify that wash
is properly installed with:
wash --help
If wash is installed correctly, you will see a printout of all available commands and short descriptions for each.
If you ever need more detail on a specific command or sub-command just run wash <command> --help
.
Now that wash
is installed, let's get started.