|
5 | 5 | <img src="./logos/capsule-logo-readme.png" alt="capsule-logo.png" width="10%" height="10%"/> |
6 | 6 |
|
7 | 7 | # Capsule: the nano (wasm) functions runner |
8 | | -> - 🖐 I'm learning Go |
9 | | -> - Issues: https://github.com/bots-garden/capsule/issues |
10 | | -> - Last release: `v0.2.6 🐝 [Bee]` |
11 | | -> - Dev release: `v0.2.7 🦚 [peacock][dev]` *🚧 in progress* |
12 | | -
|
13 | | -## What's new |
14 | 8 |
|
15 | | -- `v0.2.6`: Wazero: updates to `1.0.0-pre.2` by [@codefromthecrypt](https://github.com/codefromthecrypt) + a logo |
16 | | -- `v0.2.5`: Add MQTT support by [@py4mac](https://github.com/py4mac) with `MqttPublish` & `MqttPublish` |
17 | | -- `v0.2.4`: Add 2 wasm helper functions `flatjson.StrToMap` and `flatjson.MapToStr` |
18 | | -- `v0.2.3`: NATS support, 2 new functions: `NatsReply` and `NatsConnectRequest` |
19 | | -- `v0.2.2`: like `0.2.1` with fixed modules dependencies, and tag name start with a `v` |
20 | | -- `0.2.1`: NATS support (1st stage) `OnNatsMessage`, `NatsPublish`, `NatsConnectPublish`, `NatsConnectPublish`, `NatsGetSubject`, `NatsGetServer` |
21 | | -- `0.2.0`: `OnLoad` & `OnExit` functions + Memory cache host functions (`MemorySet`, `MemoryGet`, `MemoryKeys`) |
22 | | -- `0.1.9`: Add `Request` and `Response` types (for the Handle function) |
23 | | -- `0.1.8`: Redis host functions: add the KEYS command (`RedisKeys(pattern string)`) |
| 9 | +> - Issues: https://github.com/bots-garden/capsule/issues |
| 10 | +> - Last release: `v0.2.7 🦚 [peacock]` |
| 11 | +> - Dev release: `v0.2.8 TBD` *🚧 in progress* |
24 | 12 |
|
25 | 13 | ## What is **Capsule**? |
26 | 14 |
|
|
31 | 19 | - Serving a function of a wasm module through NATS (the **"NATS mode"**), in this case **Capsule** is used as a NATS subscriber and can reply on a subject(topic) |
32 | 20 | - Serving a function of a wasm module through MQTT (the **"MQTT mode"**), in this case **Capsule** is used as a MQTT subscriber and can reply on a subject(topic) |
33 | 21 |
|
34 | | -> 🖐 **The functions are developed with GoLang and compiled to wasm with TinyGo** |
35 | | -
|
36 | | -📦 Before executing or running a function, you need to download the last release of **Capsule**: https://github.com/bots-garden/capsule/releases/tag/v0.2.6 (`v0.2.6 🐝 [Bee]`) |
37 | | - |
38 | 22 | > - **Capsule** is developed with GoLang and thanks to the 💜 **[Wazero](https://github.com/tetratelabs/wazero)** project |
39 | 23 | > - The wasm modules are developed in GoLang and compiled with TinyGo (with the WASI specification) |
40 | 24 |
|
| 25 | +## Installing Capsule |
| 26 | + |
| 27 | +Before executing or running a function, you need to install the last release of **Capsule**: |
| 28 | + |
| 29 | +```bash |
| 30 | +CAPSULE_VERSION="v0.2.7" |
| 31 | +wget -O - https://raw.githubusercontent.com/bots-garden/capsule/${CAPSULE_VERSION}/install-capsule-launcher.sh| bash |
| 32 | +# To get the developement version you can use CAPSULE_VERSION="main" |
| 33 | +``` |
| 34 | +> The script will install capsule in `$HOME/.local/bin` |
| 35 | +
|
| 36 | +Then you can serve a wasm function like this: |
| 37 | + |
| 38 | +```bash |
| 39 | +MESSAGE="👋 Hello World 🌍" capsule \ |
| 40 | + -wasm=./app/index.wasm \ |
| 41 | + -mode=http \ |
| 42 | + -httpPort=8080 |
| 43 | +``` |
| 44 | + |
| 45 | +> You can download the appropriate release of **Capsule** here: https://github.com/bots-garden/capsule/releases/tag/v0.2.7 (`v0.2.7 🦚 [peacock]`) |
| 46 | +
|
| 47 | +### Using the Capsule Docker image |
| 48 | +> The documentation is a wip 🚧 |
| 49 | +
|
| 50 | +A "scratch" Docker image of Capsule exists on https://hub.docker.com/r/k33g/capsule-launcher/tags. You can find more details on the [capsule-docker-image](https://github.com/bots-garden/capsule-docker-image) project. |
| 51 | +This image will be used to deploy Capsule to CaaS or Kubernetes. You can use it directly to run a wasm function without installing Capsule: |
| 52 | + |
| 53 | +```bash |
| 54 | +docker run \ |
| 55 | + -p 8080:8080 \ |
| 56 | + -e MESSAGE="👋 Hello World 🌍" \ |
| 57 | + -v $(pwd):/app --rm k33g/capsule-launcher:0.2.6 \ |
| 58 | + /capsule \ |
| 59 | + -wasm=./app/index.wasm \ |
| 60 | + -mode=http \ |
| 61 | + -httpPort=8080 |
| 62 | +``` |
| 63 | + |
| 64 | + |
41 | 65 | 👋 You will find some **running examples** with these projects: |
42 | 66 | - https://github.com/bots-garden/capsule-launcher-demo |
43 | 67 | - https://github.com/bots-garden/capsule-hello-universe |
|
46 | 70 | > - https://github.com/bots-garden/capsule-samples |
47 | 71 | > - https://github.com/bots-garden/capsule-on-fly-dot-io |
48 | 72 |
|
49 | | -## Blog posts |
| 73 | +## Tooling |
| 74 | +> The documentation is a wip 🚧 |
50 | 75 |
|
| 76 | +To write and build wasm function for Capsule, you need to install GoLang and TinyGo. Otherwise, you can use the [capsule-function-builder](https://github.com/bots-garden/capsule-function-builder) project. It provides a very simple CLI, named **capsule-builder** or **cabu** that uses a Docker image with all the necessary resources (Golang and TinyGo compilers). |
| 77 | + |
| 78 | +### Install Capsule Builder |
| 79 | + |
| 80 | +```bash |
| 81 | +CAPSULE_BUILDER_VERSION="v0.0.0" |
| 82 | +wget -O - https://raw.githubusercontent.com/bots-garden/capsule-function-builder/${CAPSULE_BUILDER_VERSION}/install-capsule-builder.sh | bash |
| 83 | +``` |
| 84 | + |
| 85 | +Then you can generate a new project from a template: |
| 86 | + |
| 87 | +```bash |
| 88 | +# template name: `service-get` |
| 89 | +# function project name `hello-world` |
| 90 | +cabu generate service-get hello-world |
| 91 | +``` |
| 92 | + |
| 93 | + |
| 94 | +Then, build it easily: |
| 95 | + |
| 96 | +```bash |
| 97 | +cd hello-world |
| 98 | +cabu build . hello-world.go hello-world.wasm |
| 99 | +``` |
| 100 | + |
| 101 | +And, finally, serve it: |
| 102 | + |
| 103 | +```bash |
| 104 | +capsule \ |
| 105 | + -wasm=./hello-world.wasm \ |
| 106 | + -mode=http \ |
| 107 | + -httpPort=8080 |
| 108 | +``` |
| 109 | + |
| 110 | +## What's new |
| 111 | + |
| 112 | +- `v0.2.7`: |
| 113 | + - The FaaS components are externalized, now, this project is **only** for the **Capsule Runner** |
| 114 | + - "Scratch" Docker image (18.5M) to easily use and deploy the Capsule Runner (https://github.com/bots-garden/capsule-docker-image) |
| 115 | + - **cabu** (or **capsule-builder**) (https://github.com/bots-garden/capsule-function-builder): a CLI using a specific Docker image allowing: |
| 116 | + - the creation of a wasm function project (from templates) |
| 117 | + - the build of the wasm function, without installing anything (TinyGo is embedded in the image) (https://github.com/bots-garden/capsule-function-builder) |
| 118 | +>- `v0.2.6`: Wazero: updates to `1.0.0-pre.2` by [@codefromthecrypt](https://github.com/codefromthecrypt) + a logo |
| 119 | +>- `v0.2.5`: Add MQTT support by [@py4mac](https://github.com/py4mac) with `MqttPublish` & `MqttPublish` |
| 120 | +>- `v0.2.4`: Add 2 wasm helper functions `flatjson.StrToMap` and `flatjson.MapToStr` |
| 121 | +>- `v0.2.3`: NATS support, 2 new functions: `NatsReply` and `NatsConnectRequest` |
| 122 | +>- `v0.2.2`: like `0.2.1` with fixed modules dependencies, and tag name start with a `v` |
| 123 | +>- `0.2.1`: NATS support (1st stage) `OnNatsMessage`, `NatsPublish`, `NatsConnectPublish`, `NatsConnectPublish`, `NatsGetSubject`, `NatsGetServer` |
| 124 | +>- `0.2.0`: `OnLoad` & `OnExit` functions + Memory cache host functions (`MemorySet`, `MemoryGet`, `MemoryKeys`) |
| 125 | +>- `0.1.9`: Add `Request` and `Response` types (for the Handle function) |
| 126 | +>- `0.1.8`: Redis host functions: add the KEYS command (`RedisKeys(pattern string)`) |
| 127 | +
|
| 128 | +## Blog posts |
51 | 129 |
|
52 | 130 | - [Capsule, my personal wasm multi-tools knife (part 1)](https://www.wasm.builders/k33g_org/capsule-my-personal-wasm-multi-tools-knife-part-1-3eoa) |
53 | 131 | - [Capsule, my personal wasm FaaS (part 2)](https://www.wasm.builders/k33g_org/capsule-my-personal-wasm-faas-part-2-140k) |
|
0 commit comments