From 6b42dfdb0dfd32588c7a593293a660e4549d6fde Mon Sep 17 00:00:00 2001 From: Liss-Bot Date: Sat, 16 May 2026 16:00:38 +0000 Subject: [PATCH] Update documentation --- docs/multi-language-support.md | 19 ++ docs/troubleshooting.md | 444 ++++++++++++++++----------------- docs/widgets.md | 8 +- 3 files changed, 246 insertions(+), 225 deletions(-) diff --git a/docs/multi-language-support.md b/docs/multi-language-support.md index 4e37ae2d..cad92b78 100644 --- a/docs/multi-language-support.md +++ b/docs/multi-language-support.md @@ -79,6 +79,25 @@ If you are not comfortable with making pull requests, or do not want to modify t --- +## Checking Translation Coverage + +We've got a short test/lint script for verifying translation files are complete and valid, and to show per-language coverage report. + +```bash +yarn validate-locales +``` + +This will run the following checks: +- Ensure all locale files are registered, present and parsable (failure) +- Non-existing translations used in the code, not present in en.json (failure) +- Translations in en.json never used anywhere in the code (warn) +- Translations in other locales not used in en.json or code (warn) +- Missing translations in other locales compared to en.json (coverage report) + +This script is located in [`tests/locales/check-locales.js`](https://github.com/lissy93/dashy/blob/master/tests/locales/check-locales.js), and can be executed directly, or with `yarn validate-locales` and is also run as part of the CI workflow on PRs. + +--- + ## Adding New Text to a Component If you're working on a new component, then any text that is displayed to the user should be extracted out of the component, and stored in the file. This also applies to any existing components, that might have been forgotten to be translated. Thankfully, everything is already setup, so this is a pretty easy job. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d2f318b1..3a4e3d2c 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -21,51 +21,66 @@ - [Container crashes or restart loop after saving](#container-crashes-or-restart-loop-after-saving-310-and-311-only) - [Intentionally read-only mode](#intentionally-read-only-mode) - [Refused to Connect in Web Content View](#refused-to-connect-in-modal-or-workspace-view) -- [404 On Static Hosting](#404-on-static-hosting) -- [404 from Mobile Home Screen](#404-after-launch-from-mobile-home-screen) -- [404 On Multi-Page Apps](#404-on-multi-page-apps) -- [Dashy hosted at a sub-path](#dashy-hosted-at-a-sub-path-eg-examplecomdashy) -- [Sub-page shows "Unable to find config for ..."](#sub-page-shows-unable-to-find-config-for) -- [Sub-page missing from nav, or won't open when clicked](#sub-page-missing-from-nav-or-wont-open-when-clicked) -- [Sub-page ignores its theme, layout or appConfig](#sub-page-ignores-its-theme-layout-or-appconfig) -- [Sub-config files return 404](#sub-config-files-return-404) -- [Yarn Build or Run Error](#yarn-error) -- [`yarn build` fails inside the container](#yarn-build-fails-inside-the-container) -- [Remote Config Not Loading](#remote-config-not-loading) -- [High CPU or RAM Usage on Startup](#high-cpu-or-ram-usage-on-startup) -- [Heap limit Allocation failed](#ineffective-mark-compacts-near-heap-limit-allocation-failed) -- [Command failed with signal "SIGKILL"](#command-failed-with-signal-sigkill) -- [Auth Validation Error: "should be object"](#auth-validation-error-should-be-object) -- [App Not Starting After Update to 2.0.4](#app-not-starting-after-update-to-204) -- [Keycloak Redirect Error](#keycloak-redirect-error) -- [OIDC or Keycloak failure on numeric client IDs](#oidc-or-keycloak-failure-on-numeric-client-ids) -- [Mount Type Mismatch](#mount-type-mismatch) +- [404 / Routing issues](#404--routing-issues) + - [404 On Static Hosting](#404-on-static-hosting) + - [404 from Mobile Home Screen](#404-after-launch-from-mobile-home-screen) + - [404 On Multi-Page Apps](#404-on-multi-page-apps) + - [Dashy hosted at a sub-path](#dashy-hosted-at-a-sub-path-eg-examplecomdashy) +- [Sub-pages](#sub-pages) + - [Sub-page shows "Unable to find config for ..."](#sub-page-shows-unable-to-find-config-for) + - [Sub-page missing from nav, or won't open when clicked](#sub-page-missing-from-nav-or-wont-open-when-clicked) + - [Sub-page ignores its theme, layout or appConfig](#sub-page-ignores-its-theme-layout-or-appconfig) + - [Sub-config files return 404](#sub-config-files-return-404) + - [Remote Config Not Loading](#remote-config-not-loading) +- [Build & memory errors](#build--memory-errors) + - [Yarn Build or Run Error](#yarn-error) + - [`yarn build` fails inside the container](#yarn-build-fails-inside-the-container) + - [High CPU or RAM Usage on Startup](#high-cpu-or-ram-usage-on-startup) + - [Heap limit Allocation failed](#ineffective-mark-compacts-near-heap-limit-allocation-failed) + - [Command failed with signal "SIGKILL"](#command-failed-with-signal-sigkill) + - [Node Sass unsupported environment](#node-sass-does-not-yet-support-your-current-environment) + - [Unreachable Code Error](#unreachable-code-error) + - [Cannot find module './_baseValues'](#error-cannot-find-module-_basevalues) +- [Auth & OIDC](#auth--oidc) + - [Auth Validation Error: "should be object"](#auth-validation-error-should-be-object) + - [Keycloak Redirect Error](#keycloak-redirect-error) + - [OIDC or Keycloak failure on numeric client IDs](#oidc-or-keycloak-failure-on-numeric-client-ids) + - [Redirect loop after login](#redirect-loop-after-login) + - [invalid_redirect_uri](#invalid_redirect_uri) + - [Login works in the browser but the dashboard refuses to save anything (403)](#login-works-in-the-browser-but-the-dashboard-refuses-to-save-anything-403) + - [Logged in but no admin controls](#logged-in-but-no-admin-controls) + - [Login works but Dashy errors on the callback with "OIDC signinCallback returned no user"](#login-works-but-dashy-errors-on-the-callback-with-oidc-signincallback-returned-no-user) + - [Sign-out leaves you stuck on Authentik](#sign-out-leaves-you-stuck-on-authentik) + - [Untrusted certificate from Authentik](#untrusted-certificate-from-authentik) + - [Numeric client_id getting truncated](#numeric-client_id-getting-truncated) +- [Docker & image issues](#docker--image-issues) + - [App Not Starting After Update to 2.0.4](#app-not-starting-after-update-to-204) + - [Mount Type Mismatch](#mount-type-mismatch) + - [DockerHub toomanyrequests](#dockerhub-toomanyrequests) + - [Old image tags fail to pull](#old-image-tags-fail-to-pull) + - [Healthcheck Failing in Docker](#healthcheck-failing-in-docker) + - [Docker Login Fails on Ubuntu](#docker-login-fails-on-ubuntu) - [Styles and Assets not Updating](#styles-and-assets-not-updating) -- [DockerHub toomanyrequests](#dockerhub-toomanyrequests) -- [Old image tags fail to pull](#old-image-tags-fail-to-pull) - [Config Validation Errors](#config-validation-errors) -- [Node Sass unsupported environment](#node-sass-does-not-yet-support-your-current-environment) -- [Unreachable Code Error](#unreachable-code-error) -- [Cannot find module './_baseValues'](#error-cannot-find-module-_basevalues) - [Ngrok Invalid Host Headers](#invalid-host-header-while-running-through-ngrok) - [Warnings in the Console during deploy](#warnings-in-the-console-during-deploy) -- [Docker Login Fails on Ubuntu](#docker-login-fails-on-ubuntu) - [Status Checks Failing](#status-checks-failing) -- [Healthcheck Failing in Docker](#healthcheck-failing-in-docker) -- [Diagnosing Widget Errors](#widget-errors) -- [Fixing Widget CORS Errors](#widget-cors-errors) -- [CORS Proxy connect ECONNREFUSED or ENOTFOUND](#cors-proxy-connect-econnrefused--or-getaddrinfo-enotfound) -- [CORS Proxy Target-URL host blocked or scheme rejected](#cors-proxy-target-url-host--is-blocked--must-use-http-or-https) -- [Widget Shows Error Incorrectly](#widget-shows-error-incorrectly) -- [Weather Forecast Widget 401](#weather-forecast-widget-401) -- [Widget Displaying Inaccurate Data](#widget-displaying-inaccurate-data) +- [Widgets](#widgets) + - [Diagnosing Widget Errors](#widget-errors) + - [Fixing Widget CORS Errors](#widget-cors-errors) + - [CORS Proxy connect ECONNREFUSED or ENOTFOUND](#cors-proxy-connect-econnrefused--or-getaddrinfo-enotfound) + - [CORS Proxy Target-URL host blocked or scheme rejected](#cors-proxy-target-url-host--is-blocked--must-use-http-or-https) + - [Widget Shows Error Incorrectly](#widget-shows-error-incorrectly) + - [Weather Forecast Widget 401](#weather-forecast-widget-401) + - [Widget Displaying Inaccurate Data](#widget-displaying-inaccurate-data) + - [Public IP Widget not working for ipinfo or ipquery providers](#public-ip-widget-not-working-for-ipinfo-or-ipquery-providers) - [Font Awesome Icons not Displaying](#font-awesome-icons-not-displaying) - [Copy to Clipboard not Working](#copy-to-clipboard-not-working) -- [How to Reset Local Settings](#how-to-reset-local-settings) -- [How to make a bug report](#how-to-make-a-bug-report) -- [Public IP Widget not working for ipinfo or ipquery providers](#public-ip-widget-not-working-for-ipinfo-or-ipquery-providers) -- [How-To Open Browser Console](#how-to-open-browser-console) -- [Git Contributions not Displaying](#git-contributions-not-displaying) +- [How-To / Reference](#how-to--reference) + - [How to Reset Local Settings](#how-to-reset-local-settings) + - [How to make a bug report](#how-to-make-a-bug-report) + - [How-To Open Browser Console](#how-to-open-browser-console) + - [Git Contributions not Displaying](#git-contributions-not-displaying) --- @@ -226,7 +241,9 @@ Content-Security-Policy: frame-ancestors 'self' https://[dashy-location]/ --- -## 404 On Static Hosting +## 404 / Routing issues + +### 404 On Static Hosting If you're seeing Dashy's 404 page on initial load/ refresh, and then the main app when you go back to Home, then this is likely caused by the Vue router, and if so can be fixed in one of two ways. @@ -234,26 +251,20 @@ The first solution is to switch the routing mode, from HTML5 `history` mode to ` If this works, but you wish to continue using HTML5 history mode, then a bit of extra [server configuration](/docs/management#web-server-configuration) is required. This is explained in more detaail in the [Vue Docs](https://router.vuejs.org/guide/essentials/history-mode.html). Once completed, you can then use `VITE_APP_ROUTING_MODE=history` (the default) again, for neater URLs. ---- - -## 404 after Launch from Mobile Home Screen +### 404 after Launch from Mobile Home Screen Similar to the above issue, if you get a 404 after using iOS and Android's "Add to Home Screen" feature, then this is caused by Vue router. It can be fixed by rebuilding Dashy with the `VITE_APP_ROUTING_MODE=hash` build-time environment variable set. See also: [#628](https://github.com/Lissy93/dashy/issues/628), [#762](https://github.com/Lissy93/dashy/issues/762) ---- - -## 404 On Multi-Page Apps +### 404 On Multi-Page Apps Similar to above, if you get a 404 error when visiting a page directly on multi-page apps, then this can be fixed by rebuilding Dashy with the `VITE_APP_ROUTING_MODE=hash` build-time environment variable set, then refreshing the page. See also: [#670](https://github.com/Lissy93/dashy/issues/670), [#763](https://github.com/Lissy93/dashy/issues/763) ---- - -## Dashy hosted at a sub-path (e.g. `example.com/dashy`) +### Dashy hosted at a sub-path (e.g. `example.com/dashy`) If the homepage works but sub-page links 404, or assets fail to load, it's almost always the base path. Rebuild with `BASE_URL` set to the sub-path - leading slash, no trailing slash: @@ -262,28 +273,28 @@ Vue Router uses this to prefix every route. Without it, links resolve to `/home/ --- -## Sub-page shows "Unable to find config for ..." +## Sub-pages + +### Sub-page shows "Unable to find config for ..." This means Dashy couldn't match the URL segment to any entry in your `pages:` list. A few causes: -### Old bookmark from before an upgrade +#### Old bookmark from before an upgrade Slugs are now trimmed more aggressively (e.g. `🌐 Command Center` used to give `-command-center`, now gives `command-center`). Re-bookmark from the nav, or update the URL by hand. -### The page was renamed or removed +#### The page was renamed or removed The URL no longer resolves to anything. Check the `pages:` array in `conf.yml` and confirm the sub-page still exists. -### The path points at an unreachable file +#### The path points at an unreachable file If the sub-config YAML can't be fetched (404, CORS, auth), you'll see "Unable to load config from ..." instead. Verify the `path:` is correct, reachable from the browser, and CORS-open if remote. -### Page name literally "Main" +#### Page name literally "Main" `main` is reserved in the URL scheme to mean "the root config". A page named "Main" becomes reachable at `/home/main-page` (not `/home/main`). Rename the page if that's confusing. -### Service worker is serving a stale app +#### Service worker is serving a stale app Hard-refresh (Ctrl + F5) after a major upgrade. The PWA cache may still be pointing at old routes. Also see [Styles and Assets not Updating](#styles-and-assets-not-updating). ---- - -## Sub-page missing from nav, or won't open when clicked +### Sub-page missing from nav, or won't open when clicked If page defined in `pages:` is nowhere in the nav bar, or its link goes to a different page, then there's probably something wrong with the name you chose. Note that Dashy strips out any non-alphanumeric characters. - Ensure each page does have a valid `name` and `path` field @@ -291,17 +302,13 @@ If page defined in `pages:` is nowhere in the nav bar, or its link goes to a dif - Check each page has a name which has at least some alpha-numeric characters - Very long names could be being stripped/truncated ---- - -## Sub-page ignores its theme, layout or appConfig +### Sub-page ignores its theme, layout or appConfig This is by design. Only the `appConfig` from your root `conf.yml` is used - theme, layout, iconSize, statusCheck, etc. are inherited globally so behaviour stays consistent across pages. If you put `appConfig` inside a sub-page YAML, it's silently dropped on load. Move the values to the root config. See [Restrictions](/docs/pages-and-sections#restrictions). ---- - -## Sub-config files return 404 +### Sub-config files return 404 If your `conf.yml` references additional pages via `pages:` and the browser shows `Sub-config load failed: /something.yml`, the cause is almost always a Docker mount that only exposes `conf.yml` and not the rest of `user-data/`. @@ -323,9 +330,24 @@ volumes: Now everything in your `user-data` folder is reachable at the web root. Same applies to `docker run -v`. +### Remote Config Not Loading + +If you've got a multi-page dashboard, and are hosting the additional config files yourself, then CORS rules will apply. A CORS error will look something like: + +```text +Access to XMLHttpRequest at 'https://example.com/raw/my-config.yml' from origin 'http://dashy.local' has been blocked by CORS policy: +No 'Access-Control-Allow-Origin' header is present on the requested resource. +``` + +The solution is to add the appropriate headers onto the target server, to allow it to accept requests from the origin where you're running Dashy. + +If it is a remote service, that you do not have admin access to, then another option is to proxy the request. Either host your own, or use a publicly accessible service, like [allorigins.win](https://allorigins.win), e.g: `https://api.allorigins.win/raw?url=https://pastebin.com/raw/4tZpaJV5`. For git-based services specifically, there's [raw.githack.com](https://raw.githack.com/) + --- -## Yarn Error +## Build & memory errors + +### Yarn Error For more info, see [Issue #1](https://github.com/Lissy93/dashy/issues/1) @@ -343,9 +365,7 @@ Alternatively, as a workaround, you have several options: - Try using [NPM](https://www.npmjs.com/get-npm) instead: So clone, cd, then run `npm install`, `npm run build` and `npm start` - Try using [Docker](https://www.docker.com/get-started) instead, and all of the system setup and dependencies will already be taken care of. So from within the directory, just run `docker build -t lissy93/dashy .` to build, and then use docker start to run the project, e.g: `docker run -it -p 8080:8080 lissy93/dashy` (see the [deploying docs](/docs/deployment#deploy-with-docker) for more info) ---- - -## `yarn build` fails inside the container +### `yarn build` fails inside the container If you run `docker exec yarn build` and get `vite: not found` (or similar), it's because the published image ships only production dependencies. The build toolchain (vite, vue-tsc, sass, etc.) lives in `devDependencies` and isn't installed in the runtime image. @@ -353,24 +373,7 @@ You almost certainly don't need to rebuild. Dashy's Express server reads `user-d If you genuinely need a fresh build (you've patched something in `src/`), do it on the host with `yarn install && yarn build`, or build a custom image from a checkout of the repo. ---- - -## Remote Config Not Loading - -If you've got a multi-page dashboard, and are hosting the additional config files yourself, then CORS rules will apply. A CORS error will look something like: - -```text -Access to XMLHttpRequest at 'https://example.com/raw/my-config.yml' from origin 'http://dashy.local' has been blocked by CORS policy: -No 'Access-Control-Allow-Origin' header is present on the requested resource. -``` - -The solution is to add the appropriate headers onto the target server, to allow it to accept requests from the origin where you're running Dashy. - -If it is a remote service, that you do not have admin access to, then another option is to proxy the request. Either host your own, or use a publicly accessible service, like [allorigins.win](https://allorigins.win), e.g: `https://api.allorigins.win/raw?url=https://pastebin.com/raw/4tZpaJV5`. For git-based services specifically, there's [raw.githack.com](https://raw.githack.com/) - ---- - -## High CPU or RAM Usage on Startup +### High CPU or RAM Usage on Startup When the Dashy container first starts, it runs a Vue production build in parallel with the server. This is **a one-time cost per container start**, but it briefly uses around **1–1.5 GB of RAM and 100% of one CPU core** for anywhere from 30 seconds to several minutes (depending on host speed). On Pi-class hardware or VMs with less than 1 GB of RAM, this spike can be enough to lock up the host. @@ -393,9 +396,7 @@ When the Dashy container first starts, it runs a Vue production build in paralle See also: [#1585](https://github.com/Lissy93/dashy/issues/1585), [#969](https://github.com/Lissy93/dashy/issues/969), [#1500](https://github.com/Lissy93/dashy/issues/1500), [#877](https://github.com/Lissy93/dashy/issues/877) ---- - -## Ineffective mark-compacts near heap limit Allocation failed +### Ineffective mark-compacts near heap limit Allocation failed If you see an error message, similar to: @@ -413,17 +414,35 @@ This is likely caused by insufficient memory allocation to the container. When t See also: [#380](https://github.com/Lissy93/dashy/issues/380), [#350](https://github.com/Lissy93/dashy/issues/350), [#297](https://github.com/Lissy93/dashy/issues/297), [#349](https://github.com/Lissy93/dashy/issues/349), [#510](https://github.com/Lissy93/dashy/issues/510), [#511](https://github.com/Lissy93/dashy/issues/511) and [#834](https://github.com/Lissy93/dashy/issues/834) ---- - -## Command failed with signal "SIGKILL" +### Command failed with signal "SIGKILL" In Docker, this can be caused by not enough memory. When the container first starts up, or has to rebuild, the memory usage spikes, and so a larger allocation may be required. This can be specified with, for example: `--memory=1024m`. For more info, see [Docker: Runtime options with Memory, CPUs, and GPUs](https://docs.docker.com/config/containers/resource_constraints/) See also [#624](https://github.com/Lissy93/dashy/issues/624) +### Node Sass does not yet support your current environment + +Caused by node-sass's binaries being built for a for a different architecture +To fix this, just run: `yarn rebuild node-sass` + +### Unreachable Code Error + +An error similar to: `Fatal error in , line 0. Unreachable code, FailureMessage Object: 0xffe6c8ac. Illegal instruction (core dumped)` +Is related to a bug in a downstream package, see [nodejs/docker-node#1477](https://github.com/nodejs/docker-node/issues/1477). +Usually, updating your system and packages will resolve the issue. + +See also: [#776](https://github.com/Lissy93/dashy/issues/776) + +### Error: Cannot find module './_baseValues' + +Clearing the cache should fix this: `yarn cache clean` +If the issue persists, remove (`rm -rf node_modules\ yarn.lock`) and reinstall (`yarn`) node_modules + --- -## Auth Validation Error: "should be object" +## Auth & OIDC + +### Auth Validation Error: "should be object" In V 1.6.5 an update was made that in the future will become a breaking change. You will need to update you config to reflect this before V 2.0.0 is released. In the meantime, your previous config will continue to function normally, but you will see a validation warning. The change means that the structure of the `appConfig.auth` object is now an object, which has a `users` property. @@ -446,21 +465,7 @@ auth: hash: xxx ``` ---- - -## App Not Starting After Update to 2.0.4 - -Version 2.0.4 introduced changes to how the config is read, and the app is build. If you were previously mounting `/public` as a volume, then this will over-write the build app, preventing it from starting. The solution is to just pass in the file(s) / sub-directories that you need. For example: - -```yaml -volumes: -- /srv/dashy/conf.yml:/app/user-data/conf.yml -- /srv/dashy/item-icons:/app/public/item-icons -``` - ---- - -## Keycloak Redirect Error +### Keycloak Redirect Error Check the [browser's console output](#how-to-open-browser-console), if you've not set any headers, you will likely see a CORS error here, which would be the source of the issue. @@ -485,9 +490,7 @@ nginx.ingress.kubernetes.io/enable-cors: "true" See also: #479, #409, #507, #491, #341, #520 ---- - -## OIDC or Keycloak failure on numeric client IDs +### OIDC or Keycloak failure on numeric client IDs If your IdP rejects the login with an *"invalid client"* / *"client not found"* error, and your `clientId` is a long numeric value, the cause is almost certainly YAML number parsing. @@ -508,9 +511,52 @@ The same applies to `auth.keycloak.clientId`. Dashy will print a warning in the See also: #1941 +### Redirect loop after login +Your `endpoint` probably includes `.well-known/openid-configuration`. Drop everything from `.well-known` onwards + +### invalid_redirect_uri +The redirect URI Authentik has registered for the provider doesn't exactly match the URL Dashy is being served from. Register both the bare URL and the trailing-slash version, and make sure the scheme matches (`http` vs `https`). + +### Login works in the browser but the dashboard refuses to save anything (403) +Dashy's server is rejecting the id_token. Check Dashy's container logs for `[auth-oidc] token verification failed`. Common causes: +- **Issuer mismatch**. Authentik is behind a reverse proxy that isn't sending `X-Forwarded-Proto: https`, so its discovery document advertises `http://` while you configured `https://` in Dashy. Fix the proxy or set `AUTHENTIK_HOST`/`AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS` on the Authentik containers +- **Audience mismatch**. The `aud` claim in the id_token is not `dashy`. Confirm the provider's Client ID is exactly `dashy` (no leading or trailing whitespace) +- **Dashy server can't reach Authentik**. The Dashy container fails to fetch the discovery document. Exec into the container and try `wget -qO- https://auth.example.com/application/o/dashy/.well-known/openid-configuration` +- **Clock skew**. The middleware allows 30 seconds of drift. If a container's clock is further off than that, `exp`/`iat` checks fail + +### Logged in but no admin controls +The id_token doesn't include the groups claim. Open browser devtools after logging in, find the call to `/application/o/dashy/userinfo/`, and check the response. You should see a `groups` array containing `dashy-admins`. If not: +- The `groups` scope mapping doesn't exist, or is not attached to the provider's property mappings +- The user is not in the `dashy-admins` group +- The conf.yml is missing `groups` from `scope:` and Authentik is therefore not sending it + +### Login works but Dashy errors on the callback with "OIDC signinCallback returned no user" +The id_token came back without a username claim. Confirm the provider has "profile" and "email" in its scopes and the "Include claims in id_token" is on + +### Sign-out leaves you stuck on Authentik +Dashy redirects to Authentik's end-session endpoint on logout. If Authentik's invalidation flow prompts for confirmation (the default), that's expected - click through it. To skip the prompt entirely, change the provider's invalidation flow to one without a consent stage. + +### Untrusted certificate from Authentik +Self-signed certs make Dashy's server-side fetch of the discovery document fail. Use a real cert (Let's Encrypt, or your homelab CA installed into the Dashy image) for the Authentik hostname. + +### Numeric client_id getting truncated +Don't use numeric-only client IDs. If you must, wrap the value in quotes in conf.yml so YAML treats it as a string + --- -## Mount Type Mismatch +## Docker & image issues + +### App Not Starting After Update to 2.0.4 + +Version 2.0.4 introduced changes to how the config is read, and the app is build. If you were previously mounting `/public` as a volume, then this will over-write the build app, preventing it from starting. The solution is to just pass in the file(s) / sub-directories that you need. For example: + +```yaml +volumes: +- /srv/dashy/conf.yml:/app/user-data/conf.yml +- /srv/dashy/item-icons:/app/public/item-icons +``` + +### Mount Type Mismatch ```text Error response from daemon: ... mount through procfd: not a directory: @@ -529,15 +575,7 @@ docker run -d -p 8080:8080 -v ~/dashy-data:/app/user-data lissy93/dashy:latest If you'd rather mount a single file (`-v ~/conf.yml:/app/user-data/conf.yml`), the host path must be a file that already exists, otherwise Docker creates a directory in its place and you'll see this error. ---- - -## Styles and Assets not Updating - -If you find that your styles and other visual assets work when visiting `ip:port` by not `dashy.domain.com`, then this is usually caused by caching. In your browser, do a hard-refresh (Ctrl + F5). If you use Cloudflare, then you can clear the cache through the management console, or set the cache level to Bypass for certain files, under the Rules tab. - ---- - -## DockerHub `toomanyrequests` +### DockerHub `toomanyrequests` This situation relates to error messages similar to one of the following, returned when pulling, updating or running the Docker container from Docker Hub. @@ -555,20 +593,18 @@ You have reached your pull rate limit. You may increase the limit by authenticat When DockerHub returns one of these errors, or a `429` status, that means you've hit your rate limit. This was [introduced](https://www.docker.com/blog/scaling-docker-to-serve-millions-more-developers-network-egress/) last year, and prevents unauthenticated or free users from running docker pull more than 100 times per 6 hours. You can [check your rate limit status](https://www.docker.com/blog/checking-your-current-docker-pull-rate-limits-and-status/) by looking for the `ratelimit-remaining` header in any DockerHub responses. -### Solution 1 - Use an alternate container registry +#### Solution 1 - Use an alternate container registry - Dashy is also available through GHCR, which at present does not have any hard limits. Just use `docker pull ghcr.io/lissy93/dashy:latest` to fetch the image - You can also build the image from source, by cloning the repo, and running `docker build -t dashy .` or use the pre-made docker compose -### Solution 2 - Increase your rate limits +#### Solution 2 - Increase your rate limits - Logging in to DockerHub will increase your rate limit from 100 requests to 200 requests per 6 hour period - Upgrading to a Pro for $5/month will increase your image requests to 5,000 per day, and any plans above have no rate limits - Since rate limits are counted based on your IP address, proxying your requests, or using a VPN may work ---- - -## Old image tags fail to pull +### Old image tags fail to pull If `docker pull` returns `manifest unknown` or `manifest for lissy93/dashy:arm32v7 not found`, the cause is a stale architecture-specific tag in your compose file or run command. Tags like `:arm32v7`, `:arm64v8`, and `:multi-arch` are no longer published. @@ -580,6 +616,34 @@ image: lissy93/dashy:latest Docker fetches the right architecture for your host automatically. To pin a version, use a semver tag, e.g. `lissy93/dashy:3.2.14`. +### Healthcheck Failing in Docker + +If `docker ps` shows the Dashy container as `unhealthy`, the periodic healthcheck (`node services/healthcheck.js`, run every 5 minutes by default) couldn't reach the local server. + +#### SSL-enabled Dashy + +The healthcheck reads the same cert paths as the main server (`/etc/ssl/certs/dashy-pub.pem` and `/etc/ssl/certs/dashy-priv.key`) to detect whether to probe HTTPS or HTTP. If you've mounted certs at non-default paths via `SSL_PUB_KEY_PATH` / `SSL_PRIV_KEY_PATH`, the healthcheck will pick those up automatically as long as those env vars are set in the container environment (not just at run time). + +#### Custom port + +If you've set `PORT` to override the default 8080, the healthcheck honors the same env var, so it should work without changes. Make sure `PORT` is set in the container environment, not just in the host-side Docker port mapping. + +#### Container is unhealthy past the grace period + +The healthcheck has a 20s `start-period` after which failures start counting. The image is prebuilt, so startup is just `node server.js` binding to a port - fast even on a Pi. If the container is still `unhealthy` past the grace period, the server has likely crashed. Check `docker logs ` for the real error (usually a malformed `conf.yml` or a missing `user-data` mount). + +See also: [#1410](https://github.com/Lissy93/dashy/issues/1410) + +### Docker Login Fails on Ubuntu + +Run `sudo apt install gnupg2 pass && gpg2 -k` + +--- + +## Styles and Assets not Updating + +If you find that your styles and other visual assets work when visiting `ip:port` by not `dashy.domain.com`, then this is usually caused by caching. In your browser, do a hard-refresh (Ctrl + F5). If you use Cloudflare, then you can clear the cache through the management console, or set the cache level to Bypass for certain files, under the Rules tab. + --- ## Config Validation Errors @@ -594,30 +658,6 @@ If the issue still persists, you should raise an issue. --- -## Node Sass does not yet support your current environment - -Caused by node-sass's binaries being built for a for a different architecture -To fix this, just run: `yarn rebuild node-sass` - ---- - -## Unreachable Code Error - -An error similar to: `Fatal error in , line 0. Unreachable code, FailureMessage Object: 0xffe6c8ac. Illegal instruction (core dumped)` -Is related to a bug in a downstream package, see [nodejs/docker-node#1477](https://github.com/nodejs/docker-node/issues/1477). -Usually, updating your system and packages will resolve the issue. - -See also: [#776](https://github.com/Lissy93/dashy/issues/776) - ---- - -## Error: Cannot find module './_baseValues' - -Clearing the cache should fix this: `yarn cache clean` -If the issue persists, remove (`rm -rf node_modules\ yarn.lock`) and reinstall (`yarn`) node_modules - ---- - ## Invalid Host Header while running through ngrok Just add the [-host-header](https://ngrok.com/docs#http-host-header) flag, e.g. `ngrok http 8080 -host-header="localhost:8080"` @@ -630,12 +670,6 @@ Please acknowledge the difference between errors and warnings before raising an --- -## Docker Login Fails on Ubuntu - -Run `sudo apt install gnupg2 pass && gpg2 -k` - ---- - ## Status Checks Failing If you're using status checks, and despite a given service being online, the check is displaying an error, there are a couple of things you can look at: @@ -667,61 +701,41 @@ If you're serving Dashy though a CDN, instead of using the Node server or Docker --- -## Healthcheck Failing in Docker +## Widgets -If `docker ps` shows the Dashy container as `unhealthy`, the periodic healthcheck (`node services/healthcheck.js`, run every 5 minutes by default) couldn't reach the local server. +### Widget Errors -### SSL-enabled Dashy - -The healthcheck reads the same cert paths as the main server (`/etc/ssl/certs/dashy-pub.pem` and `/etc/ssl/certs/dashy-priv.key`) to detect whether to probe HTTPS or HTTP. If you've mounted certs at non-default paths via `SSL_PUB_KEY_PATH` / `SSL_PRIV_KEY_PATH`, the healthcheck will pick those up automatically as long as those env vars are set in the container environment (not just at run time). - -### Custom port - -If you've set `PORT` to override the default 8080, the healthcheck honors the same env var, so it should work without changes. Make sure `PORT` is set in the container environment, not just in the host-side Docker port mapping. - -### Container is unhealthy past the grace period - -The healthcheck has a 20s `start-period` after which failures start counting. The image is prebuilt, so startup is just `node server.js` binding to a port - fast even on a Pi. If the container is still `unhealthy` past the grace period, the server has likely crashed. Check `docker logs ` for the real error (usually a malformed `conf.yml` or a missing `user-data` mount). - -See also: [#1410](https://github.com/Lissy93/dashy/issues/1410) - ---- - -## Widget Errors - -### Find Error Message +#### Find Error Message If an error occurs when fetching or rendering results, you will see a short message in the UI. If that message doesn't adequately explain the problem, then you can [open the browser console](/docs/troubleshooting#how-to-open-browser-console) to see more details. -### Check Config +#### Check Config Before proceeding, ensure that if the widget requires auth your API is correct, and for custom widgets, double check that the URL and protocol is correct. -### Timeout Error +#### Timeout Error If the error message in the console includes: `Error: timeout of 500ms exceeded`, then your Glances endpoint is slower to respond than expected. You can fix this by [setting timeout](/docs/widgets#setting-timeout) to a larger value. This is done on each widget, with the `timeout` attribute, and is specified in ms. E.g. `timeout: 5000` would only fail if no response is returned within 5 seconds. -### CORS error +#### CORS error If the console message mentions to corss-origin blocking, then this is a CORS error, see: [Fixing Widget CORS Errors](#widget-cors-errors) -### More Info +#### More Info If you're able to, you can find more information about why the request may be failing in the Dev Tools under the Network tab, and you can ensure your endpoint is correct and working using a tool like Postman. ---- - -## Widget CORS Errors +### Widget CORS Errors The most common widget issue is a CORS error. This is a browser security mechanism which prevents the client-side app (Dashy) from from accessing resources on a remote origin, without that server's explicit permission (e.g. with headers like Access-Control-Allow-Origin). See the MDN Docs for more info: [Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). There are several ways to fix a CORS error: -### Option 1 - Ensure Correct Protocol +#### Option 1 - Ensure Correct Protocol You will get a CORS error if you try and access a http service from a https source. So ensure that the URL you are requesting has the right protocol, and is correctly formatted. -### Option 2 - Set Headers +#### Option 2 - Set Headers If you have control over the destination (e.g. for a self-hosted service), then you can simply apply the correct headers. Add the `Access-Control-Allow-Origin` header, with the value of either `*` to allow requests from anywhere, or more securely, the host of where Dashy is served from. For example: @@ -738,25 +752,21 @@ Access-Control-Allow-Origin: * For more info on how to set headers, see: [Setting Headers](/docs/management#setting-headers) in the management docs -### Option 3 - Proxying Request +#### Option 3 - Proxying Request You can route requests through Dashy's built-in CORS proxy. Instructions and more details can be found [here](/docs/widgets#proxying-requests). If you don't have control over the target origin, and you are running Dashy either through Docker, with the Node server or on Netlify, then this solution will work for you. Just add the `useProxy: true` option to the failing widget. -### Option 4 - Use a plugin +#### Option 4 - Use a plugin For testing purposes, you can use an addon, which will disable the CORS checks. You can get the Allow-CORS extension for [Chrome](https://chrome.google.com/webstore/detail/allow-cors-access-control/lhobafahddgcelffkeicbaginigeejlf?hl=en-US) or [Firefox](https://addons.mozilla.org/en-US/firefox/addon/access-control-allow-origin/), more details [here](https://mybrowseraddon.com/access-control-allow-origin.html) ---- - -## CORS Proxy `connect ECONNREFUSED ...` or `getaddrinfo ENOTFOUND ...` +### CORS Proxy `connect ECONNREFUSED ...` or `getaddrinfo ENOTFOUND ...` The target host is unreachable from the Dashy container. If the target is on the same host as Dashy, **don't use `localhost`** - inside a Docker container that resolves to the container itself, not the host. Use the host's LAN IP, the Docker bridge gateway, or `host.docker.internal` (on Docker Desktop). If the target is on a different Docker network, attach Dashy to that network too. ---- - -## CORS Proxy `Target-URL host '...' is blocked` / `must use http:// or https://` +### CORS Proxy `Target-URL host '...' is blocked` / `must use http:// or https://` To prevent the CORS proxy from being abused as a Server-Side Request Forgery vector, Dashy refuses to proxy a small number of host/scheme combinations by default: @@ -773,18 +783,14 @@ The variable is named so loudly because flipping it on a Dashy instance that's e Note that this is an all-or-nothing escape hatch, not a per-host allowlist. If you only need to reach one specific host that's currently blocked, please open a feature request describing the use case. ---- - -## Widget Shows Error Incorrectly +### Widget Shows Error Incorrectly When there's an error fetching or displaying a widgets data, then it will be highlighted in yellow, and a message displayed on the UI. In some instances, this is a false positive, and the widget is actually functioning correctly. If this is the case, you can disable the UI error message of a given widget by setting: `ignoreErrors: true` ---- - -## Weather Forecast Widget 401 +### Weather Forecast Widget 401 A 401 error means your API key is invalid, it is not an issue with Dashy. @@ -801,9 +807,7 @@ A future update will be pushed out, to use a free weather forecasting API. See also: [#803](https://github.com/Lissy93/dashy/issues/803), [#789](https://github.com/Lissy93/dashy/issues/789), [#577](https://github.com/Lissy93/dashy/issues/577), [#621](https://github.com/Lissy93/dashy/issues/621), [#578](https://github.com/Lissy93/dashy/issues/578), [#806](https://github.com/Lissy93/dashy/discussions/806) ---- - -## Widget Displaying Inaccurate Data +### Widget Displaying Inaccurate Data If any widget is not displaying the data you expect, first confirm that your config is correct, then try manually calling the API endpoint. @@ -813,6 +817,10 @@ If the API itself is returning incorrect, incomplete or inaccurate data then an See also: [#807](https://github.com/Lissy93/dashy/issues/807) (re, domain monitor) +### Public IP Widget not working for `ipinfo` or `ipquery` providers + +If you've set `options.provider` to either `ipinfo` and `ipquery` and the requests are failing, it's likley that they're being blocked. Check your adblocker (uBlock, PrivacyBadger, etc), DNS block lists (PiHole, AdGuard, etc). Or, try proxying the request (with `useProxy: true`) or just try a different provider. + --- ## Font Awesome Icons not Displaying @@ -845,7 +853,9 @@ As a workaround, you could either: --- -## How to Reset Local Settings +## How-To / Reference + +### How to Reset Local Settings Some settings are stored locally, in the browser's storage. @@ -858,29 +868,27 @@ You can also view any and all data that Dashy is storing, using the developer to For a full list of all data that may be cached, see the [Privacy Docs](/docs/privacy#browser-storage). ---- +### How to make a bug report -## How to make a bug report - -### Step 1 - Where to open issues +#### Step 1 - Where to open issues You will need a GitHub account in order to raise a ticket. You can then [click here](https://github.com/Lissy93/dashy/issues/new?assignees=lissy93&labels=%F0%9F%90%9B+Bug&template=bug.yml&title=%5BBUG%5D+%3Ctitle%3E) to open a new bug report. -### Step 2 - Checking it's not already covered +#### Step 2 - Checking it's not already covered Before submitting, please check that: - A similar ticket has not previously been opened - The issue is not covered in the [troubleshooting guide](/docs/troubleshooting) or [docs](https://github.com/Lissy93/dashy/tree/master/docs#readme) -### Step 3 - Describe the Issue +#### Step 3 - Describe the Issue Your ticket will likely be dealt with more effectively if you can explain the issue clearly, and provide all relevant supporting material. Complete the fields, asking for your environment info and version of Dashy. Then describe the issue, briefly explaining the steps to reproduce, expected outcome and actual outcome. -### Step 4 - Provide Supporting Info +#### Step 4 - Provide Supporting Info Where relevant please also include: @@ -892,7 +900,7 @@ Where relevant please also include: _Take care to redact any personal info, (like IP addresses, auth hashes or API keys)._ -### Step 5 - Fix Released +#### Step 5 - Fix Released A maintainer will aim to respond within 48 hours. The timeframe for resolving your issue, will vary depending on severity of the bug and the complexity of the fix. @@ -900,15 +908,7 @@ You will be notified on your ticket, when a fix has been released. Finally, be sure to remain respectful to other users and project maintainers, in line with the [Contributor Covenant Code of Conduct](https://github.com/Lissy93/dashy/blob/master/.github/CODE_OF_CONDUCT#contributor-covenant-code-of-conduct). ---- - -## Public IP Widget not working for `ipinfo` or `ipquery` providers - -If you've set `options.provider` to either `ipinfo` and `ipquery` and the requests are failing, it's likley that they're being blocked. Check your adblocker (uBlock, PrivacyBadger, etc), DNS block lists (PiHole, AdGuard, etc). Or, try proxying the request (with `useProxy: true`) or just try a different provider. - ---- - -## How-To Open Browser Console +### How-To Open Browser Console When raising a bug, one crucial piece of info needed is the browser's console output. This will help the developer diagnose and fix the issue. @@ -921,9 +921,7 @@ To open dev tools, and jump straight to the console: For more detailed walk through, see [this article](https://support.shortpoint.com/support/solutions/articles/1000222881-save-browser-console-file). ---- - -## Git Contributions not Displaying +### Git Contributions not Displaying If you've contributed to Dashy (or any other project), but your contributions are not showing up on your GH profile, or in Dashy's [Credits Page](/docs/credits), then this is likely a git config issue. diff --git a/docs/widgets.md b/docs/widgets.md index 6ca9bc1c..77677c65 100644 --- a/docs/widgets.md +++ b/docs/widgets.md @@ -160,10 +160,11 @@ A simple, live-updating local weather component, showing temperature, conditions --- | --- | --- | --- **`apiKey`** | `string` | Required | Your OpenWeatherMap API key. You can get one for free at [openweathermap.org](https://openweathermap.org/) **`city`** | `string` | Required | A city name to use for fetching weather. This can also be a state code or country code, following the ISO-3166 format +**`cityId`** | `number` | _Optional_ | An OpenWeatherMap numeric city ID, used to disambiguate cities that share a name. You can find the ID in the URL of the city's page on [openweathermap.org](https://openweathermap.org/) (e.g. `2643743` for London, GB). If provided, this will override the `city` option **`units`** | `string` | _Optional_ | The units to use for displaying data, can be either `metric` or `imperial`. Defaults to `metric` **`hideDetails`** | `boolean` | _Optional_ | If set to `true`, the additional details (wind, humidity, pressure, etc) will not be shown. Defaults to `false` -**`lat`** | `number` | _Optional_ | To show weather for a specific location, you can provide the latitude and longitude coordinates. If provided, this will override the `city` option -**`lon`** | `number` | _Optional_ | To show weather for a specific location, you can provide the latitude and longitude coordinates. If provided, this will override the `city` option +**`lat`** | `number` | _Optional_ | To show weather for a specific location, you can provide the latitude and longitude coordinates. If provided, this will override the `city` and `cityId` options +**`lon`** | `number` | _Optional_ | To show weather for a specific location, you can provide the latitude and longitude coordinates. If provided, this will override the `city` and `cityId` options #### Example @@ -197,6 +198,9 @@ Displays the weather (temperature and conditions) for the next few days for a gi --- | --- | --- | --- **`apiKey`** | `string` | Required | Your OpenWeatherMap API key. You can get one at [openweathermap.org](https://openweathermap.org/) or for free via the [OWM Student Plan](https://home.openweathermap.org/students) **`city`** | `string` | Required | A city name to use for fetching weather. This can also be a state code or country code, following the ISO-3166 format +**`cityId`** | `number` | _Optional_ | An OpenWeatherMap numeric city ID, used to disambiguate cities that share a name. You can find the ID in the URL of the city's page on [openweathermap.org](https://openweathermap.org/) (e.g. `2643743` for London, GB). If provided, this will override the `city` option +**`lat`** | `number` | _Optional_ | Latitude for a specific location. If provided alongside `lon`, this will override the `city` and `cityId` options +**`lon`** | `number` | _Optional_ | Longitude for a specific location. If provided alongside `lat`, this will override the `city` and `cityId` options **`numDays`** | `number` | _Optional_ | The number of days to display of forecast info to display. Defaults to `4`, max `16` days **`units`** | `string` | _Optional_ | The units to use for displaying data, can be either `metric` or `imperial`. Defaults to `metric` **`hideDetails`** | `boolean` | _Optional_ | If set to `true`, the additional details (wind, humidity, pressure, etc) will not be shown. Defaults to `false`