From be869e375c68beaabe570e1e5d2a1a0e2e0f8ae0 Mon Sep 17 00:00:00 2001
From: Evan Shortiss <evanshortiss@gmail.com>
Date: Thu, 12 Oct 2023 14:02:08 -0700
Subject: [PATCH] doc: notes for xstate usage in UI and explain networking

---
 roshambo-ui/README.md  | 16 ++++++++++++----
 roshambo-ui/nginx.conf |  5 +++--
 2 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/roshambo-ui/README.md b/roshambo-ui/README.md
index fa271a9..a7e58f1 100644
--- a/roshambo-ui/README.md
+++ b/roshambo-ui/README.md
@@ -1,5 +1,9 @@
 # RPS Game UI
 
+**NOTE:** This application uses XState for managing state. Install the [XState VS Code Plugin](https://marketplace.visualstudio.com/items?itemName=statelyai.stately-vscode)
+to ensure that the _StateMachine.typegen.ts_ file is automatically regenerated
+when _StateMachine.ts_ is modified.
+
 ## Local Development
 
 Requires Node.js 18.12.1 or later. Consider using 
@@ -30,8 +34,8 @@ npm run dev -- --host
 
 ### Local Development for iOS Devices
 
-iOS disables access to the camera and accelerometer APIs when a site is not
-served via HTTPS.
+iOS disables camera and accelerometer API access when a site is not served over
+HTTPS.
 
 To serve the application in development mode with SSL/HTTPS enabled, use this
 command:
@@ -40,6 +44,9 @@ command:
 npm run dev:ssl -- --host
 ```
 
+You'll need to accept the self-signed certificate when you visit the
+application on your iOS device.
+
 ## Running with Podman/Docker
 
 Build the backend:
@@ -50,7 +57,8 @@ mvn clean package
 podman build . -f src/main/docker/Dockerfile.jvm -t rps-backend
 ```
 
-Run the backend container:
+Run the backend container, and optionally expose its port 8080 on host port
+8181:
 
 ```bash
 podman run --rm -p 8181:8080 --name rps-backend rps-backend
@@ -63,7 +71,7 @@ cd roshambo-ui
 podman build . -t rps-ui
 ```
 
-Start the frontend (making sure to pass the backend host):
+Start the frontend, making sure to pass the backend host and port:
 
 ```bash
 export BACKEND_IP=$(podman inspect --format='{{.NetworkSettings.IPAddress}}' rps-backend)
diff --git a/roshambo-ui/nginx.conf b/roshambo-ui/nginx.conf
index ab2b30e..73c8321 100644
--- a/roshambo-ui/nginx.conf
+++ b/roshambo-ui/nginx.conf
@@ -45,7 +45,8 @@ http {
 
         # This is necessary to ensure that RPS_BACKEND_HOST is resolved. NGINX
         # fails to resolve the hostname despite the NGINX container having the
-        # OpenShift nameserver in /etc/resolve.conf, so it must be injected!
+        # OpenShift nameserver in /etc/resolve.conf, so it must be injected
+        # into this conf file when the container is starting!
         resolver $NAMESERVERS valid=10s;
 
         # Load configuration files for the default server block.
@@ -58,7 +59,7 @@ http {
 
             # The RPS_BACKEND_HOST variable is replaced by envsubst when the
             # container image starts. The RPS_BACKEND_HOST variable must be
-            # defined as a runtime variable!
+            # defined as a runtime environment variable!
             proxy_pass "$RPS_BACKEND_HOST$request_uri";
 
             # Required for correct handling of server-sent events