Spin

https://github.com/spinframework/spin
Admin
Spin is an open source framework for building and running fast, secure, and composable cloud...
Tokens:41,960
Snippets:570
Trust Score:-
License:Apache-2.0
Update:6 months ago
Show doc for...
Tokens:
Raw
### Download and Install WASI SDK

Source: https://github.com/spinframework/spin/blob/main/examples/http-cpp/README.md

Installs the WASI SDK, a prerequisite for building WebAssembly components.

```bash
curl -OL https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-14/wasi-sdk-14.0-linux.tar.gz
tar xf wasi-sdk-14.0-linux.tar.gz
sudo mv wasi-sdk-14.0 /opt/wasi-sdk
```

--------------------------------

### Install wit-bindgen CLI

Source: https://github.com/spinframework/spin/blob/main/examples/http-cpp/README.md

Installs the wit-bindgen-cli tool, necessary for generating bindings for Spin components.

```bash
cargo install --git https://github.com/bytecodealliance/wit-bindgen --rev cb871cfa1ee460b51eb1d144b175b9aab9c50aba wit-bindgen-cli
```

--------------------------------

### Install Spin Templates from Local Directory

Source: https://context7.com/spinframework/spin/llms.txt

Installs Spin templates from a local directory. Use this for testing custom templates before publishing.

```bash
spin templates install --dir ./my-templates
```

--------------------------------

### Install Spin Trigger Plugin with Pluginify

Source: https://github.com/spinframework/spin/blob/main/examples/spin-timer/README.md

Commands to build a Spin plugin and install it using the 'pluginify' tool. This method simplifies the packaging and installation process compared to manual installation.

```bash
spin plugin install pluginify
```

```bash
spin pluginify --install
```

```bash
spin build --up
```

--------------------------------

### Spin.toml example for OCI push

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/008-using-oci-registries.md

Example `spin.toml` content used to derive application name and version for OCI registry pushes.

```toml
name = "myregistry.com/myusername/myapp"
version = "1.2.3"
```

--------------------------------

### Example Configuration Provider TOML

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/002-app-config.md

Illustrative TOML structure for configuring different configuration providers. This example shows a JSON file provider and an environment variable provider with a custom prefix.

```toml
[[config-provider]]
type = "json_file"
path = "config.json"

[[config-provider]]
type = "env"
prefix = "MY_APP_"
```

--------------------------------

### Build and Run Spin Application

Source: https://github.com/spinframework/spin/blob/main/examples/http-cpp/README.md

Builds the Spin application and starts the HTTP server.

```bash
spin build
spin up
```

--------------------------------

### Start Vault Server

Source: https://github.com/spinframework/spin/blob/main/examples/vault-variable-test/README.md

Starts a development instance of Vault. Ensure you note the root token ID for subsequent commands.

```bash
vault server -dev -dev-root-token-id root
```

--------------------------------

### Spin Login Command Example

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/007-deployment-auth.md

Demonstrates the interactive login experience for the `spin login` command, including prompts for authentication method and credentials.

```bash
spin login --url https://example.com
```

```text
What authentication method does this server support?
1. Sign in with GitHub
2. Sign in with a username and password
Enter a number:
```

```text
Hippo username: 
Hippo password:
# etc
```

```text
$ spin login --url https://example.com
Copy your one-time code: tWOJCFhY
Press Enter to open https://example.com/device-authorization in your browser
# ...user hits Enter...
Waiting for device authorization...
Waiting for device authorization...
Device authorized!
Login successful.
```

--------------------------------

### Install Spin CLI

Source: https://github.com/spinframework/spin/blob/main/README.md

Installs the Spin CLI using a curl script and moves the binary to the system's PATH. Ensure you have the necessary permissions to move the file to /usr/local/bin.

```bash
curl -fsSL https://spinframework.dev/downloads/install.sh | bash
sudo mv ./spin /usr/local/bin/spin
```

--------------------------------

### Spin Manifest Version 1 to Version 2 Transformation Example

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/005-manifest-redesign.md

Provides an example of how a version 1 manifest can be transformed into the equivalent version 2 format, illustrating the changes in structure and configuration placement.

```toml
trigger = { type = "http", base = "/" }
[[component]]
id = "hello"
source = "hello.wasm"
[component.trigger]
route = "/hello"

```

```toml
[application.trigger.http]
base = "/"
[[trigger.http]]
route = "/hello"
handler = "hello"
[component.hello]
source = "hello.wasm"

```

--------------------------------

### Install Spin Templates from Git

Source: https://context7.com/spinframework/spin/llms.txt

Installs Spin templates from a specified Git repository and branch. Ensure the repository URL and branch name are correct.

```bash
spin templates install --git https://github.com/org/templates --branch main
```

--------------------------------

### Install and Deploy Cloud Plugin

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/014-cloud-plugin.md

When the cloud plugin is not installed, Spin will prompt the user to install it and then proceed with the deployment.

```console
$ spin deploy
The `cloud` plugin is required. Installing now.
Plugin 'cloud' was installed successfully!
Uploading cloud_start version 0.1.0+XXXXXXXX...
Deploying...
Waiting for application to become ready... ready
Available Routes:
  cloud-start: https://cloud-start-xxxxxxxx.fermyon.app/ (wildcard)
```

--------------------------------

### spin plugin install

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/006-spin-plugins.md

Installs a Spin plugin using a plugin manifest file. It can install from a local file, a remote URL, or by default from the Spin plugins repository.

