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.