docs(walrus-sites): update stable branch mentions to refer to testnet (…

…#181) * Mention that testnet is the stable branch * Use admonish danger instead of markdown note * Add git checkout testnet * Update portal.md * Remove redundant blank line * Remove redundant blank lines * Apply editor config edits to fix lint errs * Mention package upgrades happening * Fix portal.html admonish snippet * Update assets/example-config.yaml to sites-config.yaml * Update site-builder installation tutorial * Remove old header * Minor fixes * Improve tutorial install * Change location of the admonish danger location * Rephrase * Update the tutorial-publish to use the example WS repo * Fix deployment * Minor fixes * Update builder-config.md * Rename cli to CLI Co-authored-by: giac-mysten <[email protected]> * Table formatting and alignment Co-authored-by: giac-mysten <[email protected]> * Update site SC package to latest Co-authored-by: giac-mysten <[email protected]> * Move --config before publish Co-authored-by: giac-mysten <[email protected]> * Rephrase: But -> However Co-authored-by: giac-mysten <[email protected]> * Add admonish info about site-builder config & stand. loc * Add comma to sentence Co-authored-by: giac-mysten <[email protected]> * Move admonish note about s-builder configs to tut-install * Replace walrus default locations link * Fix * Fix line lengths on tutorial-install * Fix line lengths in tutorial-publish * chore: fixe line length Signed-off-by: giac-mysten <[email protected]> * fix: formatting Signed-off-by: giac-mysten <[email protected]> --------- Signed-off-by: giac-mysten <[email protected]> Co-authored-by: giac-mysten <[email protected]> Co-authored-by: giac-mysten <[email protected]>
MystenLabs · Dec 16, 2024 · 664638f · 664638f
1 parent 7fca07a
commit 664638f
Show file tree

Hide file tree

Showing 5 changed files with 127 additions and 39 deletions.
diff --git a/docs/walrus-sites/builder-config.md b/docs/walrus-sites/builder-config.md
@@ -10,9 +10,11 @@ here the details for all the configuration options.
 
 ## Minimal configuration
 
-The config file is expected to be in `./sites-config.yaml`, and it is possible to point elsewhere
-with the `--config` flag. For your first run, it should be sufficient to call the `site-builder`
-with `--config sites-config.yaml`, which is already configured appropriately.
+The config file is expected to be in one of the [default
+locations](../usage/setup.html#config-custom-path), and it is possible to point elsewhere with the
+`--config` flag. For your first run, it should be sufficient to call the `site-builder` without
+specifying the config explicitly, which is already configured if you followed thoroughly the
+[installation steps](./tutorial-install.html#configuration).
 
 If, for any reason, you didn't add `walrus` to `$PATH`, make sure to configure a pointer to the
 binary, see below.
@@ -23,10 +25,10 @@ If you want to have more control over the behavior of the site builder, you can
 following variables in the config file:
 
 - `package`: the object ID of the Walrus Sites package on Sui. This must always be specified in the
-  config, and is already appropriately configured in `assets/example-config.yaml`.
+  config, and is already appropriately configured in `./sites-config.yaml`.
 - `portal`: the name of the portal through which the site will be viewed; this only affects the
-  output of the CLI, and nothing else (default: `walrus.site`).
-  All Walrus Sites are accessible through any portal independent of this setting.
+  output of the CLI, and nothing else (default: `walrus.site`). All Walrus Sites are accessible
+  through any portal independent of this setting.
 - `general`: these are general options that can be configured both through the CLI and the config:
   - `rpc_url`: The URL of the Sui RPC node to use. If not set, the `site-builder` will infer it from
     the wallet.
@@ -37,3 +39,8 @@ following variables in the config file:
   - `walrus_config`: The configuration for the `walrus` client binary, see the [relevant
     chapter](../usage/setup.md).
   - `gas_budget`: The maximum amount of gas to be spent for transactions (default: 500M MIST).
+
+```admonish note
+From time to time there are package upgrades happening. This will require you to
+update the `package` field in the config file.
+```
diff --git a/docs/walrus-sites/commands.md b/docs/walrus-sites/commands.md
@@ -4,8 +4,7 @@ We now describe in more detail the commands available through the site builder.
 
 ```admonish tip
 In general, the `--help` flag is your friend, you can add it to get further details for the whole
-CLI (`./target/release/site-builder --help`) or individual commands (e.g.,
-`./target/release/site-builder update --help`).
+CLI (`site-builder --help`) or individual commands (e.g. `site-builder update --help`).
 ```
 
 ## `publish`

diff --git a/docs/walrus-sites/portal.md b/docs/walrus-sites/portal.md
@@ -11,6 +11,10 @@ portals:
 Currently, the server-side and service-workers portals are available at <https://blob.store> and
 <https://walrus.site>, respectively.
 
+```admonish danger title="Walrus Sites stable branch"
+The stable branch of Walrus Sites is `testnet`.
+```
+
 ## Running the portal locally
 
 You can run a service-worker portal locally if you want to browse Walrus Sites without accessing
@@ -19,6 +23,12 @@ external portals or for development purposes.
 This requires having the [`pnpm`](https://pnpm.io/) tool installed. To start, clone the
 `walrus-sites` repo and enter the `portal` directory. Here, run
 
+Make sure you are on the stable branch:
+
+``` sh
+git checkout testnet
+```
+
 ``` sh
 cd portal
 pnpm install

diff --git a/docs/walrus-sites/tutorial-install.md b/docs/walrus-sites/tutorial-install.md
@@ -8,30 +8,53 @@ prepare your environment for development.
 Before you start, make sure you
 
 - have a recent version of [Rust](https://www.rust-lang.org/tools/install) installed;
-- have `git` installed; and
 - followed all [Walrus setup instructions](../usage/setup.md).
 
 Then, follow these additional setup steps.
 
-## Clone the repository and build the `site-builder` tool
+## Installation
 
-First, clone and enter the Walrus Sites repo from <https://github.com/MystenLabs/walrus-sites>:
+Similar to the `walrus` client CLI tool, we currently provide the `site-builder` client binary for
+macOS (Intel and Apple CPUs), Ubuntu, and Windows:
 
-``` sh
-git clone https://github.com/MystenLabs/walrus-sites.git
-cd walrus-sites
+| OS      | CPU                   | Architecture |
+|---------|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| Ubuntu  | Intel 64bit           | [`ubuntu-x86_64`](https://storage.googleapis.com/mysten-walrus-binaries/site-builder-testnet-latest-ubuntu-x86_64)                |
+| Ubuntu  | Intel 64bit (generic) | [`ubuntu-x86_64-generic`](https://storage.googleapis.com/mysten-walrus-binaries/site-builder-testnet-latest-ubuntu-x86_64-generic)|
+| MacOS   | Apple Silicon         | [`macos-arm64`](https://storage.googleapis.com/mysten-walrus-binaries/site-builder-testnet-latest-macos-arm64)                    |
+| MacOS   | Intel 64bit           | [`macos-x86_64`](https://storage.googleapis.com/mysten-walrus-binaries/site-builder-testnet-latest-macos-x86_64)                  |
+| Windows | Intel 64bit           | [`windows-x86_64.exe`](https://storage.googleapis.com/mysten-walrus-binaries/site-builder-testnet-latest-windows-x86_64.exe)      |
+
+```admonish title="Windows"
+We now offer a pre-built binary also for Windows. However, most of the remaining instructions assume
+a UNIX-based system for the directory structure, commands, etc. If you use Windows, you may need to
+adapt most of those.
 ```
 
-Then, build the release version of the site builder:
+You can download the latest build from our Google Cloud Storage (GCS) bucket (correctly setting the
+`$SYSTEM` variable):
 
 ``` sh
-cargo build --release
+SYSTEM= # set this to your system: ubuntu-x86_64, ubuntu-x86_64-generic, macos-x86_64, macos-arm64, windows-x86_64.exe
+curl https://storage.googleapis.com/mysten-walrus-binaries/site-builder-testnet-latest-$SYSTEM -o site-builder
+chmod +x site-builder
+```
+
+To be able to run it simply as `site-builder`, move the binary to any directory included in your
+`$PATH` environment variable. Standard locations are `/usr/local/bin/`, `$HOME/bin/`, or
+`$HOME/.local/bin/`.
+
+```admonish note
+The site builder will look for the default configuration file `sites-config.yaml` in the current
+directory, the `$XDG_HOME/walrus/sites-config.yaml` and `$HOME/walrus/sites-config.yaml` directory.
+In case you want to use explicitly a different `sites-config.yaml`, use the `--config` flag to
+specify the path to the configuration file.
 ```
 
-After the build process completes, you are ready to run the site builder:
+Once this is done, you should be able to simply type `site-builder` in your terminal.
 
 ```terminal
-$ ./target/release/site-builder
+$ site-builder
 Usage: site-builder [OPTIONS] <COMMAND>
 
 Commands:
@@ -44,3 +67,49 @@ Commands:
 
   ⋮
 ```
+
+## Configuration
+
+The `site-builder` tool needs a configuration file to work. This file is called `sites-config.yaml`
+and looks like this:
+
+```yaml
+# module: site
+# portal: walrus.site
+package: 0xdf9033cac39b7a9b9f76fb6896c9fc5283ba730d6976a2b1d85ad1e6036c3272
+# general:
+#   rpc_url: https://fullnode.testnet.sui.io:443
+#   wallet: /path/to/.sui/sui_config/client.yaml
+#   walrus_binary: /path/to/walrus
+#   walrus_config: /path/to/devnet_deployment/client_config.yaml
+#   gas_budget: 500000000
+```
+
+As you can see, the configuration file is quite simple. The only mandatory field is the `package`
+field, which represents the Sui object ID of the Walrus Sites smart contract. You can find the
+latest version of the package in the [Walrus Sites
+repository](https://github.com/MystenLabs/walrus-sites/tree/testnet) on the `testnet` branch.
+
+```admonish danger title="Walrus Sites stable branch"
+The stable branch of Walrus Sites is `testnet`.
+Make sure that you always pull the latest changes from there.
+```
+
+You can define the location of the `sites-config.yaml` file using the `--config` flag when running
+the `site-builder` commands like so:
+
+``` sh
+site-builder --config /path/to/sites-config.yaml publish <build-directory-of-a-site>
+```
+
+However, if are not a fan of repeating the same flags over and over, it's always easier to have the
+configuration file in one of the [default locations](./tutorial-install.html#admonition-note).
+
+Download the `sites-config.yaml` file from the repository, and place it in one of the aforementioned
+default locations. To illustrate, we will use the `~/.config/walrus` directory, like so:
+
+```sh
+curl https://raw.githubusercontent.com/MystenLabs/walrus-sites/refs/heads/testnet/sites-config.yaml -o ~/.config/walrus/sites-config.yaml
+```
+
+You are now ready to start working on your Walrus Sites! 🎉
diff --git a/docs/walrus-sites/tutorial-publish.md b/docs/walrus-sites/tutorial-publish.md
@@ -1,37 +1,39 @@
 # Publishing a Walrus Site
 
-Now that everything is installed and configured, you should be able to start publishing
-your first Walrus Site!
+Now that everything is installed and configured, you should be able to start publishing your first
+Walrus Site!
 
 ## Select the source material for the site
 
 The `site-builder` works by uploading a directory of files produced by any web framework to Walrus
 and adding the relevant metadata to Sui. This directory should have a file called `index.html` in
 its root, which will be the entry point to the Walrus Site.
 
-For the rest of the tutorial, we will use as an example the simple site contained in
-`./examples/snake`.
+There is a very useful [example-Walrus-sites](https://github.com/MystenLabs/example-walrus-sites)
+repository that contains multiple kinds of sites that you can use for reference.
+
+For simplicity, we will start by publishing the most frugal of the sites, the `walrus-snake` game.
+
+First, clone the repository of examples:
+
+``` sh
+git clone https://github.com/MystenLabs/example-walrus-sites.git && cd walrus-snake/
+```
 
 ## Publish the site
 
-Since we have placed the `walrus` binary and configuration in their default locations, publishing
-the `./examples/snake` site is as simple as calling the publishing command:
+Since we have placed the `walrus` and `site-builder` binaries and configuration in their default
+locations, publishing the `./walrus-snake` site is as simple as calling the publishing command:
 
 ``` sh
-./target/release/site-builder publish ./examples/snake --epochs 100
+site-builder publish ./walrus-snake --epochs 100
 ```
 
 ``` admonish tip
 Currently on Walrus testnet, the duration of an epoch is 1 day. If you want your site to stay up
 longer, specify the number of epochs with the `--epochs` flag!
 ```
 
-```admonish note
-The site builder will look for the default configuration file `sites-config.yaml` in the
-`./walrus-sites` directory. In case you are calling the `site-builder` command from a different
-location, use the `--config` flag to specify the path to the configuration file.
-```
-
 The end of the output should look like the following:
 
 ``` txt
@@ -50,12 +52,13 @@ Browse the resulting site at: https://1lupgq2auevjruy7hs9z7tskqwjp5cc8c5ebhci4v5
 
 This output tells you that, for each file in the folder, a new Walrus blob was created, and the
 respective blob ID. Further, it prints the object ID of the Walrus Site object on Sui (so you can
-have a look in the explorer and use it to set the SuiNS name) and, finally, the URL at which you
-can browse the site.
+have a look in the explorer and use it to set the SuiNS name) and, finally, the URL at which you can
+browse the site.
 
-Note here that we are passing the default config `./sites-config.yaml` as the config for the site
-builder. The configuration file is necessary to ensure that the `site-builder` knows the correct Sui
-package for the Walrus Sites logic.
+Note here that we are implicitly using the default `sites-config.yaml` as the config for the site
+builder that we set up previously on the [installation section](./tutorial-install.html). The
+configuration file is necessary to ensure that the `site-builder` knows the correct Sui package for
+the Walrus Sites logic.
 
 More details on the configuration of the `site-builder` can be found under the [advanced
 configuration](./builder-config.md) section.
@@ -65,14 +68,14 @@ configuration](./builder-config.md) section.
 Let's say now you want to update the content of the site, for example by changing the title from
 "eat all the blobs!" to "Glob all the Blobs!".
 
-First, make this edit on in the `./examples/snake/index.html` file.
+First, make this edit on in the `./walrus-snake/index.html` file.
 
 Then, you can update the existing site by running the `update` command, providing the directory
-where to find the updated files (still `./example/snake`) and the object ID of the existing site
+where to find the updated files (still `./walrus-snake`) and the object ID of the existing site
 (`0x407a3081...`):
 
 ``` sh
-./target/release/site-builder update --epochs 100 examples/snake  0x407a3081...
+site-builder update --epochs 100 ./walrus-snake  0x407a3081...
 ```
 
 The output this time should be: