add guide for running the visualization (#376)

closes #375

balancer-design.typ

@@ -74,7 +74,7 @@ In Rust, packages are called "crates". The Balancer and Harness is split into mu
 	caption: figure.caption("External Rust dependencies required for all workspace crates", position: top)
 )
 
-== Development Environment
+== Development Environment <Section::dev-env>
 
 #let text-box = box.with(
 	inset: 1em,

data/dev-env/balancer.docker.toml

@@ -0,0 +1,6 @@
+api_key = "<randomly generate this, alphanumeric>"
+
+[discovery]
+method = "dns"
+service_port = 3002
+query = "opentogethertube"

data/dev-env/balancer.no-docker.toml

@@ -0,0 +1,8 @@
+api_key = "<randomly generate this>"
+
+[discovery]
+method = "manual"
+
+[[discovery.monoliths]]
+host = "localhost"
+port = 3002

data/dev-env/collector.docker.toml

@@ -0,0 +1,7 @@
+collect_interval = "5s"
+balancer_api_key = "<balancer's api key>"
+
+[discovery]
+method = "dns"
+service_port = 8081
+query = "balancer"

data/dev-env/collector.no-docker.toml

@@ -0,0 +1,9 @@
+collect_interval = "5s"
+balancer_api_key = "<balancer's api key>"
+
+[discovery]
+method = "manual"
+
+[[discovery.monoliths]]
+host = "localhost"
+port = 8081

data/dev-env/commands-vis-docker.txt

@@ -0,0 +1,11 @@
+# Terminal 0 - OTT
+docker-compose -f docker/with-balancer.docker-compose.yml up -d
+
+# Terminal 1 - Grafana
+yarn workspace ott-vis server
+
+# Terminal 2 - ott-vis-panel - only if panel has changed
+yarn workspace ott-vis-panel run dev
+
+# Terminal 3 - ott-vis-datasource - only if datasource has changed
+yarn workspace ott-vis-datasource run dev

data/dev-env/commands-vis-no-docker.txt

@@ -0,0 +1,17 @@
+# Terminal 0 - Balancer
+cargo run --bin ott-balancer-bin -- --config-path env/balancer.toml
+
+# Terminal 1 - Monolith
+yarn run start
+
+# Terminal 2 - Collector
+cargo run --bin ott-collector -- --config-path env/collector.toml
+
+# Terminal 3 - Grafana
+yarn workspace ott-vis server
+
+# Terminal 4 - ott-vis-panel - only if panel has changed
+yarn workspace ott-vis-panel run dev
+
+# Terminal 5 - ott-vis-datasource - only if datasource has changed
+yarn workspace ott-vis-datasource run dev

figures/dev-env/vis-dev-env-docker.puml

@@ -0,0 +1,22 @@
+@startuml
+node Browser {
+  portout http
+}
+
+node Grafana {
+  portin "Listens on 3500" as grafanalisten
+
+  component Datasource {
+    portout "http" as datasourcehttp
+  }
+}
+
+node OTT {
+  portin "Collector on 8000" as COLLECTOR_PORT
+  portin "Balancer on 8080" as BALANCER_PORT
+}
+
+http --> grafanalisten
+datasourcehttp --> COLLECTOR_PORT
+http --> BALANCER_PORT
+@enduml

figures/dev-env/vis-dev-env-no-docker.puml

@@ -0,0 +1,37 @@
+@startuml
+node Browser {
+  portout http
+}
+
+node Grafana {
+  portin "Listens on 3500" as grafanalisten
+
+  component Datasource {
+    portout "http" as datasourcehttp
+  }
+}
+
+folder OTT {
+  node Collector {
+    portin "Listens on 8000" as COLLECTOR_PORT
+    portout "http" as collectorhttp
+  }
+
+  node Balancer  {
+    portin "BALANCER_PORT=8081" as BALANCER_PORT
+    portout http_proxy
+    portout monolith
+  }
+
+  node Monolith {
+    portin "PORT=3000" as PORT
+    portin "BALANCING_PORT=3002" as BALANCING_PORT
+  }
+}
+
+http --> grafanalisten
+datasourcehttp --> COLLECTOR_PORT
+collectorhttp --> BALANCER_PORT
+http_proxy --> PORT
+monolith --> BALANCING_PORT
+@enduml

visualization-design.typ

@@ -275,3 +275,86 @@ The visualization will be able to receive streamed events from the balancers for
 ) <Figure::vis-collector-component>
 
 In the Balancer, events are sourced directly from the Balancer's logs via a `Layer` from the `tracing` crate.
+
+== Dev Environment
+#import "balancer-design.typ": text-box
+
+There are 4 components that need to be running in order to have the visualization working correctly:
++ Grafana instance
++ Collector
++ Balancer
++ Monolith
+
+See @Section::dev-env for instructions on running the Monolith with the Balancer.
+
+The easiest way to do this is with the `with-balancer.docker-compose.yml` file. This file will run the balancer, monolith, and collector in a docker-compose environment.
+
+#text-box(
+  raw("docker-compose -f docker/with-balancer.docker-compose.yml up -d")
+)
+
+#let vis-dev-env-figure(path, caption, balancer-config, collector-config, commands) = {
+	figure(
+		grid(
+			columns: 2,
+			gutter: 20pt,
+			image(path),
+			align(left)[
+				#grid(
+					gutter: 10pt,
+					[
+						`balancer.toml`
+
+						#text-box(
+							raw(balancer-config, lang: "toml"),
+						)
+					],
+					[
+						`collector.toml`
+
+						#text-box(
+							raw(collector-config, lang: "toml"),
+						)
+					],
+					[
+						`Commands to run:`
+
+						#text-box(
+							raw(commands, lang: "bash"),
+						)
+					]
+				)
+			]
+		),
+		caption: caption,
+	)
+}
+
+#vis-dev-env-figure(
+  "figures/dev-env/vis-dev-env-docker.svg",
+  "Visualization Development Environment Setup (with docker)",
+  read("data/dev-env/balancer.docker.toml"),
+  read("data/dev-env/collector.docker.toml"),
+	read("data/dev-env/commands-vis-docker.txt"),
+) <Figure::vis-dev-env-docker>
+
+Alternatively, @Figure::vis-dev-env-no-docker shows how to run the balancer, monolith, and collector without docker.
+
+#vis-dev-env-figure(
+  "figures/dev-env/vis-dev-env-no-docker.svg",
+  "Visualization Development Environment Setup (without docker)",
+  read("data/dev-env/balancer.no-docker.toml"),
+  read("data/dev-env/collector.no-docker.toml"),
+  read("data/dev-env/commands-vis-no-docker.txt"),
+) <Figure::vis-dev-env-no-docker>
+
+=== Checklist
+
+- Ensure Grafana is accessible at #link("http://localhost:3500")
+- Ensure both the datasource and panel have been built
+- Ensure the balancer is running
+  - Make sure an api key is set in the config
+- Ensure the monolith is running
+  - Make sure load balancing is enabled
+- Ensure the collector is running and accessible at #link("http://localhost:8000")
+  - Make sure the collector is configured with the balancer's api key