From 3c6b5a106533ef7dae558a34b8e3609c44f78370 Mon Sep 17 00:00:00 2001 From: SandObserver <260779319+SandObserver@users.noreply.github.com> Date: Thu, 22 Oct 2026 16:56:46 -0400 Subject: [PATCH] Docs: cover Proxmox health checks and the System Summary source Document the Health Checks switch, the Proxmox check type and token setup, the Proxmox System Summary source, the new messages, and the Proxmox secret rule. Update the comparison's health checks row. --- src/content/docs/docs/badges.md | 14 ++++++++++++- src/content/docs/docs/first-setup.md | 2 +- .../docs/docs/is-stackyard-for-you.mdx | 2 +- src/content/docs/docs/security.md | 2 +- src/content/docs/docs/settings-reference.md | 6 ++++-- src/content/docs/docs/troubleshooting.md | 17 +++++++++++++--- src/content/docs/docs/widgets/index.mdx | 2 +- .../docs/docs/widgets/system-summary.mdx | 20 ++++++++++++++++--- 8 files changed, 52 insertions(+), 13 deletions(-) diff --git a/src/content/docs/docs/badges.md b/src/content/docs/docs/badges.md index 75b8b6f..b35a47f 100644 --- a/src/content/docs/docs/badges.md +++ b/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 Test. 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. diff --git a/src/content/docs/docs/first-setup.md b/src/content/docs/docs/first-setup.md index 04041f8..3cc5462 100644 --- a/src/content/docs/docs/first-setup.md +++ b/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. | diff --git a/src/content/docs/docs/is-stackyard-for-you.mdx b/src/content/docs/docs/is-stackyard-for-you.mdx index ea753c4..6df2b09 100644 --- a/src/content/docs/docs/is-stackyard-for-you.mdx +++ b/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', diff --git a/src/content/docs/docs/security.md b/src/content/docs/docs/security.md index 6bc1c3f..59e86fa 100644 --- a/src/content/docs/docs/security.md +++ b/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. diff --git a/src/content/docs/docs/settings-reference.md b/src/content/docs/docs/settings-reference.md index dee049f..8abb389 100644 --- a/src/content/docs/docs/settings-reference.md +++ b/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). diff --git a/src/content/docs/docs/troubleshooting.md b/src/content/docs/docs/troubleshooting.md index 4bddbf8..b4bb8fc 100644 --- a/src/content/docs/docs/troubleshooting.md +++ b/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 Test 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 ). 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. | diff --git a/src/content/docs/docs/widgets/index.mdx b/src/content/docs/docs/widgets/index.mdx index 3b3bf3f..e41b7a2 100644 --- a/src/content/docs/docs/widgets/index.mdx +++ b/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' }, ]} /> diff --git a/src/content/docs/docs/widgets/system-summary.mdx b/src/content/docs/docs/widgets/system-summary.mdx index c9bb8d2..0a994cb 100644 --- a/src/content/docs/docs/widgets/system-summary.mdx +++ b/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' }], + }, ]} /> @@ -101,7 +115,7 @@ Medium size only.