Skip to content

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:

Terminal window
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:

Terminal window
# 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:

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

The output shows the instance URL and other details:

Terminal window
[●] 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:

Terminal window
curl -i https://damp-bobo-wg43p36e.fra0.kraft.host/hello
Hello, Fermyon!

And curl the goodbye route:

Terminal window
curl -i https://damp-bobo-wg43p36e.fra0.kraft.host/goodbye
Goodbye, Fermyon!

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

Terminal window
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:

Terminal window
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
spec: v0.6
runtime: spin:latest
rootfs: ./Dockerfile
cmd: ["/usr/bin/spin", "up", "--from", "/app/spin.toml", "--listen", "0.0.0.0:3000"]

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:

Terminal window
kraft cloud --help

Or visit the CLI Reference.