rework

bashyoverlay.md

@@ -0,0 +1,155 @@
+# BashyOverlay — Server Notes
+**Last updated:** 2026-04-26
+
+---
+
+## What it is
+
+BashyOverlay is a Twitch stream overlay tool built with Node.js/Express. It receives Twitch EventSub events (follows, subs, bits, channel points, raids) and broadcasts them to OBS browser sources via WebSocket.
+
+Source: `/home/bashy/projects/BashyOverlay` (Linux Mint)
+Deployed to: `/opt/heystreamer/` (VPS)
+
+**Stack:** Node.js, Express, EJS, better-sqlite3, ws, tmi.js, dotenv, express-session
+
+---
+
+## Domains
+
+| Domain | Role |
+|---|---|
+| `overlay.bashynx.com` | Primary — dashboard, OBS browser source |
+| `heystreamer.bashynx.com` | Alias — same app |
+
+Both are reverse-proxied by Apache to `localhost:3000`.
+WebSocket at `/ws/overlay` requires `mod_proxy_wstunnel`.
+
+---
+
+## Server Location
+
+```
+/opt/heystreamer/
+├── src/
+│   ├── server.js      — entry point
+│   ├── app.js         — Express app, session config
+│   ├── db.js          — SQLite setup + migrations
+│   ├── eventsub.js    — Twitch EventSub WebSocket client
+│   └── ...
+├── views/             — EJS templates
+├── public/
+│   └── media/         — uploaded sounds/videos (gitignored)
+├── .env               — credentials (not in git)
+└── database.db        — SQLite database
+```
+
+---
+
+## Systemd Service
+
+```bash
+sudo systemctl status bashyoverlay
+sudo systemctl restart bashyoverlay
+sudo journalctl -u bashyoverlay -f
+```
+
+Service file: `/etc/systemd/system/bashyoverlay.service`
+Runs as: `bashynx` user
+Port: `3000` (localhost only, Apache proxies it)
+
+---
+
+## Environment Variables (.env)
+
+Required:
+```
+TWITCH_CLIENT_ID=
+TWITCH_CLIENT_SECRET=
+TWITCH_REDIRECT_URI=https://overlay.bashynx.com/auth/callback
+SECRET_KEY=
+APP_BASE_URL=https://overlay.bashynx.com
+```
+
+Register both callback URLs in Twitch dev console:
+- `http://localhost:3000/auth/callback` (dev)
+- `https://overlay.bashynx.com/auth/callback` (production)
+
+**Note:** Use only one `TWITCH_REDIRECT_URI` entry in `.env` — duplicates cause the OAuth redirect to fail silently.
+
+---
+
+## Apache Vhost
+
+File: `/etc/apache2/sites-available/overlay.bashynx.conf`
+
+Key directives:
+```apache
+RequestHeader set X-Forwarded-Proto "https"
+
+ProxyPass        /ws/overlay ws://127.0.0.1:3000/ws/overlay
+ProxyPassReverse /ws/overlay ws://127.0.0.1:3000/ws/overlay
+ProxyPass        / http://127.0.0.1:3000/
+ProxyPassReverse / http://127.0.0.1:3000/
+
+Header always unset Content-Security-Policy
+Header always set Content-Security-Policy "default-src 'self' 'unsafe-inline' 'unsafe-eval' https: wss: data:;"
+```
+
+Required modules: `proxy`, `proxy_http`, `proxy_wstunnel`, `headers`
+
+---
+
+## Known Issue — Twitch OAuth Login
+
+**Status:** Login button fires the request but redirects back to login page.
+
+**Root cause:** Express doesn't know it's behind an HTTPS proxy, so the session
+cookie's `secure: true` flag prevents it from being set over what Express perceives
+as an HTTP connection.
+
+**Fix needed (two parts):**
+
+1. In `src/app.js` — already applied locally:
+```javascript
+app.set('trust proxy', 1); // before session middleware
+```
+
+2. In Apache vhost — add:
+```apache
+RequestHeader set X-Forwarded-Proto "https"
+```
+
+3. Redeploy from Linux Mint:
+```bash
+rsync -avzO --exclude='node_modules' --exclude='.env' --exclude='public/media' \
+    ~/projects/BashyOverlay/ bashynx@185.8.164.40:/opt/heystreamer/
+
+ssh bashynx@185.8.164.40 "cd /opt/heystreamer && npm install --production"
+sudo systemctl restart bashyoverlay
+```
+
+---
+
+## Deploying Updates
+
+From Linux Mint:
+```bash
+rsync -avzO \
+    --exclude='node_modules' \
+    --exclude='.env' \
+    --exclude='public/media' \
+    ~/projects/BashyOverlay/ \
+    bashynx@37.205.8.118:/opt/heystreamer/
+
+ssh bashynx@37.205.8.118 \
+    "cd /opt/heystreamer && npm install --production && sudo systemctl restart bashyoverlay"
+```
+
+---
+
+## OBS Setup
+
+Browser source URL: `https://overlay.bashynx.com/overlay/<uuid>`
+
+The UUID is generated on first run and stored in the `settings` table.
+Find it at: `https://overlay.bashynx.com/settings`