```APIDOC
## POST /spin plugin install

### Description
Installs a Spin plugin using a plugin manifest file. By default, it looks for the plugin manifest named `<name>.json` in the Spin plugins repository.

### Method
POST

### Endpoint
/spin plugin install <name>

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the plugin to install.

#### Query Parameters
- **-f, --file** (string) - Optional - Path to local plugin manifest.
- **-u, --url** (string) - Optional - Address of remote plugin manifest.
- **-v, --version** (string) - Optional - Version of plugin to be installed. Defaults to latest.
- **-y, --yes** (boolean) - Optional - Assume yes to all queries.

### Request Example
```json
{
  "name": "my-plugin",
  "file": "/path/to/local/manifest.json",
  "url": "http://example.com/manifest.json",
  "version": "1.2.0",
  "yes": true
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of successful plugin installation.

#### Response Example
```json
{
  "message": "Plugin 'my-plugin' installed successfully."
}
```
```

--------------------------------

### Manage Spin Application Templates with CLI

Source: https://context7.com/spinframework/spin/llms.txt

Commands for listing and installing application templates from Git repositories.

```bash
# List available templates
spin templates list

# Install templates from Git repository
spin templates install --git https://github.com/spinframework/spin-templates
```

--------------------------------

### Install Spin Plugins and Templates

Source: https://github.com/spinframework/spin/blob/main/tests/testcases/legacy-apps-test/README.md

Update Spin plugins, install the JavaScript to WASM plugin, and install Spin templates from Git repositories. This is a prerequisite for creating new Spin applications.

```bash
spin plugin update
spin plugin install js2wasm --yes
spin templates install --git https://github.com/spinframework/spin
spin templates install --git https://github.com/spinframework/spin-js-sdk
```

--------------------------------

### Spin Plugin Command Overview

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/006-spin-plugins.md

Lists the available subcommands for managing Spin plugins: install, uninstall, and upgrade. Use this command to see the basic structure of plugin management.

```bash
Commands for working with Spin plugins.

USAGE:
    spin plugin <SUBCOMMAND>

SUBCOMMANDS:
    install      Install plugin as described by a remote or local plugin manifest.
    uninstall    Uninstall a plugin.
    upgrade      Upgrade one or all plugins to the latest or specified version.
```

--------------------------------

### Install a Spin Plugin

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/006-spin-plugins.md

Installs a Spin plugin using a local or remote plugin manifest. Specify the plugin name and optionally use flags for local files, remote URLs, specific versions, or to auto-confirm prompts.

```bash
Install a Spin plugin using a plugin manifest file. 
By default, looks for the plugin manifest named <name>.json
in the Spin plugins repository https://github.com/fermyon/spin-plugins.

USAGE:
    spin plugin install <name>

OPTIONS:
    -f, --file                       Path to local plugin manifest.
    -u, --url                        Address of remote plugin manifest.
    -v, --version                    Version of plugin to be installed. Defaults to latest.
    -y, --yes                        Assume yes to all queries.
```

```bash
Installing plugin `test` with license Apache 2.0 from https://github.com/fermyon/spin-plugin-test/releases/download/v0.1.0/spin-plugin-test-v0.1.0-macos-aarch64.tar.gz
For more information, reference the plugin metadata at `https://github.com/fermyon/spin-plugins/plugin-manifests/test.json`.
Are you sure you want to proceed? (y/N)
```

--------------------------------

### Install Spin Trigger Plugin Manually

Source: https://github.com/spinframework/spin/blob/main/examples/spin-timer/README.md

Steps to manually build, package, and install a Spin trigger plugin. Ensure the plugin manifest (`.json`) correctly specifies the SHA, OS, architecture, and URL for the tarball.

```bash
cp ./target/release/trigger-timer .
tar czvf trigger-timer.tar.gz trigger-timer
```

```bash
shasum -a 256 trigger-timer.tar.gz
```

```bash
spin plugin install --file ./trigger-timer.json --yes
```

```bash
spin build --up
```

--------------------------------

### WASI Configfs File Access Example (Ruby)

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/002-app-config.md

Illustrates how configuration values might be accessed as files using a hypothetical WASI configfs interface. This example shows reading a string value and a JSON-encoded value.

```ruby
key1_value = File.read("/config/key1")

# Typed config; `.json` encodes values to JSON
key1_value = JSON.parse(File.read("/config/key1.json"))

# "bytes" type; `.raw` decodes from base64
encryption_key = File.read("/config/encryption_key.raw")
```

--------------------------------

### Run Spin Application with Runtime Configuration

Source: https://github.com/spinframework/spin/blob/main/examples/vault-variable-test/README.md

Starts the Spin application using a specified runtime configuration file. This file typically defines variable providers.

```bash
spin up --runtime-config-file runtime_config.toml
```

--------------------------------

### Run Spin Application

Source: https://github.com/spinframework/spin/blob/main/examples/spin-wagi-http/README.md

Start the Spin application with Wasm modules using the spin up command. Set RUST_LOG for detailed tracing.

```bash
RUST_LOG=spin=trace spin up -f spin.toml
```

--------------------------------

### Run Spin with Runtime Configuration

Source: https://context7.com/spinframework/spin/llms.txt

Starts a Spin application using a specified runtime configuration file. This allows external services to be configured for the application.

```bash
spin up --runtime-config-file runtime-config.toml
```

--------------------------------

### Spin Manifest Version 1 Example

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/005-manifest-redesign.md

Illustrates the structure of a Spin application manifest in version 1, featuring a single HTTP trigger and a component with its own trigger configuration.

```toml
spin_manifest_version = "1"
name = "hello-world"
trigger = { type = "http", base = "/hello" }

[[component]]
id = "hello"
# ...
[component.trigger]
route = "/hello"

```

--------------------------------

### Manage Spin Plugins with CLI

Source: https://context7.com/spinframework/spin/llms.txt

Commands for updating the plugin registry, listing, searching, installing, upgrading, and uninstalling Spin plugins.

```bash
# Update plugin registry
spin plugins update

# List available plugins
spin plugins list

# List installed plugins
spin plugins list --installed

# Search for plugins
spin plugins search cloud

# Install a plugin by name
spin plugins install cloud

# Install specific version
spin plugins install cloud --version 0.5.0

# Install from URL
spin plugins install --url https://example.com/plugin-manifest.json

# Install from local manifest
spin plugins install --file ./plugin-manifest.json

# Skip confirmation prompt
spin plugins install cloud --yes

# Upgrade all plugins
spin plugins upgrade --all

# Upgrade specific plugin
spin plugins upgrade cloud

# Uninstall a plugin
spin plugins uninstall cloud

# Show plugin information
spin plugins show cloud
```

--------------------------------

### Run Spin Application Locally

Source: https://context7.com/spinframework/spin/llms.txt

Use 'spin up' to start the Spin runtime and run your application locally. This command supports running from the current directory, specific manifest files, OCI registries, and allows configuration of listen addresses, environment variables, TLS, and component selection.

```bash
# Run application from current directory
spin up
```

```bash
# Run specific manifest file
spin up -f path/to/spin.toml
```

```bash
# Run from OCI registry
spin up -f ghcr.io/username/myapp:v1.0.0
```

```bash
# Run with custom listen address
spin up --listen 0.0.0.0:8080
```

```bash
# Run with environment variables passed to all components
spin up -e API_KEY=secret123 -e DEBUG=true
```

```bash
# Run with TLS
spin up --tls-cert cert.pem --tls-key key.pem
```

```bash
# Build before running
spin up --build
```

```bash
# Run specific components only
spin up -c handler -c worker
```

```bash
# Use direct file mounts (for development)
spin up --direct-mounts
```

```bash
# Find free port automatically
spin up --find-free-port
```

--------------------------------

### Upgrade Installed Spin Templates

Source: https://context7.com/spinframework/spin/llms.txt

Upgrades all currently installed Spin templates to their latest available versions.

```bash
spin templates upgrade
```

--------------------------------

### Add Wasm Targets for Spin Componentize

Source: https://github.com/spinframework/spin/blob/main/crates/componentize/README.md

Install the necessary Wasm targets for building Spin components. Ensure Rust v1.68 or later is installed.

```shell
rustup target add wasm32-wasip1
rustup target add wasm32-unknown-unknown
```

--------------------------------

### Targeting Pre-release Spin Versions

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/011-component-versioning.md

This example shows how to target pre-release versions of Spin by appending a '-preN' suffix to the version string. This is useful for components built against development builds of Spin.

```text
spin-sdk-version-0-10-pre1
```

--------------------------------

### Component Tracing Configuration in Spin Manifest

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/018-adding-otel-tracing-to-spin.md

Example of how per-component tracing configuration might be defined in a spin.toml manifest, including context propagation settings.

```toml
[component.my-component.tracing]
context_propagation = true
```

--------------------------------

### Redis Trigger Application Manifest

Source: https://context7.com/spinframework/spin/llms.txt

A minimal `spin.toml` manifest example for an application using a Redis trigger.

```toml
spin_manifest_version = 2

[application]
name = "redis-processor"
version = "1.0.0"

```

--------------------------------

### Curl Hello Route

Source: https://github.com/spinframework/spin/blob/main/examples/spin-wagi-http/README.md

Send an HTTP GET request to the /hello route of the running Spin application and display the response headers and body.

```bash
$ curl -i localhost:3000/hello
HTTP/1.1 200 OK
content-type: application/text
content-length: 7
date: Thu, 10 Mar 2022 21:38:34 GMT

Hello
```

--------------------------------

### Configure Default SQLite Key-Value Store

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/010-key-value.md

Configure the default key-value store settings, including its type and path, within the runtime configuration file. This example shows a Spin-specific SQLite store.

```toml
# The `default` config can be overridden
[key_value_store.default]
type = "spin"
path = ".spin/sqlite_key_value.db"
```

--------------------------------

### Push, Pull, and Run Spin Applications via OCI

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/008-using-oci-registries.md

Use these commands to interact with Spin applications stored in OCI registries. Ensure you have the 'spin' CLI installed and are logged into your OCI registry if necessary.

```bash
$ spin oci push ghcr.io/<username>/my-spin-application:v1
INFO spin_publish::oci::client: Pushed "https://ghcr.io/v2/<username>/my-spin-application/manifests/sha256:9f4e7eebb27c0174fe6654ef5e0f908f1edc8f625324a9f49967ccde44a6516b"
```

```bash
$ spin oci pull ghcr.io/<username>/my-spin-application:v1
INFO spin_publish::oci::client: Pulled ghcr.io/<username>/my-spin-application:v1@sha256:9f4e7eebb27c0174fe6654ef5e0f908f1edc8f625324a9f49967ccde44a6516b
```

```bash
$ spin up --oci ghcr.io/<username>/my-spin-application:v1
INFO spin_publish::oci::client: Pulled ghcr.io/<username>/my-spin-application:v1@sha256:9f4e7eebb27c0174fe6654ef5e0f908f1edc8f625324a9f49967ccde44a6516b
Serving http://127.0.0.1:3000
```

--------------------------------

### Basic HTTP Application Manifest

Source: https://context7.com/spinframework/spin/llms.txt

Example of a `spin.toml` manifest for a basic HTTP application. It defines application metadata, variables, HTTP triggers, and component configurations including build commands, allowed outbound hosts, and resource access.

```toml
spin_manifest_version = 2

[application]
name = "my-spin-app"
version = "1.0.0"
description = "A sample Spin application"
authors = ["Developer <dev@example.com>"]

# Application-level variables (can be set via environment or runtime config)
[variables]
api_host = { default = "api.example.com" }
log_level = { required = true }

# HTTP trigger configuration
[[trigger.http]]
route = "/api/..."
component = "api-handler"

[[trigger.http]]
route = "/health"
component = "health-check"

# Component definitions
[component.api-handler]
source = "target/wasm32-wasip2/release/api_handler.wasm"
description = "Main API handler"
allowed_outbound_hosts = ["https://{{ api_host }}", "redis://localhost:6379"]
key_value_stores = ["default", "cache"]
sqlite_databases = ["default"]
ai_models = ["llama2-chat"]
environment = { LOG_LEVEL = "{{ log_level }}" }

[component.api-handler.build]
command = "cargo build --target wasm32-wasip2 --release"
watch = ["src/**/*.rs", "Cargo.toml"]

[component.health-check]
source = "target/wasm32-wasip2/release/health.wasm"
[component.health-check.build]
command = "cargo build --target wasm32-wasip2 --release -p health"

```

--------------------------------

### Test Spin Application with cURL

Source: https://github.com/spinframework/spin/blob/main/README.md

Sends an HTTP GET request to the locally running Spin application at http://127.0.0.1:3000 and displays the response headers and body.

```bash
curl -i 127.0.0.1:3000
```

--------------------------------

### Verify Spin Release Signature with Cosign

Source: https://github.com/spinframework/spin/blob/main/docs/content/release-notes-template.md

Use this command after installing cosign to verify the signature of a downloaded Spin release artifact. Ensure you have the signature file (.sig), certificate (crt.pem), and the release artifact itself.

```bash
cosign verify-blob \
    --signature spin.sig --certificate crt.pem \
    --certificate-identity https://github.com/spinframework/spin/.github/workflows/release.yml@refs/tags/<version> \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com \
    --certificate-github-workflow-sha <commit_sha> \
    --certificate-github-workflow-repository spinframework/spin \
    spin
```

--------------------------------

### Generate JavaScript WASM Module

Source: https://github.com/spinframework/spin/blob/main/tests/testcases/legacy-apps-test/README.md

Create a new HTTP JavaScript application using the Spin template, install npm dependencies, build the WASM module, and copy it to a longevity test file. Ensure you are in the application directory after creation.

```bash
spin new http-js http-js-test
cd http-js-test
npm install
spin build
cp target/spin-http-js.wasm longevity-javascript.wasm
```

--------------------------------

### Upgrade Spin Plugins

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/006-spin-plugins.md

Upgrades installed Spin plugins. Use the `--all` flag to upgrade all plugins, or specify a plugin name with `--plugin`. You can also specify a target version with `--version` or use `--downgrade` to revert to an older version.

```bash
Upgrade one or all installed Spin plugins.

USAGE:
    spin plugin upgrade [OPTIONS]

OPTIONS:
    -a, --all        Upgrade all installed plugins to latest versions (cannot be used with any other option).
    -p, --plugin     Name of plugin to upgrade.
    -v, --version    Desired version to upgrade the plugin to. Defaults to latest. 
    -f, --file       Path to local manifest (mutex with `-u`).
    -u, --url        Address of remote manifest (mutex with `-f`).
    -d, --downgrade  Enables downgrading a plugin to an older specified version.
```

--------------------------------

### Get Device Code for Spin Login

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/007-deployment-auth.md

Use this command to initiate the device authorization flow and retrieve necessary codes for authentication. It's intended for programmatic use where interactive browser login is not feasible.

```bash
$ spin login --url foo --get-device-code
{ "verificationUrl" : "...", "deviceCode" : "...", "userCode": " ..." }
```

--------------------------------

### Run Spin Documentation Website

Source: https://github.com/spinframework/spin/blob/main/docs/README.md

Use this command to run the Spin documentation website from its directory after building Spin.

```bash
spin up
```

--------------------------------

### Generate TypeScript WASM Module

Source: https://github.com/spinframework/spin/blob/main/tests/testcases/legacy-apps-test/README.md

Create a new HTTP TypeScript application using the Spin template, install npm dependencies, build the WASM module, and copy it to a longevity test file. Ensure you are in the application directory after creation.

```bash
spin new http-ts http-ts-test
cd http-ts-test
npm install
spin build
cp target/spin-http-js.wasm longevity-typescript.wasm
```

--------------------------------

### Cargo Vet Audit Failure Example

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/009-auditing-third-party-dependencies.md

This output shows a typical failure when `cargo vet` detects unvetted dependencies. It lists the unvetted dependencies, suggests recommended audits, and estimates the audit backlog. Use `cargo vet certify` to record audits.

```bash
$ cargo vet
  Vetting Failed!

  3 unvetted dependencies:
      bar:1.5 missing ["safe-to-deploy"]
      baz:1.3 missing ["safe-to-deploy"]
      foo:1.2.1 missing ["safe-to-deploy"]

  recommended audits for safe-to-deploy:
      cargo vet diff foo 1.2 1.2.1  (10 lines)
      cargo vet diff bar 2.1.1 1.5  (253 lines)
      cargo vet inspect baz 1.3     (2033 lines)

  estimated audit backlog: 2296 lines

  Use |cargo vet certify| to record the audits.
```

--------------------------------

### Build the Deny Adapter

Source: https://github.com/spinframework/spin/blob/main/crates/capabilities/deny-adapter/README.md

Build the deny adapter by running the make adapter command in the parent crate.

```bash
make adapter
```

--------------------------------

### Configure Component with Files and Dependencies

Source: https://context7.com/spinframework/spin/llms.txt

Defines a component's source, static files to include, external dependencies, and build commands.

```toml
spin_manifest_version = 2

[application]
name = "static-site"
version = "1.0.0"

[[trigger.http]]
route = "/..."
component = "fileserver"

[component.fileserver]
source = "fileserver.wasm"

# Include static files
files = [
  "static/**/*",
  { source = "assets", destination = "/public" }
]
exclude_files = ["static/**/*.map", "static/.gitkeep"]

# Component dependencies from registry
[component.fileserver.dependencies]
"wasi:http/handler@0.2.0" = ">= 0.2.0"
"my:utils/helper" = { path = "helper.wasm", export = "helper" }
"shared:lib" = { component = "shared-component" }

# Build profiles
[component.fileserver.build]
command = "npm run build"
watch = ["src/**/*"]

[component.fileserver.profile.debug]
source = "debug/fileserver.wasm"
build.command = "npm run build:debug"
environment = { DEBUG = "true" }
```

--------------------------------

### Create New Spin Application

Source: https://github.com/spinframework/spin/blob/main/README.md

Creates a new Spin application named 'hello-rust' using the Rust http template. The --accept-defaults flag automatically accepts all prompts.

```bash
spin new --accept-defaults -t http-rust hello-rust
```

--------------------------------

### spin plugin upgrade

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/006-spin-plugins.md

Upgrades one or all installed Spin plugins to the latest or a specified version.

```APIDOC
## PUT /spin plugin upgrade

### Description
Upgrades one or all installed Spin plugins. Plugins can be upgraded to the latest version or a specific version. Manifest file paths or URLs can also be provided.

### Method
PUT

### Endpoint
/spin plugin upgrade

### Parameters
#### Query Parameters
- **-a, --all** (boolean) - Optional - Upgrade all installed plugins to latest versions (cannot be used with any other option).
- **-p, --plugin** (string) - Optional - Name of the plugin to upgrade.
- **-v, --version** (string) - Optional - Desired version to upgrade the plugin to. Defaults to latest.
- **-f, --file** (string) - Optional - Path to local manifest (mutex with `-u`).
- **-u, --url** (string) - Optional - Address of remote manifest (mutex with `-f`).
- **-d, --downgrade** (boolean) - Optional - Enables downgrading a plugin to an older specified version.

### Request Example
```json
{
  "all": true,
  "plugin": "my-plugin",
  "version": "2.0.0",
  "file": "/path/to/local/manifest.json",
  "url": "http://example.com/manifest.json",
  "downgrade": true
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of successful plugin upgrade.

#### Response Example
```json
{
  "message": "Plugin 'my-plugin' upgraded to version 2.0.0 successfully."
}
```
```

--------------------------------

### Build and Copy Test Components

Source: https://github.com/spinframework/spin/blob/main/crates/build/tests/test-components/README.md

Navigate to the test command directory, build the release target for wasm32-wasip2, and then copy the compiled artifact to the specified directory. Ensure the target directory exists.

```bash
cd source/test-command
cargo build --release --target wasm32-wasip2
```

```bash
cp target/wasm32-wasip2/release/your_component_name.wasm .
```

--------------------------------

### Configure Redis-backed Key-Value Store

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/010-key-value.md

Configure an alternative key-value store, such as a Redis-backed store, by specifying its type and connection URL in the runtime configuration file.

```toml
# Example of a possible Redis-backed KV store type
[key_value_store.user_data]
type = "redis"
url = "redis://localhost"
```

--------------------------------

### Configure Services for Testing

Source: https://github.com/spinframework/spin/blob/main/tests/testing-framework/README.md

Specify the services required for a test by listing their service file names in the 'services' file. Each line should contain the name of a service file to be run.

```txt
tcp-echo
```

--------------------------------

### Uninstall a Spin Plugin

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/006-spin-plugins.md

Uninstalls a specified Spin plugin by its name. This command removes the plugin and its associated files from the local Spin installation.

```bash
Uninstall a Spin plugin.

USAGE:
    spin plugin uninstall <name>
```

--------------------------------

### Curl Goodbye Route

Source: https://github.com/spinframework/spin/blob/main/examples/spin-wagi-http/README.md

Send an HTTP GET request to the /goodbye route of the running Spin application and display the response headers and body.

```bash
$ curl -i localhost:3000/goodbye
HTTP/1.1 200 OK
foo: bar
content-length: 7
date: Thu, 10 Mar 2022 21:38:58 GMT

Goodbye
```

--------------------------------

### Create New Spin Application

Source: https://context7.com/spinframework/spin/llms.txt

Use 'spin new' to create a new Spin application from a template. Options include accepting defaults, interactive creation, specifying templates, custom output directories, parameter values, initializing in the current directory, and using values files.

```bash
# Create a new Rust HTTP application with default options
spin new --accept-defaults -t http-rust hello-rust
```

```bash
# Create interactively (prompts for name and options)
spin new
```

```bash
# Create with specific template and custom output directory
spin new myapp -t http-rust -o ./projects/myapp
```

```bash
# Create with parameter values
spin new myapp -t http-rust -v author="Your Name" -v description="My app"
```

```bash
# Initialize in current directory instead of creating new folder
spin new myapp -t http-rust --init
```

```bash
# Create from values file
spin new myapp -t http-rust --values-file config.toml
```

--------------------------------

### Database Migrations

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/013-sqlite.md

Information on how to handle database migrations using command-line options.

```APIDOC
## Database Migrations

### Description
Database tables often require configuration through migrations to set up correct table schemas. This can be achieved using a command-line option supplied to `spin up`.

### Usage
A command-line option, such as `--sqlite "CREATE TABLE users..."`, can be used to run arbitrary SQL statements on startup. Users are responsible for providing idempotent statements to prevent unexpected results from multiple executions.
```

--------------------------------

### Compile C++ Application

Source: https://github.com/spinframework/spin/blob/main/examples/spin-wagi-http/README.md

Build the C++ application in the wagi-http-cpp directory using make.

```bash
cd ../wagi-http-cpp
make build
```

--------------------------------

### Build and Run Spin Application

Source: https://github.com/spinframework/spin/blob/main/tests/manual/pg-ssl-root-certs/setup.md

Builds and deploys the Spin application. This is a base case test without TLS enabled for the database connection.

```sh
./local-db.sh
```

```sh
spin build --up
```

--------------------------------

### Granting Database Access in spin.toml

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/013-sqlite.md

Specify which SQLite databases a component can access by listing their names in the `sqlite_databases` array within `spin.toml`. For example, granting access to the default database.

```toml
sqlite_databases = ["<database 1>", "<database 2>"]
```

```toml
sqlite_databases = ["default"]
```

--------------------------------

### Migrate Spin Applications from Bindle to OCI

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/008-using-oci-registries.md

Use this command to migrate applications from a Bindle server to an OCI registry. This functionality is intended as a plugin for temporary use.

```bash
spin bindle2oci \
    --bindle-server <server> \
    --bindle-username <username> \
    --bindle-password <password> \
    ---bindle <name> \
    --oci <new-reference>
```

--------------------------------

### Send Outbound HTTP Requests with Spin SDK

Source: https://context7.com/spinframework/spin/llms.txt

Use the `outbound_http` module to send GET and POST requests to external services. Ensure necessary imports and handle responses, including JSON parsing.

```rust
use spin_sdk::http::{IntoResponse, Method, Request, Response, StatusCode};
use spin_sdk::http_service;
use spin_sdk::outbound_http;
use serde::Deserialize;

#[derive(Deserialize)]
struct GitHubUser {
    login: String,
    name: Option<String>,
    public_repos: u32,
}

#[http_service]
async fn handle_request(_req: Request) -> anyhow::Result<impl IntoResponse> {
    // Simple GET request
    let response = outbound_http::send(
        Request::builder()
            .method(Method::Get)
            .uri("https://api.github.com/users/spinframework")
            .header("User-Agent", "Spin/1.0")
            .build()
    ).await?;

    let status = response.status();
    let body = response.into_body();

    if status == StatusCode::OK {
        let user: GitHubUser = serde_json::from_slice(&body)?;
        Ok(Response::builder()
            .status(StatusCode::OK)
            .header("content-type", "application/json")
            .body(format!(
                r#"{{"user": "{}", "repos": {}}}""#,
                user.login,
                user.public_repos
            )))
    } else {
        Ok(Response::builder()
            .status(status)
            .body("Failed to fetch user"))
    }
}

// POST request with JSON body
async fn create_resource() -> anyhow::Result<Response> {
    let payload = serde_json::json!({
        "title": "New Resource",
        "body": "Resource content"
    });

    let response = outbound_http::send(
        Request::builder()
            .method(Method::Post)
            .uri("https://api.example.com/resources")
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer token123")
            .body(serde_json::to_vec(&payload)?)
            .build()
    ).await?;

    Ok(Response::builder()
        .status(response.status())
        .body(response.into_body()))
}
```

--------------------------------

### Build Spin Application

Source: https://context7.com/spinframework/spin/llms.txt

The 'spin build' command compiles Spin application components to WebAssembly. It supports building the current directory, specific manifest files, selected components, profiles, and options to skip checks or build and run immediately.

```bash
# Build application in current directory
spin build
```

```bash
# Build specific manifest file
spin build -f path/to/spin.toml
```

```bash
# Build specific components only
spin build -c component1 -c component2
```

```bash
# Build with a named profile
spin build --profile debug
```

```bash
# Build and immediately run
spin build --up
```

```bash
# Build and run with additional up arguments
spin build --up -- --listen 0.0.0.0:8080
```

```bash
# Skip target environment compatibility checks
spin build --skip-target-checks
```

--------------------------------

### Run Spin Application with Specific Build Profile

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/022-build-profiles.md

Use the `--profile [profile-name]` flag with `spin up` to run the application using specified build profiles for components. Components without the specified profile will fall back to their default configuration.

```bash
spin up --profile debug
```

--------------------------------

### Inspect a Crate with Cargo Vet

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/009-auditing-third-party-dependencies.md

Use `cargo vet inspect` to guide the user through performing an audit for a specific crate version. It provides a link to the crate's source and prompts the user to open it in a browser.

```bash
$ cargo vet inspect baz 1.3
You are about to inspect version 1.3 of 'baz', likely to certify it for "safe-to-deploy", which means:
   ...
You can inspect the crate here: https://sourcegraph.com/crates/baz@v1.3

(press ENTER to open in your browser, or re-run with --mode=local)
```

--------------------------------

### Interactive Cloud Deployment Configuration

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/014-cloud-plugin.md

An optional interactive command to configure the current Spin app for deployment, invoked automatically if the app is not yet configured.

```console
$ spin cloud deploy
The current Spin app hasn't been set up for deployment yet.
Pick a new or existing deployment config:

> Fermyon Cloud - New Deployment
  Fermyon Cloud - 'spicy-meatballs'

Creating new deployment...
New deployment created: 'mighty-hamster'

[...SNIP normal deploy flow...]
```

--------------------------------

### Typed Configuration with TOML

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/002-app-config.md

Demonstrates defining configuration slots with explicit types (number, string, bytes) in TOML. Types can often be inferred from default values.

```toml
# Type can be inferred from default value:
number_key = { default = 123 }
# equivalent to:
number_key = { type = "number", default = 123 }

required_string = { type = "string", required = true }
# "bytes" would require e.g. base64 encoding in some places
encryption_key = { type = "bytes", required = true, secret = true}
```

--------------------------------

### Build Spin Application

Source: https://github.com/spinframework/spin/blob/main/README.md

Compiles the Spin application to WebAssembly using the 'spin build' command. This command executes the underlying build process, such as 'cargo build' for Rust components.

```bash
spin build
```

--------------------------------

### Spin.toml Configuration References

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/002-app-config.md

In spin.toml, configuration values can reference top-level keys, sibling keys (prefixed with '.'), and ancestor keys (prefixed with multiple '.'). This allows for complex interdependencies in configuration.

```toml
[variables]
app_root = { default = "/app" }
log_file = { default = "{{ app_root }}/log.txt" }
...
[[component.config]]
work_root = "{{ app_root }}/work"      # -> "/app/work"
work_out = "{{ .work_root }}/output"   # -> "/app/work/output"
[[component.dependencies.dep1.config]]
dep_root = "{{ ..work_root }}/dep"     # -> "/app/work/dep"
```

--------------------------------

### Run Full Spin Integration Test Suite

Source: https://github.com/spinframework/spin/blob/main/tests/README.md

Execute the complete integration test suite, which may require Docker and additional compiler toolchains like Swift and Zig. This command runs all integration tests.

```bash
make test-integration-full
```

--------------------------------

### Define Multiple Build Profiles in spin.toml

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/022-build-profiles.md

Use `[component.name.profile.profile-name]` tables to define alternative build configurations for a component. Fallback to default profiles if a specific profile is not defined for a component.

```toml
# (Source: https://github.com/fermyon/ai-examples/blob/main/sentiment-analysis-ts/spin.toml,
#  with parts not relevant to profiles omitted.)

spin_manifest_version = 2

[application]
name = "sentiment-analysis"
...

[component.sentiment-analysis]
source = "target/spin-http-js.wasm"
...

[component.sentiment-analysis.build]
command = "npm run build"
watch = ["src/**/*", "package.json", "package-lock.json"]

# Debug build of the `sentiment-analysis` component:
[component.sentiment-analysis.profile.debug]
source = "target/spin-http-js.debug.wasm"

[component.sentiment-analysis.profile.debug.build]
command = "npm run build:debug"

# The `ui` component doesn't have a debug build, so the default build will always be used.
[component.ui]
source = { url = ".../spin_static_fs.wasm", digest = "..." }
...

[component.kv-explorer]
source = { url = ".../spin-kv-explorer.wasm", digest = "..." }
...

# Uses a pre-built debug version of the component.
[component.kv-explorer.profile.debug]
source = { url = ".../spin-kv-explorer.debug.wasm", digest = "..." }

```

--------------------------------

### Reference App Component with inherit_configuration

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/023-fine-grained-capability-inheritance.md

Reference an app component and specify `inherit_configuration` for its dependencies. This allows inheriting configuration from the parent.

```toml
"infra:dep/svc" = { component = "svc-component", inherit_configuration = ["key_value_stores", "variables"] }
```

--------------------------------

### Spin Manifest Version 2: Component Inline Configuration

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/005-manifest-redesign.md

Demonstrates how component configurations can be inlined directly within the trigger definition in version 2 manifests, simplifying the structure for certain use cases.

```toml
[[trigger.http]]
route = "/hello"
handler = { source = "hello.wasm" }

```

--------------------------------

### GitHub Actions Workflow for Signing Artifacts

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/012-signing-spin-releases.md

This workflow automates the signing of artifacts using Cosign and a GitHub OIDC token. Ensure the `sigstore/cosign-installer` action is configured with the desired Cosign release version.

```yaml
jobs:
  sign:
    runs-on: ubuntu-latest

    permissions:
      id-token: write 

    name: Sign artifact and publish signature and certificate
    steps:
      - uses: actions/checkout@master
        with:
          fetch-depth: 1

      - name: Install Cosign
        uses: sigstore/cosign-installer@main
        with:
          cosign-release: v2.0.0

      - name: Create an artifact
        run: |
          mkdir out
          echo 'hello world' > out/artifact
          
      - name: Sign the artifact with GitHub OIDC token
        run: cosign sign-blob --output-certificate out/crt.pem --output-signature out/artifact.sig out/artifact --yes

      - name: Upload assets as GitHub artifact
        uses: actions/upload-artifact@v3
        with:
          name: artifact
          path: out/*

```

--------------------------------

### Generate Go WASM Module

Source: https://github.com/spinframework/spin/blob/main/tests/testcases/legacy-apps-test/README.md

Create a new HTTP Go application using the Spin template, build the WASM module, and copy it to a longevity test file. Ensure you are in the application directory after creation.

```bash
spin new http-go http-go-test
cd http-go-test
spin build
cp main.wasm longevity-go.wasm
```

--------------------------------

### Run Spin Integration Tests (Subset)

Source: https://github.com/spinframework/spin/blob/main/tests/README.md

Execute a subset of integration tests that only require Rust and Python toolchains. This is a quicker way to run integration tests.

```bash
make test-integration
```

--------------------------------

### Create and push a GPG-signed git tag

Source: https://github.com/spinframework/spin/blob/main/docs/content/release-process.md

Create a GPG-signed and annotated tag for the release, then push it to the remote repository. This triggers the release workflow.

```bash
# Switch to the release branch
git checkout v2.0
git pull

# Create a GPG-signed and annotated tag
git tag -s -m "Spin v2.0.0" v2.0.0

# Push the tag to the remote corresponding to spinframework/spin (here 'origin')
git push origin v2.0.0
```

--------------------------------

### Rust: Interact with Spin Key-Value Store

Source: https://context7.com/spinframework/spin/llms.txt

Use the default or named key-value stores for caching and state management. Ensure stores are configured in spin.toml.

```rust
use spin_sdk::http::{IntoResponse, Request, Response, StatusCode};
use spin_sdk::http_service;
use spin_sdk::key_value::Store;

#[http_service]
async fn handle_request(req: Request) -> anyhow::Result<impl IntoResponse> {
    // Open the default key-value store
    let store = Store::open_default()?;

    // Get a value
    let visit_count = match store.get("visit_count")? {
        Some(bytes) => {
            let count: u64 = String::from_utf8(bytes)?.parse()?;
            count + 1
        }
        None => 1,
    };

    // Set/update a value
    store.set("visit_count", visit_count.to_string().as_bytes())?;

    // Check if key exists
    let exists = store.exists("visit_count")?;

    // List all keys
    let keys = store.get_keys()?;
    println!("Store has {} keys", keys.len());

    // Delete a key
    // store.delete("some_key")?;

    // Open a named store (must be configured in spin.toml)
    let cache = Store::open("cache")?;
    cache.set("last_visit", chrono::Utc::now().to_rfc3339().as_bytes())?;

    Ok(Response::builder()
        .status(StatusCode::OK)
        .header("content-type", "text/plain")
        .body(format!("Visit count: {}", visit_count)))
}
```

--------------------------------

### Signal Readiness in Python Services

Source: https://github.com/spinframework/spin/blob/main/tests/testing-framework/README.md

Python services can indicate they are ready for testing by printing 'READY' to standard output. This ensures tests do not run before the service is fully initialized.

```python
print("READY")
```

--------------------------------

### Configure Spin Pluginify TOML

Source: https://github.com/spinframework/spin/blob/main/examples/spin-timer/README.md

Configuration file for the 'pluginify' tool to package a Spin trigger. This TOML file specifies metadata like name, description, version, and the path to the compiled plugin package.

```toml
name= "trigger-timer"
description= "Run Spin components at timed intervals"
homepage= "https://github.com/spinframework/spin/tree/main/examples/spin-timer"
version= "0.1.0"
spin_compatibility= ">=2.0"
license= "Apache-2.0"
package= "./target/release/trigger-timer"
```

--------------------------------

### Switch to a release branch

Source: https://github.com/spinframework/spin/blob/main/docs/content/release-process.md

Check out the desired release branch locally. Replace `<branch-name>` with the actual branch name, e.g., `v2.0`.

```bash
git checkout <branch-name>
```

--------------------------------

### Rust: Query SQLite Database with Spin SDK

Source: https://context7.com/spinframework/spin/llms.txt

Execute SQL queries against SQLite databases, including table creation, data insertion, and querying with parameters. Supports opening default or named databases.

```rust
use spin_sdk::http::{IntoResponse, Request, Response, StatusCode};
use spin_sdk::http_service;
use spin_sdk::sqlite::{Connection, Value};

#[http_service]
async fn handle_request(req: Request) -> anyhow::Result<impl IntoResponse> {
    // Open the default SQLite database
    let conn = Connection::open_default()?;

    // Create table if not exists
    conn.execute(
        "CREATE TABLE IF NOT EXISTS users (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            name TEXT NOT NULL,
            email TEXT UNIQUE NOT NULL,
            created_at TEXT DEFAULT CURRENT_TIMESTAMP
        )",
        &[],
    )?;

    // Insert data with parameters
    conn.execute(
        "INSERT INTO users (name, email) VALUES (?, ?)",
        &[Value::Text("Alice".into()), Value::Text("alice@example.com".into())],
    )?;

    // Query data
    let result = conn.execute(
        "SELECT id, name, email FROM users WHERE name LIKE ?",
        &[Value::Text("%Alice%".into())],
    )?;

    // Process results
    let mut users = Vec::new();
    for row in result.rows() {
        let id: i64 = row.get("id").unwrap();
        let name: &str = row.get("name").unwrap();
        let email: &str = row.get("email").unwrap();
        users.push(format!("{}: {} ({})", id, name, email));
    }

    // Open a named database
    let analytics_db = Connection::open("analytics")?;
    analytics_db.execute(
        "INSERT INTO page_views (path, timestamp) VALUES (?, ?)",
        &[Value::Text(req.path().into()), Value::Text(chrono::Utc::now().to_rfc3339())],
    )?;

    Ok(Response::builder()
        .status(StatusCode::OK)
        .header("content-type", "application/json")
        .body(serde_json::to_string(&users)?))
}
```

--------------------------------

### Define HTTP Dependency with inherit_configuration

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/023-fine-grained-capability-inheritance.md

Use the expanded table form to define HTTP dependencies and specify `inherit_configuration`. This is required when `inherit_configuration` is needed.

```toml
"vendor:dep/api" = { url = "https://example.com/dep.wasm", digest = "sha256:abc123", inherit_configuration = ["variables"] }
```

--------------------------------

### Push application with user-defined tag

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/008-using-oci-registries.md

Use `spin oci push` to distribute your application to an OCI registry. You can specify a custom name and tag for the artifact.

```bash
$ spin oci push --file <path to spin.toml> myregistry.com/myusername/myapp:v1
```

```bash
$ spin oci push --file <path to spin.toml> myregistry.com/myusername/myapp:latest
```

```bash
$ spin oci push --file <path to spin.toml> myregistry.com/myusername/myapp:v0.1.0+r2d2
```

--------------------------------

### Authenticate Spin CLI with OCI Registries

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/008-using-oci-registries.md

Log in to an OCI registry using your username and password or password from stdin. This mirrors the functionality of the `docker login` command.

```bash
$ spin oci login --username <username> --password <password>
```

```bash
$ echo $CONTAINER_REGISTRY_PASSWORD | spin oci login --username <username> --password-stdin
```

--------------------------------

### Apply Inheritance Across Dependency Types

Source: https://github.com/spinframework/spin/blob/main/docs/content/sips/023-fine-grained-capability-inheritance.md

The `inherit_configuration` field works consistently for various dependency source types, including registry packages and local paths. Use `true`, `false`, or a specific list of configurations as needed.

```toml
[component."my-app".dependencies]
# Registry dependency
"aws:client" = { version = "1.0.0", inherit_configuration = ["allowed_outbound_hosts"] }

# Local dependency
"my:lib/utils" = { path = "lib/utils.wasm", inherit_configuration = true }
```

--------------------------------

### Run Spin Runtime Tests

Source: https://github.com/spinframework/spin/blob/main/tests/README.md

Execute runtime tests to ensure Spin-compliant runtimes conform to expected behavior. This command requires the `extern-dependencies-tests` feature to be enabled.

```bash
cargo test runtime_tests -F extern-dependencies-tests
```

--------------------------------

### Compile Rust Application

Source: https://github.com/spinframework/spin/blob/main/examples/spin-wagi-http/README.md

Compile the Rust application in the http-rust directory using Cargo.

```bash
cd http-rust
cargo build --release
```
Tokens:
Raw