josh/dashy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix inconsistent markdown formatting.

Browse Source 
This changes all of the documentation markdown files to follow
the same rules. The rules I've applied are from
https://github.com/DavidAnson/markdownlint/blob/v0.25.1/doc/Rules.md

The reason I felt it was necessary
to change all the files was
that there were a lot inconsistencies in how the markdown was used.
Ranging from header levels to some headers having a new line before
content and some not.
This commit is contained in:
David Alasow
2022-08-23 09:57:02 +02:00
parent 99463413b1
commit 2d731d3ed3
23 changed files with 912 additions and 542 deletions
Download Patch File Download Diff File Expand all files Collapse all files

96
docs/troubleshooting.md
View File

@@ -5,7 +5,8 @@
>
> _Found something not listed here? Consider adding it, to help other users._
### Contents
## Contents
- [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)
@@ -41,7 +42,6 @@
- [How-To Open Browser Console](#how-to-open-browser-console)
- [Git Contributions not Displaying](#git-contributions-not-displaying)
---
## `Refused to Connect` in Modal or Workspace View
@@ -53,20 +53,23 @@ As defined in [RFC-7034](https://datatracker.ietf.org/doc/html/rfc7034), for any
These settings are usually set in the config file for the web server that's hosting the target application, here are some examples of how to enable cross-origin access with common web servers:
### NGINX
In NGINX, you can use the [`add_header`](https://nginx.org/en/docs/http/ngx_http_headers_module.html) module within the app block.
```
```text
server {
...
add_header X-Frame-Options SAMEORIGIN always;
}
```
Then reload with `service nginx reload`
### Caddy
In Caddy, you can use the [`header`](https://caddyserver.com/docs/caddyfile/directives/header) directive.
```yaml
```text
header {
X-Frame-Options SAMEORIGIN
}
@@ -76,13 +79,13 @@ header {
In Apache, you can use the [`mod_headers`](https://httpd.apache.org/docs/current/mod/mod_headers.html) module to set the `X-Frame-Options` in your config file. This file is usually located somewhere like `/etc/apache2/httpd.conf
```
```text
Header set X-Frame-Options: "ALLOW-FROM http://[dashy-location]/"
```
### LightHttpd
```
```text
Content-Security-Policy: frame-ancestors 'self' https://[dashy-location]/
```
@@ -122,12 +125,14 @@ For more info, see [Issue #1](https://github.com/Lissy93/dashy/issues/1)
First of all, check that you've got yarn installed correctly - see the [yarn installation docs](https://classic.yarnpkg.com/en/docs/install) for more info.
If you're getting an error about scenarios, then you've likely installed the wrong yarn... (you're [not](https://github.com/yarnpkg/yarn/issues/2821) the only one!). You can fix it by uninstalling, adding the correct repo, and reinstalling, for example, in Debian:
- `sudo apt remove yarn`
- `curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -`
- `echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list`
- `sudo apt update && sudo apt install yarn`
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:80 lissy93/dashy` (see the [deploying docs](https://github.com/Lissy93/dashy/blob/master/docs/deployment.md#deploy-with-docker) for more info)
@@ -137,7 +142,7 @@ Alternatively, as a workaround, you have several options:
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.
```
@@ -148,11 +153,11 @@ If it is a remote service, that you do not have admin access to, then another op
---
## Ineffective mark-compacts near heap limit Allocation failed
## Ineffective mark-compacts near heap limit Allocation failed
If you see an error message, similar to:
```
```text
<--- Last few GCs --->
[61:0x74533040] 229060 ms: Mark-sweep (reduce) 127.1 (236.9) -> 127.1 (137.4) MB, 5560.7 / 0.3 ms (average mu = 0.286, current mu = 0.011) allocation failure scavenge might not succeed
@@ -162,7 +167,6 @@ If you see an error message, similar to:
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
```
This is likely caused by insufficient memory allocation to the container. When the container first starts up, or has to rebuild, the memory usage spikes, and if there isn't enough memory, it may terminate. 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: [#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)
@@ -232,7 +236,7 @@ For more details on how to set headers, see the [Example Headers](/docs/manageme
If you're running in Kubernetes, you will need to enable CORS ingress rules, see [docs](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#enable-cors), e.g:
```
```text
nginx.ingress.kubernetes.io/cors-allow-origin: "https://dashy.example.com"
nginx.ingress.kubernetes.io/enable-cors: "true"
```
@@ -243,7 +247,7 @@ See also: #479, #409, #507, #491, #341, #520
## Docker Directory
```
```text
Error response from daemon: OCI runtime create failed: container_linux.go:380:
starting container process caused: process_linux.go:545: container init caused:
rootfs_linux.go:76: mounting "/home/ubuntu/my-conf.yml" to rootfs at
@@ -278,23 +282,27 @@ If you find that your styles and other visual assets work when visiting `ip:port
This situation relates to error messages similar to one of the following, returned when pulling, updating or running the Docker container from Docker Hub.
```
```text
Continuing execution. Pulling image lissy93/dashy:release-1.6.0
error pulling image configuration: toomanyrequests
```
or
```
```text
You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit
```
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 availible 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
@@ -302,6 +310,7 @@ You can [check your rate limit status](https://www.docker.com/blog/checking-your
---
## Config Validation Errors
The configuration file is validated against [Dashy's Schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.json) using AJV.
First, check that your syntax is valid, using [YAML Validator](https://codebeautify.org/yaml-validator/) or [JSON Validator](https://codebeautify.org/jsonvalidator). If the issue persists, then take a look at the [schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.json), and verify that the field you are trying to add/ modify matches the required format. You can also use [this tool](https://www.jsonschemavalidator.net/s/JFUj7X9J) to validate your JSON config against the schema, or run `yarn validate-config`.
@@ -313,6 +322,7 @@ 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`
@@ -326,21 +336,23 @@ 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"`
---
## Warnings in the Console during deploy
Please acknowledge the difference between errors and warnings before raising an issue about messages in the console. It's not unusual to see warnings about a new version of a certain package being available, an asset bundle bing oversized or a service worker not yet having a cache. These shouldn't have any impact on the running application, so please don't raise issues about these unless it directly relates to a bug or issue you're experiencing. Errors on the other hand should not appear in the console, and they are worth looking into further.
---
@@ -352,15 +364,18 @@ 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:
If your service requires requests to include any authorization in the headers, then use the `statusCheckHeaders` property, as described in the [docs](/docs/status-indicators.md#setting-custom-headers).
If you are still having issues, it may be because your target application is blocking requests from Dashy's IP. This is a [CORS error](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), and can be fixed by setting the headers on your target app, to include:
```
```text
Access-Control-Allow-Origin: https://location-of-dashy/
Vary: Origin
```
If the URL you are checking has an unsigned certificate, or is not using HTTPS, then you may need to disable the rejection of insecure requests. This can be done by setting `statusCheckAllowInsecure` to true for a given item.
If your service is online, but responds with a status code that is not in the 2xx range, then you can use `statusCheckAcceptCodes` to set an accepted status code.
@@ -381,19 +396,24 @@ If you're serving Dashy though a CDN, instead of using the Node server or Docker
## 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 addequatley explain the problem, then you can [open the browser console](/docs/troubleshooting.md#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](https://github.com/Lissy93/dashy/blob/master/docs/widgets.md#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.
---
@@ -404,33 +424,34 @@ The most common widget issue is a CORS error. This is a browser security mechani
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:
```
```text
Access-Control-Allow-Origin: https://url-of-dashy.local
```
or
```
```text
Access-Control-Allow-Origin: *
```
For more info on how to set headers, see: [Setting Headers](/docs/management.md#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.md#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)
@@ -498,6 +519,7 @@ If the copy to clipboard feature (either under Config --> Export, or Item --> Co
The most common reason for this, is if you not running the app over HTTPS. Copying to the clipboard requires the app to be running in a secure origin / aka have valid HTTPS cert. You can read more about this [here](https://stackoverflow.com/a/71876238/979052).
As a workaround, you could either:
- Highlight the text and copy / <kbd>Ctrl</kbd> + <kbd>C</kbd>
- Or setup SSL - [here's a guide](https://github.com/Lissy93/dashy/blob/master/docs/management.md#ssl-certificates) on doing so
@@ -520,24 +542,25 @@ For a full list of all data that may be cached, see the [Privacy Docs](/docs/pri
## 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](https://github.com/Lissy93/dashy/blob/master/docs/troubleshooting.md) 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:
@@ -547,9 +570,9 @@ Where relevant please also include:
- If client-side issue, then include the browser logs ([see how](#how-to-open-browser-console))
- If server-side / during deployment, include the terminal output
_Take care to redact any personal info, (like IP addresses, auth hashes or API keys)_
_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.
@@ -560,11 +583,13 @@ Finally, be sure to remain respectful to other users and project maintainers, in
---
## 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.
If you've been asked for this info, but are unsure where to find it, then it is under the "Console" tab, in the browsers developer tools, which can be opened with <kbd>F12</kbd>. You can right-click the console, and select Save As to download the log.
To open dev tools, and jump straight to the console:
- Win / Linux: <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>J</kbd>
- MacOS: <kbd>Cmd</kbd> + <kbd>Option</kbd> + <kbd>J</kbd>
@@ -579,6 +604,7 @@ If you've contributed to Dashy (or any other project), but your contributions ar
These statistics are generated using the username / email associated with commits. This info needs to be setup on your local machine using [`git config`](https://git-scm.com/docs/git-config).
Run the following commands (replacing name + email with your info):
- `git config --global user.name "John Doe"`
- `git config --global user.email johndoe@example.com`