Docs: cover Proxmox health checks and the System Summary source

src/content/docs/docs/badges.md

@@ -16,7 +16,19 @@ A badge is the small pill on an app tile. Each app can have three kinds.
 Shows whether the service is up.
 
 - **Ping** reads the HTTP status of a URL.
-- **Container** reads the container state from Docker. It needs a socket proxy such as [docker-socket-proxy](https://github.com/tecnativa/docker-socket-proxy), its address in `SOCKET_PROXY_URL`, and Docker Container Health Checks on in General. Never mount the Docker socket into Stackyard.
+- **Container** reads the container state from Docker. It needs a socket proxy such as [docker-socket-proxy](https://github.com/tecnativa/docker-socket-proxy) and its address in Docker Socket URL in General, or in `SOCKET_PROXY_URL`. Never mount the Docker socket into Stackyard.
+- **Proxmox** reads whether a Proxmox VE virtual machine or container is running. Pick it from the Guest list. It needs the Proxmox connection in General.
+
+Every check type needs **Health Checks** on in General.
+
+### Proxmox token
+
+1. In Proxmox, open **Datacenter**, **Permissions**, **API Tokens**, and add a token.
+2. Give the role **PVEAuditor** on path `/`. The role is read only.
+3. If **Privilege Separation** is on, give the role to the token itself, not only to its user. Otherwise the token sees no guests.
+4. In Stackyard, enter the address, the token ID (`user@realm!name`) and the secret, then press <span class="sy-btn sy-btn--ghost">Test</span>. It reports how many guests the token can see.
+
+One request to Proxmox serves every Proxmox tile.
 
 A problem shows a red `!`. Hover it for the reason. Turn on Hide Healthy Badge in General to hide the green state.
 

src/content/docs/docs/first-setup.md

@@ -21,7 +21,7 @@ The password is a gate between local users, not an authentication layer. See [Se
 
 | Section | What it covers |
 | --- | --- |
-| **General** | Server identity and behaviour: title, host IP, language, logging, password, Docker health checks, and config [import and export](/docs/import-export/backup-and-restore/). |
+| **General** | Server identity and behaviour: title, host IP, language, logging, password, health checks, and config [import and export](/docs/import-export/backup-and-restore/). |
 | **Appearance** | How the dashboard looks: wallpaper, labels, and theme. See [Wallpaper and themes](/docs/customization/). |
 | **Dashboard** | What is on the dashboard: apps, widgets, folders, and their order. See [Apps and folders](/docs/apps-and-folders/). |
 | **About** | Version, update notice, and links to the project. |

src/content/docs/docs/is-stackyard-for-you.mdx

@@ -27,7 +27,7 @@ How Stackyard compares with the three dashboards it is most often weighed agains
     },
     {
       label: 'Health checks',
-      values: ['HTTP, Docker', 'HTTP, ICMP, Docker', 'HTTP, ICMP', 'HTTP'],
+      values: ['HTTP, Docker, Proxmox', 'HTTP, ICMP, Docker, Kubernetes, Proxmox', 'HTTP, ICMP', 'HTTP'],
     },
     {
       label: 'Self-hosted integrations',

src/content/docs/docs/security.md

@@ -41,7 +41,7 @@ Stackyard never adds a name to the list by itself. Open a fresh install by its I
 
 Stored secrets are stripped from the config before it reaches the browser. A populated field reports as set without returning its value, in config responses and in exports alike.
 
-A secret is restored only for the request it was stored for. If a save changes where the credential would be sent, by editing a badge URL, its non-secret headers, or a widget field that decides where it goes, the stored value is not restored and Stackyard names what must be re-entered. Matching on an item's id alone would let an imported config point an existing credential somewhere new. These count as such a change too: turning **Allow self-signed certificate** on or off for an app, turning `settings.server.skipTlsVerify` on or off for widgets, changing a widget's type, and changing or removing the port map (`settings.server.portMap`).
+A secret is restored only for the request it was stored for. If a save changes where the credential would be sent, by editing a badge URL, its non-secret headers, or a widget field that decides where it goes, the stored value is not restored and Stackyard names what must be re-entered. Matching on an item's id alone would let an imported config point an existing credential somewhere new. These count as such a change too: turning **Allow self-signed certificate** on or off for an app, turning `settings.server.skipTlsVerify` on or off for widgets, changing a widget's type, and changing or removing the port map (`settings.server.portMap`). The Proxmox secret in General is cleared when its address, token ID or **Allow self-signed certificate** changes.
 
 Secrets are stored in plain text in `apps.json` on the data volume. Protect that volume with filesystem permissions and backups.
 

src/content/docs/docs/settings-reference.md

@@ -28,9 +28,11 @@ At the top, before any group:
 | Setting | What it does |
 | --- | --- |
 | Logging Level | How much detail goes to the container log. Errors shows warnings and errors. Security events are always logged. See [Support](/docs/support/#reading-the-logs). |
-| Docker Container Health Checks | Turns on container status for apps. Needs a socket proxy address below. See [Badges](/docs/badges/). |
+| Health Checks | Turns on the health badge for every app with a check. On by default. Off hides the settings below. See [Health check](/docs/badges/#health-check). |
 | Hide Healthy Badge | Shows the health dot only when something is wrong. |
-| Socket URL | Where your Docker socket proxy is. Never the Docker socket itself. See [Health check](/docs/badges/#health-check). |
+| Docker Socket URL | Where your Docker socket proxy is. Needed for Container checks only. Never the Docker socket itself. |
+| Proxmox Address, Token ID, Secret | The Proxmox VE server for Proxmox checks, for example `https://pve.local:8006`. The token needs the PVEAuditor role. The secret stays on the server. |
+| Allow self-signed certificate | Proxmox only. Turn on for the certificate Proxmox installs by default. |
 
 If every app suddenly shows as unhealthy, the socket proxy address is the usual cause. See [Troubleshooting](/docs/troubleshooting/#every-app-with-a-container-shows-as-unhealthy-at-once).
 

src/content/docs/docs/troubleshooting.md

@@ -148,9 +148,15 @@ Setting **Host IP** in **General** also allows that address through the SSRF gua
 
 ### The health check badge shows nothing for a container
 
-Container checks read the Docker daemon through a socket proxy. Set `SOCKET_PROXY_URL` to the proxy's address, then turn on **Docker Container Health Checks** in **General**.
+Turn on **Health Checks** in **General**. Every check type needs it.
 
-A ping check needs neither. Switch the check type to Ping and give it a URL.
+Container checks read the Docker daemon through a socket proxy. Enter the proxy's address in **Docker Socket URL**, or set `SOCKET_PROXY_URL`.
+
+A ping check needs no proxy. Switch the check type to Ping and give it a URL.
+
+### Every Proxmox tile says Guest not found
+
+The token sees no guests. Press <span class="sy-btn sy-btn--ghost">Test</span> under **Health Checks**. `Connected · 0 guests` means the token has no role. If **Privilege Separation** is on for the token, give PVEAuditor to the token itself, not only to its user.
 
 ### Every app with a container shows as unhealthy at once
 
@@ -264,10 +270,15 @@ Messages shown in the admin, and what each one means.
 | `Nothing at that address answered.` | The socket proxy address is unreachable from inside the container. Usually a proxy published on the host's loopback. |
 | `That name is resolved by Docker, which answers only for containers on a shared network.` | The socket proxy service name is not on a network Stackyard shares. |
 | `Saved, but the socket proxy did not answer` | The address was stored, but nothing responded. Docker health checks will not work until it does. |
-| `Enter the socket proxy address, or turn Docker monitoring off.` | Docker health checks are on with no proxy address set. |
 | `Settings unavailable` | The widget's definition could not be loaded. The stored config is kept. |
 | `N widgets could not be loaded, so they are not listed below.` | Those definitions were refused at startup. The reason is in the container log. |
 | `Container not found` | The socket proxy answered, but no container matched that name. |
+| `Guest not found` | Proxmox answered, but lists no guest with that number. Templates are never listed. See [above](#every-proxmox-tile-says-guest-not-found). |
+| `Guest stopped` | The Proxmox virtual machine or container is not running. |
+| `No data from Proxmox` | Proxmox lists the guest but has no current status for it. Its node is usually offline or has just started. |
+| `Proxmox refused the token. Check the token ID and secret.` | The token ID or secret is wrong. |
+| `The token cannot read this. Give it the PVEAuditor role.` | The token is valid but lacks a permission. |
+| `Enter the Proxmox address, token ID and secret under Health Checks in General.` | An app has a Proxmox check, but no Proxmox connection is set. |
 | `This address has no API path. Enter the service's full API URL.` | The Live Activity address names a host only. Badges read a value from an API response, so the address needs the service's API path. |
 | `Connected, but this address has no API path. Enter the service's full API URL.` | The address answered, but nothing numeric was found in the response. Same cause as above. |
 | `The address answered with a redirect (HTTP <status>). Enter the address it points to.` | Redirects are not followed. Use the final address, which is often a login page when the API path is missing. |

src/content/docs/docs/widgets/index.mdx

@@ -32,7 +32,7 @@ Widgets reorder in the same list as apps and folders. See [Apps and folders](/do
   { href: '/docs/widgets/dns/', name: 'DNS', text: 'Blocked and total queries.', value: 'AdGuard Home, Pi-hole, Technitium, NextDNS' },
   { href: '/docs/widgets/github/', name: 'GitHub', text: 'Pull requests or a contribution graph.', value: 'GitHub' },
   { href: '/docs/widgets/now-playing/', name: 'Now Playing', text: 'What is playing, with progress.', value: 'Plex, Jellyfin, Emby, Navidrome' },
-  { href: '/docs/widgets/system-summary/', name: 'System summary', text: 'CPU, memory, disk, temperature and network.', value: 'This machine, Glances, Beszel, Unraid' },
+  { href: '/docs/widgets/system-summary/', name: 'System summary', text: 'CPU, memory, disk, temperature and network.', value: 'This machine, Glances, Beszel, Unraid, Proxmox' },
   { href: '/docs/widgets/weather/', name: 'Weather', text: 'Current conditions for one place.', value: 'Open-Meteo, OpenWeather' },
 ]} />
 

src/content/docs/docs/widgets/system-summary.mdx

@@ -1,6 +1,6 @@
 ---
 title: System summary widget
-description: CPU, memory, disk, temperature and network stats from the host, Glances, Beszel or Unraid, on your Stackyard dashboard.
+description: CPU, memory, disk, temperature and network stats from the host, Glances, Beszel, Unraid or Proxmox VE, on your Stackyard dashboard.
 ---
 
 import WidgetGroup from '../../../../components/WidgetGroup.astro';
@@ -66,6 +66,20 @@ Sizes: Small, Medium.
     notes: ['Unraid reports neither IO wait nor a process count.'],
     links: [{ label: 'unraid.net', href: 'https://unraid.net/' }],
   },
+  {
+    name: 'Proxmox',
+    kind: 'Virtualization server',
+    needs: 'URL, API token',
+    fields: [
+      ['Proxmox URL', 'For example `https://pve.local:8006`. An address without `https://` gets it.'],
+      ['Token ID', 'For example `stackyard@pve!dashboard`. Give the token the PVEAuditor role.'],
+      ['Token Secret', 'Stored as a secret.'],
+      ['Allow Self-Signed Certificate', 'Turn on for the certificate Proxmox installs by default.'],
+      ['Node', 'Load the list and pick one. Leave empty on a server with one node.'],
+    ],
+    notes: ['Proxmox reports neither temperature nor a process count. A Disk slot reads a storage ID, or the root filesystem when empty.'],
+    links: [{ label: 'proxmox.com', href: 'https://www.proxmox.com/en/proxmox-virtual-environment' }],
+  },
 ]} />
 
 <SettingList title="Settings" items={[
@@ -91,7 +105,7 @@ The widget always shows three slots.
 <SettingList title="Settings for each slot" items={[
   { name: 'Resource', text: 'CPU, RAM, Temperature, Disk Mount, IO Wait or Processes.' },
   { name: 'Thermal Zone or Sensor', text: 'Temperature only. A thermal zone number for This Machine, 0 by default. A sensor picked from the loaded list for the other sources.' },
-  { name: 'First and second disk', text: 'Disk Mount only. Mount paths for This Machine and Glances, filesystem names for Beszel, share names for Unraid. The second is optional. An empty Unraid share reads the whole array.' },
+  { name: 'First and second disk', text: 'Disk Mount only. Mount paths for This Machine and Glances, filesystem names for Beszel, share names for Unraid, storage IDs such as `local-lvm` for Proxmox. The second is optional. An empty Unraid share reads the whole array.' },
   { name: 'Color', text: 'The slot colour. Defaults to blue.' },
 ]} />
 
@@ -101,7 +115,7 @@ Medium size only.
 
 <SettingList title="Network row settings" items={[
   { name: 'Show Network Row', text: 'Off by default.' },
-  { name: 'Mode', text: 'Speed shows the last speed test. Throughput shows live traffic on one interface. Uptime shows uptime.' },
+  { name: 'Mode', text: 'Speed shows the last speed test. Throughput shows live traffic on one interface, except for Proxmox. Uptime shows uptime.' },
   { name: 'Interface', text: 'Throughput only, for Glances, Beszel and Unraid. Load the list, then pick one.' },
 ]} />