Run a Spin app

In this guide we create and deploy a simple Spin HTTP app. This guide is derived from Spin’s spin-wagi-http example and shows how to run a Spin application serving routes from two programs written in different languages (Rust and C++) using both the Spin executor and the Wagi executor on Unikraft Cloud. To run it, follow these steps:

1. Install the kraft CLI tool and a container runtime engine, e.g. Docker.

2. Clone the examples repository and cd into the examples/spin-wagi-http/ directory:

git clone https://github.com/kraftcloud/examples
cd examples/spin-wagi-http/

Make sure to log into Unikraft Cloud by setting your token and a metro close to you. We use fra0 (Frankfurt, 🇩🇪) in this guide:

# Set Unikraft Cloud access token
export UKC_TOKEN=token
# Set metro to Frankfurt, DE
export UKC_METRO=fra0

When done, invoke the following command to deploy this application on Unikraft Cloud:

kraft cloud deploy -p 443:3000 -M 2048 .

The output shows the instance URL and other details:

[●] Deployed successfully!
 │
 ├────────── name: spin-wagi-http-is72r
 ├────────── uuid: 045c1bda-0f2e-4f8b-98c7-a208bfa7d143
 ├───────── state: running
 ├─────────── url: https://damp-bobo-wg43p36e.fra0.kraft.host
 ├───────── image: spin-wagi-http@sha256:57a5151996d83332af6da521e1cd92271a8c3ac7ae26bc44a7c0dbbc0a30e577
 ├───── boot time: 300.06 ms
 ├──────── memory: 2048 MiB
 ├─────── service: damp-bobo-wg43p36e
 ├── private fqdn: spin-wagi-http-is72r.internal
 ├──── private ip: 172.16.28.16
 └────────── args: /usr/bin/spin up --from /app/spin.toml --listen 0.0.0.0:3000

In this case, the instance name is spin-wagi-http-is72r and the URL is https://damp-bobo-wg43p36e.fra0.kraft.host. They are different for each run.

Then curl the hello route:

curl -i https://damp-bobo-wg43p36e.fra0.kraft.host/hello

Hello, Fermyon!

And curl the goodbye route:

curl -i https://damp-bobo-wg43p36e.fra0.kraft.host/goodbye

Goodbye, Fermyon!

At any point in time, you can list information about the instance:

kraft cloud instance list

NAME                  FQDN                                   STATE    CREATED AT    IMAGE                   MEMORY   ARGS                                      BOOT TIME
spin-wagi-http-is72r  damp-bobo-wg43p36e.fra0.kraft.host    running  1 minute ago  spin-wagi-http@sha2...  2.0 GiB  /usr/bin/spin up --from /app/spin.tom...  300064us

When done, you can remove the instance:

kraft cloud instance remove spin-wagi-http-is72r

Customize your Application

To customize the application, update the files in the repository, listed below:

• wagi-http-cpp: C++ server handling the hello route
• http-rust: Rust server handling the goodbye route
• Kraftfile: the Unikraft Cloud specification
• Dockerfile: the Docker-specified application filesystem
• spin.toml: The Spin TOML configuration file

Kraftfile

spec: v0.6

runtime: spin:latest

rootfs: ./Dockerfile

cmd: ["/usr/bin/spin", "up", "--from", "/app/spin.toml", "--listen", "0.0.0.0:3000"]

Dockerfile

FROM rust:1.75.0-bookworm AS spin

ARG SPIN_VERSION=2.1.0

WORKDIR /spin

RUN set -xe; \
apt-get update; \
apt-get install -y --no-install-recommends \
  ca-certificates \
  make \
  wget;

RUN set -xe; \
wget -q -O spin.tar.gz "https://github.com/fermyon/spin/releases/download/v${SPIN_VERSION}/spin-v${SPIN_VERSION}-linux-amd64.tar.gz"; \
tar xzvf ./spin.tar.gz; \
mv ./spin /usr/bin/spin; \
rm -rf spin.tar.gz; \
rustup target add wasm32-wasi

ARG WASI_SDK_VERSION=21

WORKDIR /wasi

RUN set -xe; \
wget -q -O wasi-sdk.tar.gz "https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-${WASI_SDK_VERSION}/wasi-sdk-${WASI_SDK_VERSION}.0-linux.tar.gz"; \
mkdir -p /opt/wasi-sdk; \
tar xzvf ./wasi-sdk.tar.gz --strip-components 1 -C /opt/wasi-sdk/; \
rm -rf ./wasi-sdk.tar.gz;

FROM spin AS build

COPY ./http-rust /app/http-rust
WORKDIR /app/http-rust
RUN cargo build --release

COPY ./wagi-http-cpp /app/wagi-http-cpp
WORKDIR /app/wagi-http-cpp
RUN make build

FROM scratch

COPY --from=build /app /app
COPY ./spin.toml /app/spin.toml

spin.toml

spin_manifest_version = 2

[application]
description = "A hello world application that serves content from a C++ program and a Rust program"
name = "spin-wagi-hello"
version = "1.0.0"

[[trigger.http]]
route = "/hello"
component = "hello"
executor = { type = "wagi" } # _start (the default entrypoint) is automatically mapped to main()

[[trigger.http]]
route = "/goodbye"
component = "goodbye"
executor = { type = "http" }

[component.hello]
source = "wagi-http-cpp/main.wasm"
[component.hello.build]
command = "make build -C wagi-http-cpp"

[component.goodbye]
source = "http-rust/target/wasm32-wasi/release/goodbyerust.wasm"
[component.goodbye.build]
command = "cargo build --target wasm32-wasi --release --manifest-path http-rust/Cargo.toml"

Lines in the Kraftfile have the following roles:

• spec: v0.6: The current Kraftfile specification version is 0.6.

• runtime: spin:latest: The Unikraft runtime kernel to use is Spin.

• rootfs: ./Dockerfile: Build the application root filesystem using the Dockerfile.

• cmd: ["/usr/bin/spin", "up", "--from", "/app/spin.toml", "--listen", "0.0.0.0:3000"]: Use spin as the command to start the app, with the given parameters.

The following options are available for customizing the application:

• If only updating the existing files under the wagi-http-cpp and http-rust directories, no other change is required.

• If new files are added, these have to be copied in the application filesystem, using the COPY command in the Dockerfile.

• More extensive changes may require expanding the Dockerfile with additional Dockerfile commands.

Learn More

Use the --help option for detailed information on using Unikraft Cloud:

kraft cloud --help

Or visit the CLI Reference.