diff --git a/README.md b/README.md index 85fa03c..269553d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,198 @@ -# spin-v2-quickstart +#+title: quickstart to the spin wasm build +#+date:[2023-11-16 Thu] +#+author: HaQadosch +#+startup: indent +#+note: based on https://developer.fermyon.com/spin/v2/quickstart +* Org shortcuts +- create footnote :: ~C-c C-x f~ +- jump to the footnote ref :: ~C-c C-c~ +* Setup +** 1: Install +#+description: check if ~spin~ is installed +#+name: installed? +#+begin_src shell + spin -V +#+end_src -Based on https://developer.fermyon.com/spin/v2/quickstart \ No newline at end of file +#+RESULTS: installed? +: spin 2.0.1 (1d72f1c 2023-11-10) + +If it is not installed, ~curl~ the shell file. Make sure to install it in your +path, something like =/usr/local/bin=. +#+description: installing spin +#+name: install spin +#+begin_src shell + curl -fsSL https://developer.fermyon.com/downloads/install.sh | bash + sudo mv ./spin /usr/local/bin/spin +#+end_src +** 2: Using templates +The shell script in first step installs the template. If this is missing, use +~spin~. +#+description: installing the templates +#+name: templates install +#+begin_src shell + # Rust templates + spin templates install --git https://github.com/fermyon/spin --update + rustup target add wasm32-wasi + # Typescript to Wasm + spin plugins update + spin plugins install js2wasm --yes + spin templates install --git https://github.com/fermyon/spin-js-sdk --update +#+end_src + +* Creating the App +** Spin new +We use ~spin new~ with the =http-ts= template to create the skeleton of a new +*Spin application* +#+description: spin a new app using http-ts template +#+name: new http-ts template +#+begin_src shell + spin new -t http-ts # We can do http-js for pure javascript +#+end_src +When prompted, enter: +- =name= :: hi +- =description= :: says hi +- =path= :: /hi + + +A new folder has been created with the =name= of the application. +#+description: content of the spin application folder +#+name: content folder +#+begin_src shell + cd hi/ + tree +#+end_src + +#+RESULTS: content folder +| . +| ├── package.json +| ├── README.md +| ├── spin.toml +| ├── src +| │   └── index.ts +| ├── tsconfig.json +| └── webpack.config.js +| +| 2 directories, 6 files + +** Manifest file +The =spin.toml= is the *manifest* for the application. It tells *spin* what +*events* should trigger what *components* + +#+begin_src toml + spin_manifest_version = 2 + + [application] + authors = ["haqadosch"] + description = "says hi" + name = "hi" + version = "0.1.0" + + [[trigger.http]] + route = "/hi" + component = "hi" + + [component.hi] + source = "target/hi.wasm" + exclude_files = ["**/node_modules"] + [component.hi.build] + command = "npm run build" +#+end_src +We can see that the app is configured to trigger the component "hi" at the route +"/hi". Any other routes will be ignored. +* Build the application +** Install the node modules +Since this is a *typesccript* app, we need to ~npm install~ everything. This is +no different than any other node app, in the same folder as =package.json=, the +root folder, do the install. +#+description: installing the node modules for the app +#+name: npm install +#+begin_src shell + npm install +#+end_src +** Build the spin app +To run the *build* instruction for all the *components* defined is the +*manifest* file, +#+begin_src shell + spin build +#+end_src + +The ~spin build~ command is a shortcut of the build command in the *manifest* +#+begin_src toml + [component.hi.build] + command = "npm run build" +#+end_src +That means you can directly type ~npm run build~ in the root folder instead of +~spin build~. +** Run the application +You can spin up the application by running the following command +#+name: spin up +#+begin_src shell + cd hi + spin up +#+end_src + +#+RESULTS: spin up +| Logging component stdio to .spin/logs/ +| +| Serving http://127.0.0.1:3000 +| Available Routes: +| hi: http://127.0.0.1:3000/hi + +Visiting the URL =http://localhost:3000/hi= will display the message +"Hello from TS-SDK". + +You can log the activity of the app by setting the *environment variable* +~RUST_LOG~. This variable is independent of the template used for the app. +#+description: logging app activity +#+name: rust_log +#+begin_src shell + export RUST_LOG=spin=trace + spin up +#+end_src + +By visiting the same URL as before, you can see the following logs +#+begin_src shell + 2023-11-16T21:46:59.858033Z DEBUG spin_loader::cache: using cache root directory .cache/spin/registry + 2023-11-16T21:46:59.859288Z TRACE spin_cli::commands::up: Running trigger executor: SPIN_LOCAL_APP_DIR="" SPIN_LOCKED_URL="file:///tmp/spinup-Chh8Cn/spin.lock" SPIN_WORKING_DIR="/tmp/spinup-Chh8Cn" "/usr/local/bin/spin" "trigger" "http" + Logging component stdio to ".spin/logs/" + 2023-11-16T21:47:00.272884Z TRACE spin_trigger_http: Constructed router for application hi: [(Exact("/hi"), "hi")] + + Serving http://127.0.0.1:3000 + 2023-11-16T21:47:00.273007Z INFO spin_trigger_http: Serving http://127.0.0.1:3000 + Available Routes: + hi: http://127.0.0.1:3000/hi + 2023-11-16T21:47:07.785975Z INFO spin_trigger_http: Processing request for application hi on URI http://localhost:3000/hi + 2023-11-16T21:47:07.786012Z TRACE spin_trigger_http::handler: Executing request using the Spin executor for component hi + 2023-11-16T21:47:07.790199Z INFO spin_trigger_http::handler: Request finished, sending response with status code 200 OK + 2023-11-16T21:47:07.887633Z INFO spin_trigger_http: Processing request for application hi on URI http://localhost:3000/favicon.ico +#+end_src +* Deploy the application +** Login +Make sure you're logged in with *Github* first. Once done the deployment +process can start. +#+description: deploying +#+name: spin deploy +#+begin_src shell + spin deploy +#+end_src + +#+RESULTS: spin deploy +Copy your one-time code: + +djqIipGu + +...and open the authorization page in your browser: + +https://cloud.fermyon.com/device-authorization + +Waiting for device authorization... +Device authorized! +Uploading hi version 0.1.0 to Fermyon Cloud... +Deploying... +Waiting for application to become ready............ ready +Available Routes: + hi: https://hi-7tx.fermyon.app/hi +** Running the app in the cloud +Now visiting https://hi-7tx.fermyon.app/hi will display the same message. +The [[https://cloud.fermyon.com/][Fermyon Cloud]] has a dashboard for your app. diff --git a/README.org b/README.org new file mode 100644 index 0000000..269553d --- /dev/null +++ b/README.org @@ -0,0 +1,198 @@ +#+title: quickstart to the spin wasm build +#+date:[2023-11-16 Thu] +#+author: HaQadosch +#+startup: indent +#+note: based on https://developer.fermyon.com/spin/v2/quickstart +* Org shortcuts +- create footnote :: ~C-c C-x f~ +- jump to the footnote ref :: ~C-c C-c~ +* Setup +** 1: Install +#+description: check if ~spin~ is installed +#+name: installed? +#+begin_src shell + spin -V +#+end_src + +#+RESULTS: installed? +: spin 2.0.1 (1d72f1c 2023-11-10) + +If it is not installed, ~curl~ the shell file. Make sure to install it in your +path, something like =/usr/local/bin=. +#+description: installing spin +#+name: install spin +#+begin_src shell + curl -fsSL https://developer.fermyon.com/downloads/install.sh | bash + sudo mv ./spin /usr/local/bin/spin +#+end_src +** 2: Using templates +The shell script in first step installs the template. If this is missing, use +~spin~. +#+description: installing the templates +#+name: templates install +#+begin_src shell + # Rust templates + spin templates install --git https://github.com/fermyon/spin --update + rustup target add wasm32-wasi + # Typescript to Wasm + spin plugins update + spin plugins install js2wasm --yes + spin templates install --git https://github.com/fermyon/spin-js-sdk --update +#+end_src + +* Creating the App +** Spin new +We use ~spin new~ with the =http-ts= template to create the skeleton of a new +*Spin application* +#+description: spin a new app using http-ts template +#+name: new http-ts template +#+begin_src shell + spin new -t http-ts # We can do http-js for pure javascript +#+end_src +When prompted, enter: +- =name= :: hi +- =description= :: says hi +- =path= :: /hi + + +A new folder has been created with the =name= of the application. +#+description: content of the spin application folder +#+name: content folder +#+begin_src shell + cd hi/ + tree +#+end_src + +#+RESULTS: content folder +| . +| ├── package.json +| ├── README.md +| ├── spin.toml +| ├── src +| │   └── index.ts +| ├── tsconfig.json +| └── webpack.config.js +| +| 2 directories, 6 files + +** Manifest file +The =spin.toml= is the *manifest* for the application. It tells *spin* what +*events* should trigger what *components* + +#+begin_src toml + spin_manifest_version = 2 + + [application] + authors = ["haqadosch"] + description = "says hi" + name = "hi" + version = "0.1.0" + + [[trigger.http]] + route = "/hi" + component = "hi" + + [component.hi] + source = "target/hi.wasm" + exclude_files = ["**/node_modules"] + [component.hi.build] + command = "npm run build" +#+end_src +We can see that the app is configured to trigger the component "hi" at the route +"/hi". Any other routes will be ignored. +* Build the application +** Install the node modules +Since this is a *typesccript* app, we need to ~npm install~ everything. This is +no different than any other node app, in the same folder as =package.json=, the +root folder, do the install. +#+description: installing the node modules for the app +#+name: npm install +#+begin_src shell + npm install +#+end_src +** Build the spin app +To run the *build* instruction for all the *components* defined is the +*manifest* file, +#+begin_src shell + spin build +#+end_src + +The ~spin build~ command is a shortcut of the build command in the *manifest* +#+begin_src toml + [component.hi.build] + command = "npm run build" +#+end_src +That means you can directly type ~npm run build~ in the root folder instead of +~spin build~. +** Run the application +You can spin up the application by running the following command +#+name: spin up +#+begin_src shell + cd hi + spin up +#+end_src + +#+RESULTS: spin up +| Logging component stdio to .spin/logs/ +| +| Serving http://127.0.0.1:3000 +| Available Routes: +| hi: http://127.0.0.1:3000/hi + +Visiting the URL =http://localhost:3000/hi= will display the message +"Hello from TS-SDK". + +You can log the activity of the app by setting the *environment variable* +~RUST_LOG~. This variable is independent of the template used for the app. +#+description: logging app activity +#+name: rust_log +#+begin_src shell + export RUST_LOG=spin=trace + spin up +#+end_src + +By visiting the same URL as before, you can see the following logs +#+begin_src shell + 2023-11-16T21:46:59.858033Z DEBUG spin_loader::cache: using cache root directory .cache/spin/registry + 2023-11-16T21:46:59.859288Z TRACE spin_cli::commands::up: Running trigger executor: SPIN_LOCAL_APP_DIR="" SPIN_LOCKED_URL="file:///tmp/spinup-Chh8Cn/spin.lock" SPIN_WORKING_DIR="/tmp/spinup-Chh8Cn" "/usr/local/bin/spin" "trigger" "http" + Logging component stdio to ".spin/logs/" + 2023-11-16T21:47:00.272884Z TRACE spin_trigger_http: Constructed router for application hi: [(Exact("/hi"), "hi")] + + Serving http://127.0.0.1:3000 + 2023-11-16T21:47:00.273007Z INFO spin_trigger_http: Serving http://127.0.0.1:3000 + Available Routes: + hi: http://127.0.0.1:3000/hi + 2023-11-16T21:47:07.785975Z INFO spin_trigger_http: Processing request for application hi on URI http://localhost:3000/hi + 2023-11-16T21:47:07.786012Z TRACE spin_trigger_http::handler: Executing request using the Spin executor for component hi + 2023-11-16T21:47:07.790199Z INFO spin_trigger_http::handler: Request finished, sending response with status code 200 OK + 2023-11-16T21:47:07.887633Z INFO spin_trigger_http: Processing request for application hi on URI http://localhost:3000/favicon.ico +#+end_src +* Deploy the application +** Login +Make sure you're logged in with *Github* first. Once done the deployment +process can start. +#+description: deploying +#+name: spin deploy +#+begin_src shell + spin deploy +#+end_src + +#+RESULTS: spin deploy +Copy your one-time code: + +djqIipGu + +...and open the authorization page in your browser: + +https://cloud.fermyon.com/device-authorization + +Waiting for device authorization... +Device authorized! +Uploading hi version 0.1.0 to Fermyon Cloud... +Deploying... +Waiting for application to become ready............ ready +Available Routes: + hi: https://hi-7tx.fermyon.app/hi +** Running the app in the cloud +Now visiting https://hi-7tx.fermyon.app/hi will display the same message. +The [[https://cloud.fermyon.com/][Fermyon Cloud]] has a dashboard for your app.