docs: a setup guide for people who are not us

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)

docs/START-HERE.md

@@ -0,0 +1,223 @@
+# 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).
+
+> **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.
+
+---
+
+## The two things that confuse everyone
+
+Two things surprise almost everyone the first time. Both look like something is broken. Neither one is.
+
+### 1. It is `https`, not `http`
+
+HumWatch only answers over `https`. The address is:
+
+```
+https://localhost:9100
+```
+
+That `s` matters. Type `http` and you get nothing at all.
+
+### 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_<new-version>_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
+
+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 and copy it across yourself:
+
+```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.