diff --git a/pages/developers/_meta.ts b/pages/developers/_meta.ts index dd6d98c..83d1aa4 100644 --- a/pages/developers/_meta.ts +++ b/pages/developers/_meta.ts @@ -19,6 +19,7 @@ const meta: Meta = { "tangle-avs": "Build a Tangle Blueprint", "eigenlayer-avs": "Build an Eigenlayer AVS", "testing-with-tangle": "Testing with Tangle", + deployment: "Deployment", troubleshooting: "Troubleshooting", "-- solution-developers": { type: "separator", diff --git a/pages/developers/cli/quickstart.mdx b/pages/developers/cli/quickstart.mdx index 7b06bcc..3d299c5 100644 --- a/pages/developers/cli/quickstart.mdx +++ b/pages/developers/cli/quickstart.mdx @@ -25,12 +25,4 @@ cargo tangle blueprint create --name ## Deploying your Blueprint -Once you're ready to deploy your blueprint, simply: - -```shell -export SIGNER="//Alice" -export EVM_SIGNER="0xcb6df9de1efca7a3998a8ead4e02159d5fa99c3e0d4fd6432667390bb4726854" -cargo tangle blueprint deploy tangle --devnet -``` - -See [deploy command reference](./tangle.mdx#deploying-a-blueprint) for all options. +See [Deployment](/developers/deployment/introduction) diff --git a/pages/developers/deployment/_meta.ts b/pages/developers/deployment/_meta.ts new file mode 100644 index 0000000..764ff3a --- /dev/null +++ b/pages/developers/deployment/_meta.ts @@ -0,0 +1,8 @@ +import { Meta } from "nextra"; + +const meta: Meta = { + introduction: "Introduction", + sources: "Sources", +}; + +export default meta; diff --git a/pages/developers/deployment/introduction.mdx b/pages/developers/deployment/introduction.mdx new file mode 100644 index 0000000..1ab3845 --- /dev/null +++ b/pages/developers/deployment/introduction.mdx @@ -0,0 +1,26 @@ +# Deploying Blueprints + +In order for a blueprint to be instance-able, it'll need to be deployed and have one or more sources defined. + +## Defining Sources + +Before deploying, you must specify the sources from which to fetch the blueprint binaries. +See [Sources](/developers/deployment/sources/introduction). + +## Deploying via the CLI + +Once you're ready to deploy your blueprint, simply: + +Install the [cargo-tangle] CLI, if you haven't already. + +For testing, you can deploy to a local devnet: + +```shell +export SIGNER="//Alice" +export EVM_SIGNER="0xcb6df9de1efca7a3998a8ead4e02159d5fa99c3e0d4fd6432667390bb4726854" +cargo tangle blueprint deploy tangle --devnet +``` + +See [deploy command reference](/developers/cli/tangle#deploying-a-blueprint) for all options. + +[cargo-tangle]: /developers/cli/installation diff --git a/pages/developers/deployment/sources/_meta.ts b/pages/developers/deployment/sources/_meta.ts new file mode 100644 index 0000000..e5d670e --- /dev/null +++ b/pages/developers/deployment/sources/_meta.ts @@ -0,0 +1,12 @@ +import { Meta } from "nextra"; + +const meta: Meta = { + introduction: "Introduction", + native: "Native", + container: "Container", + tee: "Trusted Execution Environment (WIP)", + wasm: "WASM (WIP)", + testing: "Testing", +}; + +export default meta; diff --git a/pages/developers/deployment/sources/container.mdx b/pages/developers/deployment/sources/container.mdx new file mode 100644 index 0000000..021a6fb --- /dev/null +++ b/pages/developers/deployment/sources/container.mdx @@ -0,0 +1,35 @@ +# Container Source + +The `Container` source is used for blueprints that are intended to be built as container images and published to image +registries, such as `docker.io`. + +## Requirements + +The requirements for running containerized blueprints are available [here](/operators/manager/requirements#container-sources) + +## Format + +The `Container` source has the following format: + +```rust +pub struct ContainerSource { + pub registry: String, + pub image: String, + pub tag: String, +} +``` + +Where: + +- `registry` - The registry to pull the image from (e.g., `docker.io`) +- `image` - The name of the image (e.g., `some-user/my-blueprint`) +- `tag` - The release tag of the image (e.g., `latest`) + +And they can be specified in the manifest of your binary crate like so: + +```toml +[package.metadata.blueprint] +sources = [ + { type = "Container", registry = "docker.io", image = "some-user/my-blueprint", tag = "latest" } +] +``` diff --git a/pages/developers/deployment/sources/introduction.mdx b/pages/developers/deployment/sources/introduction.mdx new file mode 100644 index 0000000..d09d7eb --- /dev/null +++ b/pages/developers/deployment/sources/introduction.mdx @@ -0,0 +1,22 @@ +# Blueprint Sources + +Blueprints can be built and distributed in multiple formats (visible on the sidebar). + +A blueprint can define many sources of different types in the manifest of its binary crate: + +```toml +[package.metadata.blueprint] +sources = [ + { type = "Container", registry = "docker.io", image = "some-user/my-blueprint", tag = "latest" }, + # Fallback container source + { type = "Container", registry = "ghcr.io", image = "some-user/my-blueprint", tag = "latest" }, + # Native binary source + { type = "Native", owner = "some-github-user", repo = "some-blueprint", tag = "0.1.0", binaries = [ + { arch = "Amd64", os = "Linux", name = "my-blueprint-bin" }, + ] }, +] +``` + +The above example has two container sources, which allows an operator to attempt a pull from different sources in the event +that one of the registries is unreachable. Additionally, it has a native source which can act as a fallback for operators +that either cannot or prefer not to support running containerized blueprints. diff --git a/pages/developers/deployment/sources/native.mdx b/pages/developers/deployment/sources/native.mdx new file mode 100644 index 0000000..6f7d0f5 --- /dev/null +++ b/pages/developers/deployment/sources/native.mdx @@ -0,0 +1,55 @@ +# Native Sources + +The `Native` source is used for blueprints that compile to a native binary and release via the [`release.yml`] GitHub workflow +from the blueprint template. + +## Requirements + +The requirements for running native blueprints are available [here](/operators/manager/requirements#native-sources) + +## Format + +The `Native` source has the following format: + +```rust +pub struct NativeSource { + pub owner: String, + pub repo: String, + pub tag: String, + pub binaries: Vec, +} + +pub struct BlueprintBinary { + pub arch: Architecture, + pub os: OperatingSystem, + pub name: String, +} +``` + +Where: + +- `owner` - The owner of the GitHub repository (e.g., `tangle-network`) +- `repo` - The name of the repository (e.g., `some-blueprint`) +- `tag` - The release tag of the binary (e.g., `0.1.0`) +- `binaries` - A list of binaries (e.g., see below) + +And in `BlueprintBinary`: + +- `arch` - The architecture the blueprint was built for (see [Architecture]) +- `os` - The operating system the blueprint was built for (see [OperatingSystem]) +- `name` - The name of the binary in the GitHub release (e.g., `my-blueprint-bin`) + +And they can be specified in the manifest of your binary crate like so: + +```toml +[package.metadata.blueprint] +sources = [ + { type = "Native", owner = "some-github-user", repo = "some-blueprint", tag = "0.1.0", binaries = [ + { arch = "Amd64", os = "Linux", name = "my-blueprint-bin" }, + ] }, +] +``` + +[`release.yml`]: https://github.com/tangle-network/blueprint-template/blob/main/.github/workflows/release.yml +[Architecture]: https://docs.rs/tangle-subxt/latest/tangle_subxt/tangle_testnet_runtime/api/runtime_types/tangle_primitives/services/sources/enum.Architecture.html +[OperatingSystem]: https://docs.rs/tangle-subxt/latest/tangle_subxt/tangle_testnet_runtime/api/runtime_types/tangle_primitives/services/sources/enum.OperatingSystem.html diff --git a/pages/developers/deployment/sources/tee.mdx b/pages/developers/deployment/sources/tee.mdx new file mode 100644 index 0000000..e719294 --- /dev/null +++ b/pages/developers/deployment/sources/tee.mdx @@ -0,0 +1,31 @@ +# Trusted Execution Environment Sources + +The `TEE` (Trusted Execution Environment) source is used for blueprints that are built as container images, and intended to +be deployed to a [dstack] TEE. + +## Requirements + +The requirements for running TEE blueprints are available [here](/operators/manager/requirements#tee-sources) + +## Format + +The `TEE` source has the following format: + +```rust +// TBD... +``` + +Where: + +- TODO + +And they can be specified in the manifest of your binary crate like so: + +```toml +[package.metadata.blueprint] +sources = [ + { type = "TEE", ... }, +] +``` + +[dstack]: https://github.com/Dstack-TEE/dstack diff --git a/pages/developers/deployment/sources/testing.mdx b/pages/developers/deployment/sources/testing.mdx new file mode 100644 index 0000000..6e80589 --- /dev/null +++ b/pages/developers/deployment/sources/testing.mdx @@ -0,0 +1,53 @@ +# Testing Source + +The `Testing` source is a special, automatically generated source that was historically used by the [Blueprint Manager] +during integration tests. It has since been replaced with the [test harnesses](/developers/testing/introduction). + +## Format + +The `Testing` source has the following format: + +```rust +pub struct TestingSource { + pub cargo_package: String, + pub cargo_bin: String, + pub base_path: String, +} +``` + +Where: + +- `cargo_package` - The Cargo package name of the binary (e.g., `my-blueprint-bin`) +- `cargo_bin` - The name of the built binary file (e.g., `my-blueprint-bin`) +- `base_path` - The base path of the binary crate (e.g., `/home/user/my-blueprint/bin`) + +And they can be specified in the manifest of your binary crate like so: + +```toml +[package.metadata.blueprint] +sources = [ + { type = "Testing", cargo_package = "some-package-name", cargo_bin = "some-binary", base_path = "/home/user/some-blueprint/bin" } +] +``` + +## Output + +After building your blueprint, you'll notice something like the following in your `blueprint.json`: + +```json +{ + // ... + "sources": [ + { + "type": "Testing", + "cargo_package": "my-blueprint-bin", + "cargo_bin": "my-blueprint-bin", + "base_path": "/home/user/my-blueprint/bin" + } + ], +} +``` + +It can safely be ignored (or deleted if you prefer). + +[Blueprint Manager]: /operators/manager/introduction diff --git a/pages/developers/deployment/sources/wasm.mdx b/pages/developers/deployment/sources/wasm.mdx new file mode 100644 index 0000000..06d282c --- /dev/null +++ b/pages/developers/deployment/sources/wasm.mdx @@ -0,0 +1,39 @@ +# WebAssembly Sources + +The `WASM` (WebAssembly) source is used for blueprints that are built as WASM binaries and intended to be executed in +a WASM runtime such as [Wasmtime]. + +## Requirements + +The requirements for running WASM blueprints are available [here](/operators/manager/requirements#wasm-sources) + +## Format + +The `WASM` source has the following format: + +```rust +pub struct WasmSource { + pub runtime: WasmRuntime, + pub fetcher: NativeSource, +} +``` + +Where: + +- `runtime` - The WASM runtime this blueprint is intended to execute in (see [WasmRuntime]) +- `fetcher` - The GitHub release information, identical to [NativeSource] + +And they can be specified in the manifest of your binary crate like so: + +```toml +[package.metadata.blueprint] +sources = [ + { type = "Wasm", runtime = "Wasmtime", fetcher = { owner = "some-github-user", repo = "some-blueprint", tag = "0.1.0", binaries = [ + { arch = "Wasm", os = "Unknown", name = "my-blueprint-bin" }, + ] } }, +] +``` + +[Wasmtime]: https://wasmtime.dev/ +[NativeSource]: /developers/deployment/sources/native#format +[WasmRuntime]: https://docs.rs/tangle-subxt/latest/tangle_subxt/tangle_testnet_runtime/api/runtime_types/tangle_primitives/services/sources/enum.WasmRuntime.html diff --git a/pages/operators/_meta.ts b/pages/operators/_meta.ts index feac451..7093f57 100644 --- a/pages/operators/_meta.ts +++ b/pages/operators/_meta.ts @@ -13,6 +13,7 @@ const meta: Meta = { type: "separator", title: "Blueprint Operators", }, + manager: "Blueprint Manager", operator: "Running an operator", pricing: "Pricing", benchmarking: "Blueprint Benchmarking", diff --git a/pages/operators/manager/_meta.ts b/pages/operators/manager/_meta.ts new file mode 100644 index 0000000..bb01124 --- /dev/null +++ b/pages/operators/manager/_meta.ts @@ -0,0 +1,8 @@ +import { Meta } from "nextra"; + +const meta: Meta = { + introduction: "Introduction", + requirements: "Requirements", +}; + +export default meta; diff --git a/pages/operators/manager/introduction.mdx b/pages/operators/manager/introduction.mdx new file mode 100644 index 0000000..101a5b3 --- /dev/null +++ b/pages/operators/manager/introduction.mdx @@ -0,0 +1,3 @@ +# Blueprint Manager + +TODO diff --git a/pages/operators/manager/requirements.mdx b/pages/operators/manager/requirements.mdx new file mode 100644 index 0000000..ff40a19 --- /dev/null +++ b/pages/operators/manager/requirements.mdx @@ -0,0 +1,56 @@ +# Runtime Requirements for the Blueprint Manager + +Blueprints can be executed in multiple ways (see [Sources](/developers/deployment/sources/introduction)), with each requiring +certain dependencies, and possibly hardware. + +## Native Sources + +There are two ways to run blueprints with [Native Sources](/developers/deployment/sources/native) in the +`blueprint-manager`: sandboxed (**recommended**) or not + +In either case, the following dependencies will be needed: + +- [GitHub CLI] (for binary attestations) + +Then additionally for the two execution methods: + +### Not Sandboxed + +No extra dependencies, the blueprint will run as a normal host process. + +### Sandboxed (**Linux Only**) + +- [cloud-hypervisor] + - Note, no additional setup of `cloud-hypervisor` needs to be done. The manager handles downloading the latest kernel + and disk images. Simply installing and adding it to `PATH` is enough. +- Allow `CAP_NET_ADMIN` for the `blueprint-manager` binary + - This can be done by running `setcap cap_net_admin+eip /path/to/blueprint-manager` + - **_or_** simply running the `blueprint-manager` as root (**not recommended**) + +## Container Sources + +The requirements for running blueprints with [Container Sources](/developers/deployment/sources/container) are: + +- [Kubernetes] +- [Docker] +- The [Kata Containers] runtime + +## TEE Sources (WIP, **Linux Only**) + +The requirements for running blueprints with [TEE Sources](/developers/deployment/sources/tee) are: + +- [dstack VMM] +- TODO? + +## WASM Sources (WIP) + +The requirements for running blueprints with [WASM Sources](/developers/deployment/sources/wasm) are: + +- TODO + +[GitHub CLI]: https://cli.github.com/ +[cloud-hypervisor]: https://www.cloudhypervisor.org/ +[Kubernetes]: https://kubernetes.io/ +[Docker]: https://www.docker.com/get-started/ +[Kata Containers]: https://katacontainers.io/ +[dstack VMM]: https://github.com/Dstack-TEE/dstack/tree/master?tab=readme-ov-file#-getting-started