docs: start adding docs on walrus sites

docs/SUMMARY.md

@@ -31,6 +31,17 @@
 
 # Walrus sites
 
+- [Introduction to Walrus Sites](./walrus-sites/intro.md)
+- [Your first Walrus Site](./walrus-sites/tutorial.md)
+  - [Installing the site builder](./walrus-sites/tutorial-install.md)
+  - [Using the site builder](./walrus-sites/tutorial-use.md)
+  - [Configuring the site builder](./walrus-sites/tutorial-config.md)
+  - [Bonus: Set a SuiNS name](./walrus-sites/tutorial-suins.md)
+- [Technical overview](./walrus-sites/overview.md)
+  - [The site builder]()
+  - [The Walrus Sites Portal]()
+  - [Known restrictions](./walrus-sites/restrictions.md)
+
 ---
 
 [Glossary](./glossary.md)

docs/walrus-sites/intro.md

@@ -0,0 +1,62 @@
+# Introduction to Walrus Sites
+
+_Walrus Sites_ are "web"-sites that use Sui and Walrus as their underlying technology. They are a
+prime example of how Walrus can be used to build new and exciting decentralized applications. Anyone
+can build and deploy a Walrus Site, and make it accessible to the World!
+
+At a high level, the most exciting features include:
+
+- Publishing a site does not require managing servers or complex configurations; just provide the
+  source files (produced by your favorite web framework), publish them to Walrus Sites using the
+  [site builder tool](./site-builder.md), and you are done!
+- Sites can be linked to from ordinary Sui objects. This feature enables, for example, creating a
+  NFT collection in which _every single NFT_ has a _personalized website dedicated to it_.
+- Walrus Sites are owned by addresses on Sui, and can be exchanged, shared, and updated thanks to
+  Sui's flexible programming model. This means, among other things, that Walrus Sites can leverage
+  the [SuiNS](https://suins.io/) naming system to have human readable names. No more messing around
+  with DNS!
+- Thanks to Walrus' decentralization and extremely high data availability, there is no risk of
+  having your site wiped for no reason.
+- Since they live on Walrus, these sites cannot have a backend in the traditional sense, and can be
+  therefore considered "static" sites. However, the developer can harness the Sui's programmability
+  to add backend functionality to Walrus Sites!
+
+## Show me
+
+To give you a very high level intuition of how Walrus Sites work, let's look at an example: A simple
+NFT collection on Sui, that has a frontend dApp to mint the NFTs hosted on Walrus Sites, and in
+which _each NFT_ has a _specific, personalized Walrus Site_.
+
+You can check out the mint page at
+[https://flatland.walrus.site/](https://flatland.walrus.site/). This site is serve to your browser
+through the Walrus Site _Portal_ [https://walrus.site](https://walrus.site). While the Portal's
+operation is explained in a [later section](./portal.md), consider for now that there
+can be many Portals (hosted by whomever wants to have their own, and even on `localhost`). Further,
+the only function of the Portal is to provide the browser with some code (specifically, a service
+worker) that allows it to fetch the Walrus Site from Sui and Walrus.
+
+If you have a Sui wallet with some Testnet SUI, you can try and "mint a new Flatlander" from the
+site. This creates an NFT from the collection, and shows you two links, one to the explorer, and one
+to the "Flatlander site". This latter site is a special Walrus Site that exists only for that NFT,
+and has special characteristics (the background color, the image...) that are based on the contents
+of the NFT.
+
+The URL to this per-NFT site look something like this
+`https://4egmmrw9izzjn0dm2lkd3k0l8phk386z60ub1tpdc1jswbb5dr.walrus.site/`.  You'll notice that the
+domain remains `walrus.site`, but the subdomain is a long and random-looking string.  This string is
+actually the [Base36](https://en.wikipedia.org/wiki/Base36) encoding of the object ID of the NFT,
+which is
+[0xb09b312b...](https://suiscan.xyz/testnet/object/0xb09b312b28049467dd6173b6cebb60ed5fe3046883e248632bf9fb20b7dbdaff).
+
+In summary:
+
+- Walrus Sites are served through a portal; in this case, `https://walrus.site`. There can be many
+  portal, and anyone can host one.
+- The subdomain on the URL points to a specific object on Sui, that allows the browser to fetch and
+  render the site resources. This pointer can be:
+  - A SuiNS name, such as `flatland` in `https://flatland.walrus.site`; or
+  - the Base36 encoding of a the Sui object ID, such as `0xb09b312b...` in the example above.
+
+Curious to know how this magic is possible? Read the [technical
+overview](./overview.md)! If you just want to get started try Walrus Sites out, check the
+[tutorial](./tutorial.md).

docs/walrus-sites/overview.md

@@ -0,0 +1 @@
+# Overview

docs/walrus-sites/restrictions.md

@@ -0,0 +1,63 @@
+# Known restrictions
+
+Walrus Sites can be used to deploy almost any form of traditional
+static "Web 2" website build for modern browsers. There are, however,
+a number of restrictions that a developer should keep in mind when
+creating or porting a website to Walrus Sites.
+
+## No secret values
+
+Walrus Sites are fully publicly accessible, as the metadata is stored
+on Sui and the site content is stored on Walrus. Therefore, developers
+_must_ not store secret values within the sites.
+
+We emphasize again that any such backend-specific operations (storing
+secret values, authentication, etc.) are achievable by leveraging the
+integration with Sui blockchain and the Sui wallet.
+
+## There is a maximum redirect depth
+
+The number of consecutive [redirects](./walrus-sites/) a Walrus Site
+can perform is capped by the Portal (see [Portal configuration]()).
+This measure ensure that loading a Walrus Site does not result in an
+infinite loading loop.
+
+Different Portals can set this limit as they desire. The limit for the
+Portal hosted at [walrus.site](http://walrus.site) has a maximum
+redirect depth of 3.
+
+## Service workers are not available
+
+<div class="warning">
+This limitation only applies to Portal based on service workers. A web
+Portal will not have this limitation.
+</div>
+
+Walrus Sites leverage service workers in the clients' browsers to
+perform the essential operations of:
+
+1. reading the site metadata from Sui;
+1. fetching the page content from Walrus; and
+1. serving the content to the browser.
+
+Therefore, a site deployed on Walrus Sites cannot use service
+workers. Installing a service worker from within a Walrus Site will
+result is a dysfunctional site and a poor experience for the user.
+
+## The iOS Sui Wallet Mobile does not work with Walrus Sites
+
+<div class="warning">
+This limitation only applies to Portal based on service workers. A web
+Portal will not have this limitation.
+</div>
+
+Service workers cannot be loaded inside an in-app browser on iOS,
+because of a limitation of the WebKit engine. As a consequence, Walrus
+Sites cannot be used within the [Sui Wallet
+Mobile](https://apps.apple.com/us/app/sui-wallet-mobile/id6476572140)
+app on iOS, and therefore using the Sui wallet on a Walrus Site is
+currently impossible. Note, however, that _browsing_ a Walrus Site is
+still possible on iOS through any browser. Only the connection to the
+wallet is impacted.
+
+The connection with the Sui Wallet Mobile app works on Android devices.

docs/walrus-sites/tutorial-config.md

@@ -0,0 +1,33 @@
+# Configuring the site builder
+
+Configuring the `site-builder` tool is straightforward, but care is required to ensure that
+everything works correctly.
+
+The `site-builder` tool requires a configuration file to know which package to use on Sui, which
+wallet to use, the gas budget, and other operational details. Most of these are abstracted away
+through sensible defaults, so you should not need to touch them. Yet, for completeness, we provide
+here the details for all the configuration options.
+
+## Minimal configuration
+
+The config file is expected to be in `./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 assets/config-example.yaml`, which is already configured appropriately
+
+## Advanced configuration
+
+If you want to have more control over the behavior of the site builder, you can customize the
+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`.
+- `module`: the name of the module in the Walrus Sites package [default: `site`].
+- `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`].
+- `general`: these are general options, that can be configured both through the CLI and the config:
+  - `rpc_url`: The URL of the RPC to use. If not set, the `site-builder` will infer it from the wallet.
+  - `wallet`: Pointer to the Sui wallet to be used. By default, it uses???
+  - `walrus_binary`: Pointer to the `walrus` binary. By default, this is expected to be run from `$PATH`.
+  - `walrus_config`: The configuration for the `walrus` client binary. See [the relative documentation](TODO: link).
+  - `gas_budget`: The maximum amount of gas to be spent for transactions [default: 500M MIST].
+  - `gas_coin`: The gas coin to be used to pay for the transaction (TODO: remove).

docs/walrus-sites/tutorial-install.md

@@ -0,0 +1,146 @@
+# Installing the site builder
+
+We describe here the steps necessary to setup the Walrus Sites' `site-builder` tool, and prepare
+your environment for development.
+
+## Prerequisites
+
+Before you start, make sure you:
+
+- Have a recent version of [Rust](https://www.rust-lang.org/tools/install) installed; and
+- have the [Sui CLI](https://docs.sui.io/guides/developer/getting-started/sui-install) installed.
+
+Then, follow these additional setup steps.
+
+## Get the `walrus` binary and install it
+
+Download the [latest `walrus` binary](TODO: link) for your architecture, and add it to your
+`$PATH`. For example, on MacOS you can copy it to `/Users/myusername/.local/bin/` (check what
+directories are in your `$PATH` by running `echo $PATH`).
+
+Once this is done, you should be able to type `walrus` in your terminal and see:
+
+```
+Walrus client
+
+Usage: walrus [OPTIONS] <COMMAND>
+
+Commands:
+  store       Store a new blob into Walrus
+  read        Read a blob from Walrus, given the blob ID
+  publisher   Run a publisher service at the provided network address
+  aggregator  Run an aggregator service at the provided network address
+  daemon      Run a client daemon at the provided network address, combining
+                  the functionality of an aggregator and a publisher
+  info        Print information about the Walrus storage system this client
+                  is connected to
+  json        Run the client by specifying the arguments in a JSON string;
+                  CLI options are ignored
+  blob-id     Encode the specified file to obtain its blob ID
+  help        Print this message or the help of the given subcommand(s)
+
+Options:
+  -c, --config <CONFIG>
+          The path to the wallet configuration file.
+  -w, --wallet <WALLET>
+          The path to the Sui wallet configuration file.
+  -g, --gas-budget <GAS_BUDGET>
+          The gas budget for transactions [default: 500000000]
+  -h, --help
+          Print help (see more with '--help')
+  -V, --version
+          Print version
+
+```
+
+If, for any reason, you don't want to add `walrus` to `$PATH`, place the binary in your preferred
+directory, and remember to configure a pointer to the binary in the `site-builder` config (more on
+this later).
+
+## Point your Sui CLI to testnet, and get some SUI
+
+Walrus is currently deployed on Sui Testnet. Therefore, you have to ensure that your Sui CLI is
+configured accordingly:
+
+```
+sui client envs
+╭──────────┬──────────────────────────────────────┬────────╮
+│ alias    │ url                                  │ active │
+├──────────┼──────────────────────────────────────┼────────┤
+│ devnet   │ https://fullnode.devnet.sui.io:443   │        │
+│ local    │ http://127.0.0.1:9000                │        │
+│ testnet  │ https://fullnode.testnet.sui.io:443/ │ *      │
+│ mainnet  │ https://fullnode.mainnet.sui.io:443  │        │
+╰──────────┴──────────────────────────────────────┴────────╯
+```
+
+Further, make sure you have at least 2 separate gas coins, with at least 1 SUI each, by running `sui
+client gas`.  If you don't have enough SUI, you can hit the testnet faucet by running.
+
+```
+sui client faucet --url https://faucet.testnet.sui.io/v1/gas
+```
+
+After some seconds, running again `sui client gas` should show the newly-minted coins in your
+wallet.
+
+## Clone the Walrus Sites repo, and build the `site-builder` tool
+
+TODO: do we want to provide the binary for the site builder too?
+
+First clone and enter the [Walrus Sites repo](https://github.com/MystenLabs/blocksite-poc). (TODO: change link to public repo when available).
+
+``` bash
+git clone [email protected]:MystenLabs/blocksite-poc.git
+cd blocksite-poc
+cd site-builder
+```
+
+Build the release version of the site builder.
+
+``` bash
+cargo build --release
+```
+
+After the build process completes, it should be possible to run:
+
+```
+./target/release/site-builder
+```
+
+And output should look like the following:
+
+```
+Usage: site-builder [OPTIONS] <COMMAND>
+
+Commands:
+  publish  Publish a new site on Sui
+  update   Update an existing site
+  convert  Convert an object ID in hex format to the equivalent Base36
+               format
+  sitemap  Show the pages composing the Walrus site at the given object ID
+  help     Print this message or the help of the given subcommand(s)
+
+Options:
+  -c, --config <CONFIG>
+          The path to the configuration file for the site builder [default:
+          config.yaml]
+      --rpc-url <RPC_URL>
+          The URL or the RPC endpoint to connect the client to
+      --wallet <WALLET>
+          The path to the Sui Wallet config
+      --walrus-binary <WALRUS_BINARY>
+          The path or name of the walrus binary
+      --walrus-config <WALRUS_CONFIG>
+          The path to the configuration for the Walrus client
+  -g, --gas-budget <GAS_BUDGET>
+          The gas budget for the operations on Sui
+      --gas-coin <GAS_COIN>
+          The gas coin to be used
+  -h, --help
+          Print help (see more with '--help')
+```
+
+## Get the latest `walrus` client configuration
+
+TODO: get it from the gcp bucket and copy it to the site builder directory

docs/walrus-sites/tutorial-suins.md

@@ -0,0 +1 @@
+# Bonus: Set a SuiNS name

docs/walrus-sites/tutorial-use.md

@@ -0,0 +1 @@
+# Using the site builder

docs/walrus-sites/tutorial.md

@@ -0,0 +1,4 @@
+# Your first Walrus Site
+
+This tutorial walks you through the steps necessary to publish a Walrus Site. We also provide the
+instructions on how to add a SuiNS name to it for convenient browsing.