From c238e8234e29cf6bcc7640de45a0708fd847eb57 Mon Sep 17 00:00:00 2001 From: Static Date: Sat, 8 Aug 2026 14:42:58 -0400 Subject: [PATCH 1/2] docs: a setup guide for people who are not us v2 locked the agent down and made it meaningfully harder to reach. The address changed scheme, every browser now throws a full-page security warning, and nothing works until you find a token file you were never told existed. The README explains the system. It does not walk anyone through that. START-HERE.md does, in plain language: install, get past the warning and why the warning is correct-but-wrong-here, find the token, reach it from a phone, and the errors people will actually hit, quoted the way the screen words them. It is also honest about the three things that currently look broken and are not. The Machines page reads zero because self-signed peers fail verification silently and because each install generates its own token while the login box asks for a shared one. And a Windows installer upgrade orphans the database (#14), which is called out before the upgrade step rather than after. Co-Authored-By: Claude Opus 5 --- README.md | 7 ++ docs/START-HERE.md | 225 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 232 insertions(+) create mode 100644 docs/START-HERE.md diff --git a/README.md b/README.md index 59f6a2c..0197b10 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,11 @@ A self-hosted, local-first hardware monitoring system for Windows and Linux PCs. +> **New here? Read [Start Here](docs/START-HERE.md) instead of this file.** +> It walks through installing, getting past the browser security warning, and +> finding your token, in plain language. This README is the reference. That is +> the guide. + --- ## Features @@ -39,6 +44,8 @@ A self-hosted, local-first hardware monitoring system for Windows and Linux PCs. ## Installation +*Step-by-step version with the gotchas explained: [Start Here](docs/START-HERE.md).* + ### Installer (recommended) 1. Download **`HumWatch-Setup-vX.X.X.exe`** from the [releases page](https://github.com/StaticHumStudio/HumWatch/releases) diff --git a/docs/START-HERE.md b/docs/START-HERE.md new file mode 100644 index 0000000..fe89e45 --- /dev/null +++ b/docs/START-HERE.md @@ -0,0 +1,225 @@ +# Start Here + +This guide gets HumWatch running and gets you looking at it. No prior experience assumed. + +If you only read one thing, read [The two things that confuse everyone](#the-two-things-that-confuse-everyone). That is where people get stuck. + +--- + +## What HumWatch is + +HumWatch watches your computer's hardware. Temperatures, fan speeds, how hard the CPU is working, how much memory is left, how much disk space you have. It shows all of it on a web page. + +It runs on your own machine. Nothing goes to the cloud. There is no account to make. + +--- + +## Step 1: Install it + +Pick the row that matches your computer. + +| Your setup | What to download | What to do | +|---|---|---| +| **Windows, normal** | `HumWatch-Setup-v2.0.2.exe` | Double-click it. Click Yes when Windows asks for permission. | +| **Windows, no installer** | `HumWatch-v2.0.2.zip` | Unzip it anywhere. Run `setup.bat`, then `run.bat`. | +| **Debian or Ubuntu Linux** | `humwatch_2.0.2_amd64.deb` | `sudo apt install ./humwatch_2.0.2_amd64.deb` | +| **Other Linux** | `HumWatch-v2.0.2-linux.tar.gz` | Unpack it. Run `./setup.sh`, then `./run.sh`. | + +All of these are on the [releases page](https://github.com/StaticHumStudio/HumWatch/releases). + +> **Windows people, one warning.** If you are upgrading from version 1.x using the installer, **your old data does not come along automatically.** This is a known bug ([#14](https://github.com/StaticHumStudio/HumWatch/issues/14)). Before you upgrade, copy `C:\HumWatch\humwatch.db` somewhere safe. After upgrading, see [My history disappeared](#my-history-disappeared) to put it back. + +That is the install. It starts by itself and it starts again when you reboot. + +--- + +## The two things that confuse everyone + +HumWatch version 2 locked itself down on purpose. Two things changed, and both of them look like something is broken when it is not. + +### 1. It is `https`, not `http` + +The old address was `http://localhost:9100`. That address is dead now. + +The new one is: + +``` +https://localhost:9100 +``` + +That `s` matters. Without it you get nothing at all. If you had the old link bookmarked, fix the bookmark. + +### 2. Your browser will say the site is dangerous + +You will see a full-page warning. Something like **"Your connection is not private"** or **"Warning: Potential Security Risk Ahead."** + +**This is expected. Your computer is not compromised.** + +Here is what is actually happening. HTTPS needs a certificate, which is a file that proves a website is who it claims to be. Normally a company like Let's Encrypt vouches for that certificate, and your browser trusts them. + +HumWatch cannot do that, because it runs on *your* machine. There is no public company that can vouch for your laptop. So HumWatch makes its own certificate and signs it itself. Your browser sees a certificate that nobody famous vouched for, and it does the only thing it can do, which is warn you. + +The warning is correct in general. It is just wrong about *your* computer, because you are the one who installed the thing it is warning you about. + +**To get past it:** + +- **Chrome or Edge:** click **Advanced**, then **Proceed to localhost (unsafe)** +- **Firefox:** click **Advanced**, then **Accept the Risk and Continue** +- **Safari:** click **Show Details**, then **visit this website** + +You may have to do this once per browser, and again on your phone. + +--- + +## Step 2: Get your token + +Now the page asks for a **token**. A token is just a long password that HumWatch made for you. It is how HumWatch knows it is you and not somebody else on your network. + +You do not make one up. One already exists. You just have to go read it. + +**Windows:** + +Open Notepad as an administrator, then open this file: + +``` +C:\ProgramData\HumWatch\auth-token +``` + +Or paste this into PowerShell: + +```powershell +Get-Content C:\ProgramData\HumWatch\auth-token +``` + +**Linux:** + +```bash +sudo cat /etc/humwatch/auth-token +``` + +You will get a long line of random letters and numbers. Copy the whole thing. Do not add spaces. Do not press Enter in the middle of it. + +Paste it into the box on the page and click **Retry**. + +That is it. You are in. Your browser remembers the token, so you will not have to do this again on that browser. + +--- + +## Step 3: Look at it from your phone or another computer + +Works the same way, with one extra step first: **both devices have to be on the same network.** + +If they are on the same Wi-Fi, you are fine. If you want to reach your home PC from a coffee shop, you need something like [Tailscale](https://tailscale.com), which is free and makes your devices act like they are on the same network no matter where they are. + +Once that is sorted, replace `localhost` with the other machine's address: + +``` +https://192.168.1.50:9100 +``` + +Find that address by running `ipconfig` on Windows or `ip addr` on Linux, on the machine running HumWatch. If you use Tailscale, run `tailscale ip -4` instead and use that number. + +You will get the security warning again. Same deal, click through it. + +**On your phone you will get a slightly worse warning than on your computer.** Two things are wrong instead of one. The certificate is self-signed like before, *and* it does not list the machine's network address, only its name and `localhost`. Click through anyway. The tap is usually **Advanced**, then **Proceed**. + +Each machine has its own token, so grab that machine's token the same way you did in Step 2. + +--- + +## Step 4: Seeing all your machines at once + +HumWatch has a **Machines** page meant to show every computer you are running it on, side by side. + +**Fair warning: this probably shows zero right now.** Two reasons, and both are fixable. + +**Reason one, the tokens do not match.** The login box says "Shared fleet token" for a reason. The fleet view expects every machine to use the *same* token. But each install generates its own. So pick one machine's token, and copy it onto the others: + +- **Windows:** replace the contents of `C:\ProgramData\HumWatch\auth-token` +- **Linux:** replace the contents of `/etc/humwatch/auth-token` + +Restart HumWatch on any machine you changed. + +**Reason two, the certificates.** Machines check each other's certificates before trusting them, and self-signed certificates fail that check silently. Nothing errors, the other machine just never shows up. + +Fixing this properly means regenerating certificates that list each machine's network address, then telling every machine to trust the others. That is genuinely fiddly and it is documented in [Multi-Machine Setup](../README.md#multi-machine-setup) in the README. + +If you only watch one computer, ignore this whole section. Nothing is broken. + +--- + +## Keeping it updated + +**Windows, installed with the installer:** download the new `.exe` and run it. Back up your database first, see the warning in Step 1. + +**Windows, unzipped version:** double-click `update.bat`. It downloads the new version, checks that the download was not tampered with, and swaps it in. If anything goes wrong it puts the old version back. + +**Debian or Ubuntu:** `sudo apt install ./humwatch__amd64.deb`. Your settings and history survive. + +--- + +## When something goes wrong + +### The page will not load at all + +Check HumWatch is actually running. + +- **Windows:** press Windows+R, type `services.msc`, find **HumWatch**. It should say Running. +- **Linux:** `systemctl status humwatch` + +Also make sure you typed `https` and not `http`. + +### "This site can't be reached" from another device + +The two devices are not really on the same network, or a firewall is blocking port 9100. Test it from the HumWatch machine itself first using `https://localhost:9100`. If that works, the problem is the network between them, not HumWatch. + +### The token box keeps rejecting my token + +Almost always a copy-paste problem. Common causes: + +- A space snuck in at the start or end +- You copied only part of it +- A line break got pasted in the middle +- You used a different machine's token + +Read the file again and copy the entire line. + +### My history disappeared + +You upgraded Windows using the installer and hit bug [#14](https://github.com/StaticHumStudio/HumWatch/issues/14). Your data is not gone. It is sitting at the old location. + +Stop HumWatch, then copy the old database into the new location: + +```powershell +Stop-Service HumWatch +Copy-Item C:\HumWatch\humwatch.db C:\ProgramData\HumWatch\data\humwatch.db -Force +Start-Service HumWatch +``` + +Run PowerShell as administrator. Your history comes back. + +### There is no "Advanced" button on the warning + +Rare, but it happens if you reached the page by hostname rather than by IP address. Try the numeric address instead, like `https://192.168.1.50:9100`. + +### I forgot which address to use + +On the machine itself, `https://localhost:9100` always works. + +--- + +## Quick reference + +| Thing | Windows | Linux | +|---|---|---| +| Address on that machine | `https://localhost:9100` | `https://localhost:9100` | +| Token file | `C:\ProgramData\HumWatch\auth-token` | `/etc/humwatch/auth-token` | +| Your data | `C:\ProgramData\HumWatch\data\` | `/var/lib/humwatch/` | +| Logs | `C:\ProgramData\HumWatch\logs\` | `journalctl -u humwatch` | +| Start and stop | `services.msc`, find HumWatch | `sudo systemctl start\|stop humwatch` | + +--- + +## Still stuck? + +Open an issue at [github.com/StaticHumStudio/HumWatch/issues](https://github.com/StaticHumStudio/HumWatch/issues). Include your operating system, how you installed it, and what the screen actually says. Copy the exact wording of any error. It helps more than a description of it. From 692c95a2f1d63bf4f8b4f97b396fe8e5d70fd0ec Mon Sep 17 00:00:00 2001 From: Static Date: Sat, 8 Aug 2026 17:40:04 -0400 Subject: [PATCH 2/2] docs: drop the before-and-after framing from the guide A new user never saw the old version, so telling them what the address used to be, what changed, and which release changed it is trivia they have to read past to reach the instruction. Every "this used to be X" is now just X. The Windows backup warning stays, reframed. It is not history, it is an action someone takes now that loses their data if they take it in the wrong order. Co-Authored-By: Claude Opus 5 --- docs/START-HERE.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/START-HERE.md b/docs/START-HERE.md index fe89e45..bd7a753 100644 --- a/docs/START-HERE.md +++ b/docs/START-HERE.md @@ -27,7 +27,7 @@ Pick the row that matches your computer. All of these are on the [releases page](https://github.com/StaticHumStudio/HumWatch/releases). -> **Windows people, one warning.** If you are upgrading from version 1.x using the installer, **your old data does not come along automatically.** This is a known bug ([#14](https://github.com/StaticHumStudio/HumWatch/issues/14)). Before you upgrade, copy `C:\HumWatch\humwatch.db` somewhere safe. After upgrading, see [My history disappeared](#my-history-disappeared) to put it back. +> **Already have HumWatch on Windows? Back up before you run the installer.** It does not carry your saved history across, which is a known bug ([#14](https://github.com/StaticHumStudio/HumWatch/issues/14)). Copy `C:\HumWatch\humwatch.db` somewhere safe first. If you already ran it, see [My history disappeared](#my-history-disappeared). That is the install. It starts by itself and it starts again when you reboot. @@ -35,19 +35,17 @@ That is the install. It starts by itself and it starts again when you reboot. ## The two things that confuse everyone -HumWatch version 2 locked itself down on purpose. Two things changed, and both of them look like something is broken when it is not. +Two things surprise almost everyone the first time. Both look like something is broken. Neither one is. ### 1. It is `https`, not `http` -The old address was `http://localhost:9100`. That address is dead now. - -The new one is: +HumWatch only answers over `https`. The address is: ``` https://localhost:9100 ``` -That `s` matters. Without it you get nothing at all. If you had the old link bookmarked, fix the bookmark. +That `s` matters. Type `http` and you get nothing at all. ### 2. Your browser will say the site is dangerous @@ -186,9 +184,9 @@ Read the file again and copy the entire line. ### My history disappeared -You upgraded Windows using the installer and hit bug [#14](https://github.com/StaticHumStudio/HumWatch/issues/14). Your data is not gone. It is sitting at the old location. +The Windows installer does not move your saved history into the place HumWatch now reads from. That is bug [#14](https://github.com/StaticHumStudio/HumWatch/issues/14). Your data is not gone, it is still sitting in the install folder. -Stop HumWatch, then copy the old database into the new location: +Stop HumWatch and copy it across yourself: ```powershell Stop-Service HumWatch