diff --git a/astro.config.mjs b/astro.config.mjs index eb4e212..80d549f 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -40,9 +40,14 @@ export default defineConfig({ { label: 'πŸ‘‹ Welcome', link: '/' }, { label: 'πŸ€” Why Choose It?', link: '/why-choose' }, { label: '🀝 Who Participates?', link: '/who-participates' }, + { label: 'πŸ‡ Quick Start', link: '/quick-start' }, { - label: 'πŸ—οΈ Getting Started', - autogenerate: { directory: 'getting-started' }, + label: 'πŸ§‘β€πŸ’» Every CLI', + autogenerate: { directory: 'everycli' }, + }, + { + label: 'πŸ—οΈ Manual Setup', + autogenerate: { directory: 'manual-setup' }, }, // { // label: 'πŸŽ›οΈ Control Panel', diff --git a/src/content/docs/assets/quickstart-1.jpg b/src/content/docs/assets/quickstart-1.jpg new file mode 100644 index 0000000..0ba9bb0 Binary files /dev/null and b/src/content/docs/assets/quickstart-1.jpg differ diff --git a/src/content/docs/assets/quickstart-2.jpg b/src/content/docs/assets/quickstart-2.jpg new file mode 100644 index 0000000..40dfadb Binary files /dev/null and b/src/content/docs/assets/quickstart-2.jpg differ diff --git a/src/content/docs/everycli/index.md b/src/content/docs/everycli/about.md similarity index 78% rename from src/content/docs/everycli/index.md rename to src/content/docs/everycli/about.md index b879fe1..482f021 100644 --- a/src/content/docs/everycli/index.md +++ b/src/content/docs/everycli/about.md @@ -1,9 +1,9 @@ --- -title: Every CLI -description: The Every CLI is a developer tool that includes a local gateway server +title: About the Every CLI +description: The Every CLI is the fastest way to get started writing and running functions on the Everywhere Computer --- -Every CLI is an experimental CLI for developers written in JavaScript. It has a set of convenience functions for interacting with Homestar and the Everywhere Computer control panel. +The Every CLI is the fastest way to get started writing and running functions on the Everywhere Computer. It has a set of convenience functions for interacting with Homestar and the Everywhere Computer control panel. More info in the Github repo, including usage: https://github.com/everywhere-computer/every-cli @@ -29,8 +29,6 @@ This will eventually migrate to published functions available through the contro ## API Gateway -Running the CLI locally will start a Homestar node, API gateway, and local control panel[^ipfs]. +Running the CLI locally will start a Homestar node, API gateway, and local control panel. Integration with Cloudflare Tunnels will expose this as a live public endpoint. This means you can build apps and other experiences that are running on compute from your local Homestar node. - -[^ipfs]: Follow the [setup your local node](/getting-started/setup-your-local-node/#prepare-ipfs) instructions to run IPFS locally. diff --git a/src/content/docs/everycli/local-dev.md b/src/content/docs/everycli/local-dev.mdx similarity index 87% rename from src/content/docs/everycli/local-dev.md rename to src/content/docs/everycli/local-dev.mdx index c4bc44c..53f3bc7 100644 --- a/src/content/docs/everycli/local-dev.md +++ b/src/content/docs/everycli/local-dev.mdx @@ -1,21 +1,20 @@ --- -title: Every CLI Local Development -description: The Every CLI is a developer tool that includes a local gateway server +title: Every CLI Usage +description: The Every CLI is a developer tool that includes a local gateway server. --- +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +:::tip[Before you continue] +To get setup, please follow our [Quick Start](../quick-start) guide. +::: + ## Installation ```shell npm i -g @everywhere-computer/every-cli ``` -## Usage - -### Prerequisites - -1. Ensure you have the IPFS daemon running via [ipfs daemon](https://docs.ipfs.tech/how-to/command-line-quick-start/#take-your-node-online) or [IPFS Desktop](https://docs.ipfs.tech/install/ipfs-desktop/) -2. Create a custom TS or Wasm function, or clone TS examples repo [github.com/everywhere-computer/custom-homestar-functions-ts](https://github.com/everywhere-computer/custom-homestar-functions-ts). - ### Creating the Everywhere Computer environment Running the Every CLI will start a [Homestar](/homestar/what-is-homestar/) node, API gateway, CloudFlare tunnel and locally running copy of the Everywhere Computer [control panel](https://control.everywhere.computer). @@ -38,7 +37,8 @@ every dev --fn --fn + ### Creating TypeScript functions Write a TypeScript function with clearly specified argument and return types @@ -59,7 +59,8 @@ Start the CLI and point it to your custom TypeScript function ```shell every cli dev --fn /hello.ts ``` - + + ### Creating Wasm functions in Rust Init a new function lib using [cargo](https://github.com/rust-lang/cargo?tab=readme-ov-file#installing-cargo) @@ -134,6 +135,8 @@ Install [wasm-tools](https://github.com/bytecodealliance/wasm-tools) the generat ```shell wasm-tools component new ./target/wasm32-unknown-unknown/debug/hello.wasm -o ./hello.wasm ``` + + Start the CLI and point it to your custom Wasm function diff --git a/src/content/docs/getting-started/write-a-custom-function.md b/src/content/docs/getting-started/write-a-custom-function.md deleted file mode 100644 index 457434e..0000000 --- a/src/content/docs/getting-started/write-a-custom-function.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Write a Custom Function -description: Write a custom function to add to your workflow. -sidebar: - order: 4 ---- - -COMING SOON diff --git a/src/content/docs/index.md b/src/content/docs/index.md index d3d7b51..0a5da80 100644 --- a/src/content/docs/index.md +++ b/src/content/docs/index.md @@ -14,7 +14,7 @@ With high resilience, fast execution, and zero deployment: * **Run** your own nodes or rent from ours * **Extend** capabilities with any [UCAN](https://ucan.xyz)-enabled service -## Built on open protocols +## It's built on open protocols [IPVM](https://fission.codes/ipvm/), the InterPlanetary Virtual Machine, offers a seamless, secure, and open environment for WebAssembly functions. Leveraging content-addressed data, PKI, and capabilities, it ensures computational freedom and interoperability, avoiding lock-in with any single cloud provider. @@ -22,6 +22,6 @@ With high resilience, fast execution, and zero deployment: ## Where do I begin? -Jump right in and follow our [Getting Started](getting-started/setup-your-local-node) guide to begin experimenting with a local node. If you're curious about what's coming next, check out our [Roadmap](https://github.com/orgs/everywhere-computer/projects/1/views/1). +Jump right in and follow our [Quick Start](quick-start) guide to begin experimenting with a local node. If you're curious about what's coming next, check out our [Roadmap](https://github.com/orgs/everywhere-computer/projects/1/views/1). Or, if you'd like to learn more about the Everywhere Computer ecosystem, read on... \ No newline at end of file diff --git a/src/content/docs/manual-setup/access-control-panel.md b/src/content/docs/manual-setup/access-control-panel.md new file mode 100644 index 0000000..b22085c --- /dev/null +++ b/src/content/docs/manual-setup/access-control-panel.md @@ -0,0 +1,14 @@ +--- +title: Access the Control Panel +description: You'll manage your Homestar node and its view of the Everywhere Computer network via the Control Panel. +sidebar: + order: 4 +--- + +You'll manage your Homestar node and its view of the Everywhere Computer network via the Control Panel: [control.everywhere.computer](https://control.everywhere.computer/) + +Now that Everywhere Computer (via `homestar`) and IPFS (via `kubo`) are running locally, it's time to experiment by [running a workflow](../run-a-workflow). + +:::note[Want to run it local?] +The exercises in our Getting Started guides are written for the hosted version of the control panel, for ease of setup. In the spirit of local-first software, of course you can also [run it locally](../control-panel/running-it-locally). +::: \ No newline at end of file diff --git a/src/content/docs/getting-started/customize-a-workflow.md b/src/content/docs/manual-setup/customize-a-workflow.md similarity index 96% rename from src/content/docs/getting-started/customize-a-workflow.md rename to src/content/docs/manual-setup/customize-a-workflow.md index b444337..7951560 100644 --- a/src/content/docs/getting-started/customize-a-workflow.md +++ b/src/content/docs/manual-setup/customize-a-workflow.md @@ -4,7 +4,7 @@ description: Learn the basics of building and customizing workflows for the Everywhere Computer. sidebar: - order: 3 + order: 5 --- Docs coming soon. In the meantime, FAFO by clicking `+ New Workflow` at: [https://control.everywhere.computer/workflows/](https://control.everywhere.computer/workflows/) diff --git a/src/content/docs/manual-setup/index.md b/src/content/docs/manual-setup/index.md new file mode 100644 index 0000000..9c12955 --- /dev/null +++ b/src/content/docs/manual-setup/index.md @@ -0,0 +1,20 @@ +--- +title: Intro +description: Write and run your first custom functions on the Everywhere Computer. +sidebar: + order: 1 +--- + +:::tip[Before you continue] +We highly recommend following the [Quick Start](../quick-start) guide that makes use of the `every cli`, which is the path we will be putting more energy into supporting in the near future. + +However, this Manual Setup guide does contain additional information about the platform, which may be helpful for a deeper understanding of the system. +::: + +This Getting Started guide will help you manually: + +1. **Prepare** IPFS on your local machine β€” a dependency of the Everywhere Computer +2. **Setup** your local node +3. **Access** the Everywhere Computer control panel +4. **Run & Customize** workflows +6. **Write** custom functions in JavaScript, Rust or Python diff --git a/src/content/docs/manual-setup/prepare-ipfs.md b/src/content/docs/manual-setup/prepare-ipfs.md new file mode 100644 index 0000000..ef8b37a --- /dev/null +++ b/src/content/docs/manual-setup/prepare-ipfs.md @@ -0,0 +1,19 @@ +--- +title: Prepare IPFS +description: IPFS helps make the Everywhere Computer portable and durable. +sidebar: + order: 2 +--- + +The Everywhere Computer is both portable and durable. These two traits are made possible by [IPFS’ content addressing](https://fission.codes/blog/content-addressing-what-it-is-and-how-it-works/) and WebAssembly's ability to execute in _any_ environment β€” including browsers. + +## 1. Install IPFS + +Just as the Everywhere Computer is powered by Homestar nodes, IPFS is powered by kubo nodes β€” the GoLang IPFS implementation. You have two options for installing it: + +1. Install the kubo binary directly: [https://docs.ipfs.tech/install/command-line/#install-official-binary-distributions](https://docs.ipfs.tech/install/command-line/#install-official-binary-distributions) +2. or, install IPFS Desktop GUI which includes kubo: [https://docs.ipfs.tech/install/ipfs-desktop/](https://docs.ipfs.tech/install/ipfs-desktop/) + +## 2. Run IPFS + +Make sure kubo is running! Either by launching IPFS Desktop, or running `ipfs daemon` in your terminal. \ No newline at end of file diff --git a/src/content/docs/getting-started/run-a-workflow.md b/src/content/docs/manual-setup/run-a-workflow.md similarity index 99% rename from src/content/docs/getting-started/run-a-workflow.md rename to src/content/docs/manual-setup/run-a-workflow.md index 8624235..f56a655 100644 --- a/src/content/docs/getting-started/run-a-workflow.md +++ b/src/content/docs/manual-setup/run-a-workflow.md @@ -4,7 +4,7 @@ description: Now that the Everywhere Computer is running on your machine, let's run a workflow. sidebar: - order: 2 + order: 4 --- The Everywhere Computer works by running workflows: sequences of functions you'll write to accomplish your compute jobs. They can be big. They can be small. They can run in isolation. They can be composed together. diff --git a/src/content/docs/getting-started/setup-your-local-node.mdx b/src/content/docs/manual-setup/setup-your-local-node.mdx similarity index 52% rename from src/content/docs/getting-started/setup-your-local-node.mdx rename to src/content/docs/manual-setup/setup-your-local-node.mdx index 183f3d8..1b30c40 100644 --- a/src/content/docs/getting-started/setup-your-local-node.mdx +++ b/src/content/docs/manual-setup/setup-your-local-node.mdx @@ -2,39 +2,14 @@ title: Setup Your Local Node description: Get the Everywhere Computer✡ up and running on your local machine. sidebar: - order: 1 + order: 3 --- import { Tabs, TabItem } from '@astrojs/starlight/components'; -The **Everywhere Computer** is powered by [Homestar](https://github.com/ipvm-wg/homestar) nodes β€” a reference implementation of the [IPVM](https://github.com/ipvm-wg) protocol. This guide will help you: +The **Everywhere Computer** is powered by [Homestar](https://github.com/ipvm-wg/homestar) nodes β€” our implementation of the [IPVM](https://github.com/ipvm-wg) protocol. -1. **Prepare** IPFS on your local machine β€” a dependency of the Everywhere Computer -2. **Setup** your local Homestar node -3. **Access** the Everywhere Computer control panel - -## Prepare IPFS - -The Everywhere Computer is both portable and durable. These two traits are made possible by [IPFS’ content addressing](https://fission.codes/blog/content-addressing-what-it-is-and-how-it-works/) and WebAssembly's ability to execute in _any_ environment β€” including browsers. - -### 1. Install IPFS - -Just as the Everywhere Computer is powered by Homestar nodes, IPFS is powered by kubo nodes β€” the GoLang IPFS implementation. You have two options for installing it: - -1. Install the kubo binary directly: [https://docs.ipfs.tech/install/command-line/#install-official-binary-distributions](https://docs.ipfs.tech/install/command-line/#install-official-binary-distributions) -2. or, install IPFS Desktop GUI which includes kubo: [https://docs.ipfs.tech/install/ipfs-desktop/](https://docs.ipfs.tech/install/ipfs-desktop/) - -### 2. Run IPFS - -Make sure kubo is running! Either by launching IPFS Desktop, or running `ipfs daemon` in your terminal. - -## Install Homestar - -:::caution -🚧 This is still under very active development! 🚧 -::: - -To install your first Everywhere Computer `Homestar` node, we recommend the cross-platform approach via npm. +To setup your local `Homestar` node, we highly recommend using `Node`. @@ -98,16 +73,4 @@ We can now start the node by running: homestar start -c ./settings.toml --db ./homestar.db ``` -**🧟 It's alive! 🧟** - -## Access the Control Panel - -You'll manage your Homestar node and its view of the Everywhere Computer network via the Control Panel: [control.everywhere.computer](https://control.everywhere.computer/) - -Now that Everywhere Computer (via `homestar`) and IPFS (via `kubo`) are running locally, it's time to experiment by [running a workflow](../run-a-workflow). - -{/* -:::note[Want to run it local?] -The exercises in our Getting Started guides are written for the hosted version of the control panel, for ease of setup. In the spirit of local-first software, of course you can also [run it locally](../control-panel/running-it-locally). -::: -*/} +**🧟 It's alive! 🧟** \ No newline at end of file diff --git a/src/content/docs/quick-start.md b/src/content/docs/quick-start.md new file mode 100644 index 0000000..1b59c96 --- /dev/null +++ b/src/content/docs/quick-start.md @@ -0,0 +1,94 @@ +--- +title: Quick Start +description: Use the `every cli` to write and run custom functions within 5 minutes. +--- + +Get introduced to the Everywhere Computer's core concepts while using the `every cli` to write and run custom functions on your local machine: + +```shell +npm i -g @everywhere-computer/every-cli +``` + +## Setup & Run a Local IPFS Node + +The Everywhere Computer is both portable and durable. These two traits are made possible by [IPFS’ content addressing](https://fission.codes/blog/content-addressing-what-it-is-and-how-it-works/) and WebAssembly's ability to execute in _any_ environment β€” including browsers. + +If you are not already running an IPFS Kubo node on your local machine: +1. Download & install the [IPFS Desktop](https://docs.ipfs.tech/install/ipfs-desktop/) client. +2. Launch the IPFS Desktop client β€” this will ensure an IPFS node is running on your local machine. + +## Run Your First Function + +Clone down our [custom TypeScript functions repo](https://github.com/everywhere-computer/custom-homestar-functions-ts). In the `src/functions` directory you'll find four *very* basic functions: +1. `add.ts` - adds two numbers together +2. `concat.ts` - concatenates two strings +3. `hello.ts` - a simple `hello ${world}` +4. `message-and-number.ts` - concatenates together a string and a number + +### Boot Up The Everywhere Computer + +Let's beging with `hello.ts`. From the root directory of the repository run: + +```shell +every dev --fn src/functions/hello.ts +``` + +This should produce an output like the following in your terminal: +```bash +βœ” Functions parsed and compiled +βœ” Homestar is running at http://127.0.0.1:8020 +βœ” Control Panel is running at http://127.0.0.1:4173 + +◐ Starting cloudflared tunnel to http://127.0.0.1:3000/ + +... a QR code ... + +➜ Local: http://127.0.0.1:3000/ +➜ Tunnel: https://sometimes-comical-word-set.trycloudflare.com +``` + +Everything is now ready to run your function: +1. **The function has been compiled to WebAssembly (Wasm)** which is the Everywhere Computer's native format. +2. **A local Homestar node** is running β€” these are what power the Everything Computer. +3. **A local instance of the Control Panel** is running so that we can interact with our local Homestar node. +4. **A Cloudflare tunnel** has been opened, enabling your function to be called over the public internet via an HTTP Gateway. + +### Run `hello` From The Control Panel + +Visit your local Control Panel at [http://127.0.0.1:4173](http://127.0.0.1:4173). You should see the following interface: + +![The Control Panel](./assets/quickstart-1.jpg) + +Enter a name and hit the "Run" button. You should see your first result! + +You may have noticed it took a moment to compile the result. Because of the Everywhere Computer's memoization, that result is now cached. If you hit run again, it should be nearly instantaneous β€” we skipped straight to the result. + +### Run `hello` From Your Phone + +Take out your phone and scan the QR code from your terminal. This will open the Cloudflare tunnel on your device. + +Append `hello?name=Gary` to the url (eg. https://YOUR-TUNNEL-URL/hello?name=test). Because of the content type of the response, your browser will likely download (or prompt you to download) a text file that reads "Hello Gary". + +Congrats! You've just run the Everywhere Computer over the internet. + +## Write A Multi-Function Workflow + +When you called that first sample function, it was wrapped with the input you proved as a `task` and executed as part of a `workflow`: a sequence of functions that define compute jobs to be run on the Everywhere Computer. Just to repeat: + +1. **A Function:** The code you've written that accepts inputs and returns an output +2. **A Task:** Function + a specific set of Inputs +3. **A Workflow:** Multiple tasks run in sequence + +Workflows can be big. They can be small. They can run in isolation. They can be composed together. + +Let's construct a two task workflow to test this out. To do this, we'll instruct the cli to compile both the `hello` and `concat` functions: + +```shell +every dev --fn src/functions/hello.ts --fn src/functions/concat.ts +``` + +![A Multi-Function Workflow](./assets/quickstart-2.jpg) + +## Next Steps + +For additional instructions on local development with the `every cli` β€” including writing custom functions in TypeScript and Rust β€” check out [Every CLI Usage](/everycli/local-dev). \ No newline at end of file