diff --git a/src/content/docs/docs/apps-and-folders.md b/src/content/docs/docs/apps-and-folders.md index bca6b6f..33d3097 100644 --- a/src/content/docs/docs/apps-and-folders.md +++ b/src/content/docs/docs/apps-and-folders.md @@ -9,6 +9,8 @@ description: Add app tiles with icons by name, group them in folders, and pin th Press Add, choose App, and enter a name, URL, icon and colour. +A name is up to 64 characters. Keep a username and password out of the URL: anyone who can open the dashboard can read it. Stackyard shows a warning when the URL holds one. + For the icon, type the service name, such as `sonarr`. Stackyard searches [dashboard-icons](https://github.com/homarr-labs/dashboard-icons), [selfh.st](https://github.com/selfhst/icons), [simple-icons](https://github.com/simple-icons/simple-icons) and [lobehub](https://github.com/lobehub/lobe-icons). A URL or an uploaded file also works. Icons load through your server, so the icon CDN never sees your list of services. ### Tile colour diff --git a/src/content/docs/docs/badges.md b/src/content/docs/docs/badges.md index 05c9534..03dff2d 100644 --- a/src/content/docs/docs/badges.md +++ b/src/content/docs/docs/badges.md @@ -15,8 +15,8 @@ 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) and its address in Docker Socket URL in General, or in `SOCKET_PROXY_URL`. Never mount the Docker socket into Stackyard. +- **Ping** reads the HTTP status of a URL. A link-local address (`169.254.0.0/16`, `fe80::/10`) is never pinged, by address or by a name that resolves to one. That range holds the cloud metadata service. +- **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`. A proxy that allows only versioned API paths, such as `/v1.47/containers/json`, works too. 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. diff --git a/src/content/docs/docs/import-export/migrating.md b/src/content/docs/docs/import-export/migrating.md index 5fd2edb..4fb9309 100644 --- a/src/content/docs/docs/import-export/migrating.md +++ b/src/content/docs/docs/import-export/migrating.md @@ -1,12 +1,22 @@ --- title: Import from Homepage or Dashy -description: Import links and folders into Stackyard from a gethomepage (Homepage) or Dashy YAML config. +description: Import links and folders into Stackyard from a gethomepage (Homepage) or Dashy YAML config, or from gethomepage labels on your Docker containers. --- **In the admin:** General, then Backup. See the [Settings reference](/docs/settings-reference/). Stackyard reads gethomepage and Dashy configuration files, so you do not have to retype every link. Find it under **General**, Import from another dashboard. +## From Docker labels + +**Import from Docker labels** reads gethomepage labels from every container, stopped ones included. It reads them through the **Docker Socket URL** under Health Checks, so turn Health Checks on and set that address first. The proxy needs read access to containers, such as `CONTAINERS=1` on docker-socket-proxy. + +A container needs both `homepage.name` and `homepage.group`. The group becomes a folder. Apps in a folder are ordered by `homepage.weight`, then by name. Folders are ordered by name. + +Each app gets a health check on its own container. Stackyard reads `homepage.href`, `homepage.icon` and `homepage.siteMonitor`. Widget labels are not imported, and their API keys never leave the server. + +Labels scoped to one instance, such as `homepage.instance.internal.href`, are not read. A container named only through instance labels is listed as not imported. + ## What comes across Links and folders. An app in the source becomes an app tile, and a group or section becomes a folder. @@ -15,6 +25,8 @@ A link written as a host and port, such as `plex.lan:32400`, is imported with `h Icons come across when they are a [dashboard-icons](https://github.com/homarr-labs/dashboard-icons) name or an icon link on `cdn.jsdelivr.net`. +A name longer than 64 characters is shortened. A username and password in a link or a health-check address are removed. + A Homepage `siteMonitor` or a Dashy status check becomes the app's health check. A Dashy check that allows insecure certificates is imported with certificate checking on, unless you tick **Allow self-signed certificate** in the import preview. :::note @@ -33,7 +45,7 @@ A health-check address that is only a path, or that the other dashboard resolves An entry is skipped when it has no label, has no link, or its link is not safe to follow. Relative links are skipped, because they have no meaning outside the dashboard that wrote them, as are values the other dashboard resolves from its own environment. -A file with more than 5,000 entries is refused, and nothing is imported. So is a file whose YAML merge keys (`<<`) expand too far. +A file with more than 5,000 entries is refused, and nothing is imported. The same limit applies to containers. So is a file whose YAML merge keys (`<<`) expand too far. Stackyard reports how many apps and folders were imported, and lists what it could not import and why. diff --git a/src/content/docs/docs/settings-reference.md b/src/content/docs/docs/settings-reference.md index 8abb389..2227b6d 100644 --- a/src/content/docs/docs/settings-reference.md +++ b/src/content/docs/docs/settings-reference.md @@ -52,6 +52,7 @@ Locked out? See [password recovery](/docs/troubleshooting/#i-forgot-the-password | --- | --- | | Import / Export | Downloads your whole config as one file, or restores it. See [Backup and restore](/docs/import-export/backup-and-restore/). | | Import from another dashboard | Reads gethomepage and Dashy files. Apps and folders are added. See [Import](/docs/import-export/migrating/). | +| Import from Docker labels | Reads gethomepage labels on your containers through the Docker Socket URL. Apps and folders are added. See [From Docker labels](/docs/import-export/migrating/#from-docker-labels). | ## Appearance diff --git a/src/content/docs/docs/troubleshooting.md b/src/content/docs/docs/troubleshooting.md index a4f4e2b..e12c645 100644 --- a/src/content/docs/docs/troubleshooting.md +++ b/src/content/docs/docs/troubleshooting.md @@ -310,8 +310,11 @@ Messages shown in the admin, and what each one means. | `: the importer cannot read the YAML on line .` | The file uses YAML the importer does not support, such as tab indentation or more than one document. | | `That file type is not supported.` | Icons must be SVG, PNG or ICO. Wallpapers must be JPEG, PNG, WebP, AVIF or GIF. | | `That is not a valid http or https address.` | The address is not an http or https URL. | -| `The socket proxy refused the request.` | The socket proxy answered its `/version` endpoint with 401 or 403. | -| `Something answered there, but it is not a Docker socket proxy.` | The address answered, but not with a Docker API version. | +| `The socket proxy refused the request.` | The socket proxy answered with 401 or 403, with and without an API version in the path. For Import from Docker labels, the proxy needs read access to containers. | +| `Something answered there, but it is not a Docker socket proxy.` | The address answered, but not with a Docker API version or a container list. | +| `Turn on Health Checks in General and enter the Docker Socket URL.` | Import from Docker labels has no socket proxy address to read from. | +| `No container has both a homepage.name and a homepage.group label.` | Import from Docker labels found no container it could turn into an app. | +| `Docker lists too many containers to import at once.` | The container list is larger than 16 MB, or holds more than 5,000 entries. | | `Saving is turned off in the live demo.` | The public demo is read-only. | | `Nothing to import. The file matches your current config.` | The imported file is identical to what is already stored. | | `Settings restored. Reload the page before changing any settings.` | An import replaced settings. Settings still shows the values from before it until the page reloads. |