Add SSH documentation to the website. (#692)

website/docs.md

@@ -11,6 +11,7 @@ single command.
 
 ```console
 $ go run .                       # Run locally.
+$ weaver ssh deploy weaver.toml  # Run on multiple machines.
 $ weaver gke deploy weaver.toml  # Run on Google Cloud.
 $ weaver kube deploy weaver.toml # Run on Kubernetes.
 ```
@@ -63,6 +64,7 @@ USAGE
   weaver version                  // show weaver version
   weaver single    <command> ...  // for single process deployments
   weaver multi     <command> ...  // for multiprocess deployments
+  weaver ssh       <command> ...  // for multimachine deployments
   ...
 ```
 
@@ -527,7 +529,7 @@ Cloud Tracing][cloud_trace], etc.
   demonstrate what Service Weaver has to offer.
 - Dive deeper into the various ways you can deploy a Service Weaver application,
   including [single process](#single-process), [multiprocess](#multiprocess),
-  [GKE](#gke) and [Kube](#kube) deployers.
+  [SSH](#ssh), [GKE](#gke) and [Kube](#kube) deployers.
 - Check out [Service Weaver's source code on GitHub][weaver_github].
 - Chat with us on [Discord](https://discord.gg/FzbQ3SM8R5) or send us an
   [email](serviceweaver@google.com).
@@ -3089,6 +3091,131 @@ slowly shifts traffic from old versions of the application to the new version of
 the application. You can use `weaver gke-local status`, exactly like how you use
 `weaver gke status`, to monitor the rollouts of your applications.
 
+# SSH [experimental]
+
+[SSH][ssh] is a deployer that allows you to run Service Weaver applications on
+a set of machines reachable via `ssh`. Note that the `SSH` deployer runs your
+application's components as standalone OS processes, so you don't need
+[Kubernetes][kubernetes], [Docker][docker], etc.
+
+## Getting Started
+
+Prerequisites:
+* A set of machines reachable via `ssh`.
+* You may want to set up passwordless `ssh` between your machines, otherwise you
+will have to type the password for each machine when you deploy/stop an application.
+
+Consider again the "Hello, World!" Service Weaver application from the [Step by
+Step Tutorial](#step-by-step-tutorial) section. The application runs an HTTP
+server on a listener named `hello` with a `/hello?name=<name>` endpoint that
+returns a `Hello, <name>!` greeting. To deploy this application using the `SSH`
+deployer, first create a [Service Weaver application config file](#config-files),
+say `weaver.toml`, with the following contents:
+
+```toml
+[serviceweaver]
+binary = "./hello"
+
+[ssh]
+listeners.hello = {address = "localhost:9000"}
+locations = "./ssh_locations.txt"
+```
+
+The `[serviceweaver]` section of the config file specifies the compiled Service
+Weaver binary. The `[ssh]` section contains the set of machines where your
+application should be deployed, as well as per listener configuration. The set of
+machines is specified as follows in `ssh_locations.txt`:
+
+```txt
+10.100.12.31
+10.100.12.32
+10.100.12.33
+...
+```
+
+Deploy the application using `weaver ssh deploy`:
+
+```console
+$ weaver ssh deploy weaver.toml
+```
+
+When `weaver ssh deploy` terminates (e.g., when you press `ctrl+c`), the
+application is destroyed and all processes are terminated.
+
+## Logging
+
+`weaver ssh logs` logs to stdout. Refer to `weaver ssh logs --help` for details.
+
+## Metrics
+
+Run `weaver ssh dashboard` to open a dashboard in a web browser. The
+dashboard has a page for every Service Weaver application deployed via `weaver ssh deploy`.
+Every deployment's page has a link to the deployment's [metrics](#metrics).
+The metrics are exported in [Prometheus format][prometheus] and looks something
+like this:
+
+```txt
+# Metrics in Prometheus text format [1].
+#
+# To visualize and query the metrics, make sure Prometheus is installed on
+# your local machine and then add the following stanza to your Prometheus yaml
+# config file:
+#
+# scrape_configs:
+# - job_name: 'prometheus-serviceweaver-scraper'
+#   scrape_interval: 5s
+#   metrics_path: /debug/serviceweaver/prometheus
+#   static_configs:
+#     - targets: ['127.0.0.1:43087']
+#
+# [1]: https://prometheus.io
+
+# HELP example_count An example counter.
+# TYPE example_count counter
+example_count{serviceweaver_node="bbc9beb5"} 42
+example_count{serviceweaver_node="00555c38"} 9001
+
+# ┌─────────────────────────────────────┐
+# │ SERVICEWEAVER AUTOGENERATED METRICS │
+# └─────────────────────────────────────┘
+# HELP serviceweaver_method_count Count of Service Weaver component method invocations
+# TYPE serviceweaver_method_count counter
+serviceweaver_method_count{caller="main",component="main.Example",serviceweaver_node="9fa07495",method="Foo"} 0
+serviceweaver_method_count{caller="main",component="main.Example",serviceweaver_node="ee76816d",method="Foo"} 1
+...
+```
+
+As the header explains, you can visualize and query the metrics by installing
+Prometheus and configuring it, using the provided stanza, to periodically scrape
+the `/debug/serviceweaver/prometheus` endpoint of the provided target
+(`127.0.0.1:43087` in the example above). You can also inspect the metrics
+manually. The metrics page shows the latest value of every metric in your
+application followed by [the metrics that Service Weaver automatically creates
+for you](#metrics-auto-generated-metrics).
+
+## Tracing
+
+Run `weaver ssh dashboard` to open a dashboard in a web browser. The
+dashboard has a page for every Service Weaver application deployed via `weaver ssh deploy`.
+Every deployment's page has a link to the deployment's [traces](#tracing)
+accessible via [Perfetto][perfetto]. This is similar to how you access the traces
+when using the [single process](#single-process) or the [multiprocess](#multiprocess) deployer.
+
+Refer to [Perfetto UI Docs](https://perfetto.dev/docs/visualization/perfetto-ui)
+to learn more about how to use the tracing UI.
+
+## Limitations
+
+**Note** that the `SSH` deployer is not production ready yet, but rather it serves
+as a playground to deploy a Service Weaver application on a set of machines. We
+welcome contributions to make it production ready. Some limitations:
+
+* Each component is deployed on all the machines.
+* No scale up/down mechanism based on health/load signals.
+* Slow rollouts not supported.
+* `weaver ssh profile` command not implemented.
+* No integration with existing frameworks to export logs, metrics and traces.
+
 # Serializable Types
 
 When you invoke a component's method, the arguments to the method (and the
@@ -3416,6 +3543,7 @@ runtime benefits of microservices.
 [prometheus_histogram]: https://prometheus.io/docs/concepts/metric_types/#histogram
 [prometheus_naming]: https://prometheus.io/docs/practices/naming/
 [sql_package]: https://pkg.go.dev/database/sql
+[ssh]: https://github.com/ServiceWeaver/weaver/tree/main/internal/tool/ssh
 [trace_service]: https://cloud.google.com/trace
 [update_failures_paper]: https://scholar.google.com/scholar?cluster=4116586908204898847
 [weak_consistency]: https://mwhittaker.github.io/consistency_in_distributed_systems/1_baseball.html

website/index.html

@@ -87,6 +87,7 @@ <h1>Step 3: Deploy Your Components</h1>
 ```shell
 $ go test .                       # Test locally.
 $ go run .                        # Run locally.
+$ weaver ssh deploy weaver.toml   # Run on multiple machines.
 $ weaver gke deploy weaver.toml   # Run on Google Cloud.
 $ weaver kube deploy weaver.toml  # Run on Kubernetes.
 </markdown>

website/news.html

@@ -31,6 +31,10 @@
   const NOVEMBER = 10;
   const DECEMBER = 11;
   const items = [
+    {
+      date: new Date(2023, DECEMBER, 19),
+      text: 'We added documentation on how to use the <a href="./docs.html#ssh-experimental">SSH</a> deployer to deploy Service Weaver applications across a set of machines reachable via ssh. Note that the deployer is missing some features; we welcome contributions :).',
+    },
     {
       date: new Date(2023, DECEMBER, 13),
       text: '<a href="https://kaichu.io/about/">Kai-Chu</a> talked about Service Weaver at <a href="https://twitter.com/GDGTaichung/status/1731666673894375794/photo/1">DevFest Taichung</a>. Thanks Kai-Chu.',