From 5aefef465f8697261b23f41802c8afcc616c5b49 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andreas=20Kr=C3=BChlmann?= <andreas@kruhlmann.dev>
Date: Thu, 8 Jan 2026 16:27:24 +0100
Subject: [PATCH] Crossplatform running and docs

---
 Makefile                                | 16 +++++++--
 README.md                               | 44 +++++++++++++++++++++++++
 src/main/shell/run-electron-app-in-xorg |  3 +-
 3 files changed, 59 insertions(+), 4 deletions(-)

diff --git a/Makefile b/Makefile
index 39756e2..567634d 100644
--- a/Makefile
+++ b/Makefile
@@ -10,6 +10,13 @@ IMGFLOAT_ASSETS_PATH ?= ./assets
 IMGFLOAT_PREVIEWS_PATH ?= ./previews
 SPRING_SERVLET_MULTIPART_MAX_REQUEST_SIZE ?= 10MB
 SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE ?= 10MB
+WATCHDIR = ./src/main
+ELECTRON := $(shell \
+	if [ -f /etc/os-release ] && grep -q '^ID=nixos' /etc/os-release; then \
+		echo electron; \
+	else \
+		echo "npx electron"; \
+	fi)
 RUNTIME_ENV = IMGFLOAT_ASSETS_PATH=$(IMGFLOAT_ASSETS_PATH) \
 			  IMGFLOAT_PREVIEWS_PATH=$(IMGFLOAT_PREVIEWS_PATH) \
 			  IMGFLOAT_GITHUB_OWNER=$(IMGFLOAT_GITHUB_OWNER) \
@@ -17,7 +24,6 @@ RUNTIME_ENV = IMGFLOAT_ASSETS_PATH=$(IMGFLOAT_ASSETS_PATH) \
 			  IMGFLOAT_DB_PATH=$(IMGFLOAT_DB_PATH) \
 			  SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE=$(SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE) \
 			  SPRING_SERVLET_MULTIPART_MAX_REQUEST_SIZE=$(SPRING_SERVLET_MULTIPART_MAX_REQUEST_SIZE)
-WATCHDIR = ./src/main
 
 node_modules: package-lock.json
 	npm install
@@ -43,9 +49,13 @@ test:
 package:
 	mvn clean package
 
+.PHONY: run-client
+run-client:
+	IMGFLOAT_CHANNELS_URL=http://localhost:8080/channels $(ELECTRON) ./src/main/node/app.js
+
 .PHONY: runx
-runx:
-	IMGFLOAT_CHANNELS_URL=http://localhost:8080/channels ./src/main/shell/run-electron-app-in-xorg
+run-client-x:
+	IMGFLOAT_CHANNELS_URL=http://localhost:8080/channels ./src/main/shell/run-electron-app-in-xorg $(ELECTRON)
 
 .PHONY: fix
 fix: node_modules
diff --git a/README.md b/README.md
index caaecdf..67dfa04 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,8 @@ Visit [imgfloat.kruhlmann.dev](https://imgfloat.kruhlmann.dev) once your streame
 
 ## Running locally
 
+### Environment
+
 Define the following required environment variables:
 
 | Variable | Description | Example Value |
@@ -54,3 +56,45 @@ IMGFLOAT_GITHUB_OWNER=...
 IMGFLOAT_GITHUB_REPO=...
 IMGFLOAT_INITIAL_TWITCH_USERNAME_SYSADMIN=...
 ```
+
+### Build and run
+
+To run the application:
+
+```sh
+$ make run
+...
+...  : Tomcat started on port 8080 (http) with context path ''
+```
+
+If you want live compilation run the `watch` command in a separate terminal. Note that this doesn't automatically reload the browser; this has to be done manually.
+
+```sh
+$ make watch
+...
+[INFO] BUILD SUCCESS
+```
+
+This automatically re-compiles the project when source files change. `entr` is required for this to work.
+
+### Running the electron client
+
+There are two methods of running the electron app during development.
+
+#### Running in the current X server
+
+```sh
+$ make run-client
+...
+^C
+```
+
+#### Running in a sandboxed X server
+
+This method spawns an Xorg server with `Xephyr` and `openbox` to ensure a floating window manager, which will more accurately reflect the common user environment. Killing either the Xephyr or electron process shuts both down.
+
+```sh
+$ make run-client-x
+...
+^C
+```
diff --git a/src/main/shell/run-electron-app-in-xorg b/src/main/shell/run-electron-app-in-xorg
index 8795c40..2340225 100755
--- a/src/main/shell/run-electron-app-in-xorg
+++ b/src/main/shell/run-electron-app-in-xorg
@@ -1,6 +1,7 @@
 #!/usr/bin/env sh
 set -eu
 
+ELECTRON="$1"
 APP_ENTRY="src/main/node/app.js"
 SCREEN="1280x800"
 
@@ -33,7 +34,7 @@ OPENBOX_PID=$!
 
 sleep 0.5
 
-DISPLAY=":$DISP" electron "$APP_ENTRY" &
+DISPLAY=":$DISP" "${ELECTRON}" "$APP_ENTRY" &
 ELECTRON_PID=$!
 DISPLAY=":$DISP" xsetroot -solid "#009999"