Merge branch 'master' of github.com:Lissy93/dashy into FEATURE/minimal-view
This commit is contained in:
Alicia Sykes
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 925 KiB After Width: | Height: | Size: 990 KiB |
@@ -72,6 +72,7 @@ To disallow any changes from being written to disk via the UI config editor, set
|
||||
**`externalStyleSheet`** | `string` or `string[]` | _Optional_ | Either a URL to an external stylesheet or an array or URLs, which can be applied as themes within the UI
|
||||
**`customCss`** | `string` | _Optional_ | Raw CSS that will be applied to the page. This can also be set from the UI. Please minify it first.
|
||||
**`hideComponents`** | `object` | _Optional_ | A list of key page components (header, footer, search, settings, etc) that are present by default, but can be removed using this option. See [`appConfig.hideComponents`](#appconfighideComponents-optional)
|
||||
**`enableMultiTasking`** | `boolean` | _Optional_ | If set to true, will keep apps open in the background when in the workspace view. Useful for quickly switching between multiple sites, and preserving their state, but comes at the cost of performance.
|
||||
**`allowConfigEdit`** | `boolean` | _Optional_ | Should prevent / allow the user to write configuration changes to the conf.yml from the UI. When set to `false`, the user can only apply changes locally using the config editor within the app, whereas if set to `true` then changes can be written to disk directly through the UI. Defaults to `true`. Note that if authentication is enabled, the user must be of type `admin` in order to apply changes globally.
|
||||
**`enableErrorReporting`** | `boolean` | _Optional_ | Enable reporting of unexpected errors and crashes. This is off by default, and **no data will ever be captured unless you explicitly enable it**. Turning on error reporting helps previously unknown bugs get discovered and fixed. Dashy uses [Sentry](https://github.com/getsentry/sentry) for error reporting. Defaults to `false`.
|
||||
**`sentryDsn`** | `boolean` | _Optional_ | If you need to monitor errors in your instance, then you can use Sentry to collect and process bug reports. Sentry can be self-hosted, or used as SaaS, once your instance is setup, then all you need to do is pass in the DSN here, and enable error reporting. You can learn more on the [Sentry DSN Docs](https://docs.sentry.io/product/sentry-basics/dsn-explainer/). Note that this will only ever be used if `enableErrorReporting` is explicitly enabled.
|
||||
@@ -153,7 +154,7 @@ To disallow any changes from being written to disk via the UI config editor, set
|
||||
|
||||
**Field** | **Type** | **Required**| **Description**
|
||||
--- | --- | --- | ---
|
||||
**`icon`** | `string` | _Optional_ | The icon for a given item or section. Can be a font-awesome icon, favicon, remote URL or local URL. If set to `favicon`, the icon will be automatically fetched from the items website URL. To use font-awesome, specify the category, followed by the icon name, e.g. `fas fa-rocket`, `fab fa-monero` or `fal fa-duck` - note that to use pro icons, you mut specify `appConfig.fontAwesomeKey`. If set to `generative`, then a unique icon is generated from the apps URL or IP. You can also use hosted any by specifying it's URL, e.g. `https://i.ibb.co/710B3Yc/space-invader-x256.png`. To use a local image, first store it in `./public/item-icons/` (or `-v /app/public/item-icons/` in Docker) , and reference it by name and extension - e.g. set `image.png` to use `./public/item-icon/image.png`, you can also use sub-folders if you have a lot of icons, to keep them organised.
|
||||
**`icon`** | `string` | _Optional_ | The icon for a given item or section. Can be a font-awesome icon, favicon, remote URL or local URL. If set to `favicon`, the icon will be automatically fetched from the items website URL. To use font-awesome, specify the category, followed by the icon name, e.g. `fas fa-rocket`, `fab fa-monero` or `fal fa-duck` - note that to use pro icons, you mut specify `appConfig.fontAwesomeKey`. Similarly, you can also use [simple-icons](https://simpleicons.org/) by setting icon to `si-[icon-name]` or [material-design-icons](https://dev.materialdesignicons.com/icons) by setting icon to `mdi-[icon-name]`. If set to `generative`, then a unique icon is generated from the apps URL or IP. You can also use hosted any by specifying it's URL, e.g. `https://i.ibb.co/710B3Yc/space-invader-x256.png`. To use a local image, first store it in `./public/item-icons/` (or `-v /app/public/item-icons/` in Docker) , and reference it by name and extension - e.g. set `image.png` to use `./public/item-icon/image.png`, you can also use sub-folders if you have a lot of icons, to keep them organised.
|
||||
|
||||
**[⬆️ Back to Top](#configuring)**
|
||||
|
||||
|
||||
@@ -10,18 +10,27 @@ Contributing to the code or documentation is super helpful. You can fix a bug, a
|
||||
## Add Translations
|
||||
If you speak another language, then adding translations would be really helpful, and you will be credited in the readme for your work. Multi-language support makes Dashy accessible for non-English speakers, which I feel is important. This is a very quick and easy task, as all application text is located in [`locales/en.json`](https://github.com/Lissy93/dashy/blob/master/src/assets/locales/en.json), so adding a new language is as simple as copying this file and translating the values. You don't have to translate it all, as any missing attributes will just fallback to English. For a full tutorial, see the [Multi-Language Support Docs](https://github.com/Lissy93/dashy/blob/master/docs/multi-language-support.md).
|
||||
|
||||
## Take a 2-minute survey
|
||||
Help improve Dashy by taking a very short, 6-question survey. This will give me a better understanding of what is important to you, so that I can make Dashy better in the future :)
|
||||
|
||||
[](https://n9fy6xak9yd.typeform.com/to/gl0L68ou)
|
||||
|
||||
## Share your dashboard
|
||||
Dashy now has a [Showcase](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md#dashy-showcase-) where you can show off a screenshot of your dashboard, and get inspiration from other users. I also really enjoy seeing how people are using Dashy. To [submit your dashboard](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md#submitting-your-dashboard), please either open a PR or raise an issue.
|
||||
|
||||
## Improve the Docs
|
||||
Found a typo, or something that isn't as clear as it could be? Maybe I've missed something off altogether, or you hit a roadblock that took you a while to figure out. Submitting a pull request to add to or improve the documentation will help future users get Dashy up and running more easily.
|
||||
All content is located either in the [`./README.md`](/README.md) or [`/docs/`](/docs) directory, and synced to the Wiki and website using a GH [action](/actions/workflows/wiki-sync.yml).
|
||||
|
||||
## Raise a bug
|
||||
If you've found a bug, then please do raise it as an issue. This will help me know if there's something that needs fixing. Try and include as much detail as possible, such as your environment, steps to reproduce, any console output and maybe an example screenshot or recording if necessary. You can [Raise a Bug here](https://github.com/Lissy93/dashy/issues/new?assignees=Lissy93&labels=%F0%9F%90%9B+Bug&template=bug-report---.md&title=%5BBUG%5D) 🐛.
|
||||
If you've found a bug, then please do raise it as an issue. This will help me know if there's something that needs fixing. Try and include as much detail as possible, such as your environment, steps to reproduce, any console output and maybe an example screenshot or recording if necessary.
|
||||
|
||||
[](https://github.com/Lissy93/dashy/issues/new?assignees=Lissy93&labels=%F0%9F%90%9B+Bug&template=bug-report---.md&title=%5BBUG%5D)
|
||||
|
||||
## Join the discussion
|
||||
I've enabled the discussion feature on GitHub, here you can share tips and tricks, useful information, or your dashboard. You can also ask questions, and offer basic support to other users.
|
||||
|
||||
## Share your dashboard
|
||||
Dashy now has a [Showcase](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md#dashy-showcase-) where you can show off a screenshot of your dashboard, and get inspiration from other users. I also really enjoy seeing how people are using Dashy. To [submit your dashboard](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md#submitting-your-dashboard), please either open a PR or raise an issue.
|
||||
[](https://github.com/Lissy93/dashy/discussions)
|
||||
|
||||
## Spread the word
|
||||
Dashy is still a relatively young project, and as such not many people know of it. It would be great to see more users, and so it would be awesome if you could consider sharing on social platforms.
|
||||
@@ -42,8 +51,9 @@ Dashy is on the following platforms, and if you could spare a few seconds to giv
|
||||
|
||||
[](https://www.producthunt.com/posts/dashy)
|
||||
[](https://alternativeto.net/software/dashy/about/)
|
||||
[](https://www.slant.co/improve/topics/27783/viewpoints/1/~self-hosted-homelab-startpage~dashy)
|
||||
[](https://github.com/Lissy93/dashy/stargazers)
|
||||
|
||||
[](https://hub.docker.com/r/lissy93/dashy)
|
||||
|
||||
## Make a small donation
|
||||
Please only do this is you can definitely afford to. Don't feel any pressure to donate anything, as Dashy and my other projects will always be 100% free, for everyone, for ever.
|
||||
@@ -65,7 +75,7 @@ Sponsoring will give you several perks, from $1 / £0.70 per month, as well as a
|
||||
## Request a feature via BountySource
|
||||
BountySource is a platform for sponsoring the development of certain features on open source projects. If there is a feature you'd like implemented into Dashy, but either isn't high enough priority or is deemed to be more work than it's worth, then you can instead contribute a bounty towards it's development. You won't pay a penny until your proposal is fully built, and you are satisfied with the result. This helps support the developers, and makes Dashy better for everyone.
|
||||
|
||||
For more info, see [Dashy on Bounty Source](https://www.bountysource.com/teams/dashy)
|
||||
[](https://www.bountysource.com/teams/dashy)
|
||||
|
||||
## Enable Anonymous Bug Reports
|
||||
[Sentry](https://github.com/getsentry/sentry) is an open source error tracking and performance monitoring tool, which enables the identification any errors which occur in the production app (only if you enable it). It helps me to discover bugs I was unaware of, and then fix them, in order to make Dashy more reliable long term. This is a simple, yet really helpful step you can take to help improve Dashy.
|
||||
|
||||
@@ -32,6 +32,13 @@
|
||||
<sub><b>Alicia Sykes</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/EVOTk">
|
||||
<img src="https://avatars.githubusercontent.com/u/45015615?v=4" width="80;" alt="EVOTk"/>
|
||||
<br />
|
||||
<sub><b>EVOTk</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/evroon">
|
||||
<img src="https://avatars.githubusercontent.com/u/11857441?v=4" width="80;" alt="evroon"/>
|
||||
@@ -40,10 +47,17 @@
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/EVOTk">
|
||||
<img src="https://avatars.githubusercontent.com/u/45015615?v=4" width="80;" alt="EVOTk"/>
|
||||
<a href="https://github.com/snyk-bot">
|
||||
<img src="https://avatars.githubusercontent.com/u/19733683?v=4" width="80;" alt="snyk-bot"/>
|
||||
<br />
|
||||
<sub><b>EVOTk</b></sub>
|
||||
<sub><b>Snyk Bot</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/UrekD">
|
||||
<img src="https://avatars.githubusercontent.com/u/38784343?v=4" width="80;" alt="UrekD"/>
|
||||
<br />
|
||||
<sub><b>UrekD</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
@@ -52,7 +66,8 @@
|
||||
<br />
|
||||
<sub><b>Begin</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
</td></tr>
|
||||
<tr>
|
||||
<td align="center">
|
||||
<a href="https://github.com/deepsourcebot">
|
||||
<img src="https://avatars.githubusercontent.com/u/60907429?v=4" width="80;" alt="deepsourcebot"/>
|
||||
@@ -67,14 +82,6 @@
|
||||
<sub><b>Ryan Turner</b></sub>
|
||||
</a>
|
||||
</td></tr>
|
||||
<tr>
|
||||
<td align="center">
|
||||
<a href="https://github.com/snyk-bot">
|
||||
<img src="https://avatars.githubusercontent.com/u/19733683?v=4" width="80;" alt="snyk-bot"/>
|
||||
<br />
|
||||
<sub><b>Snyk Bot</b></sub>
|
||||
</a>
|
||||
</td></tr>
|
||||
</table>
|
||||
<!-- readme: contributors -end -->
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Welcome to Dashy, so glad you're here :) Deployment is super easy, and there are several methods available depending on what type of system you're using. If you're self-hosting, then deploying with Docker (or similar container engine) is the recommended approach.
|
||||
|
||||
#### Quick Start
|
||||
If you want to skip the fuss, and get straight down to it, then you can spin up a new instance of Dashy by running:
|
||||
If you want to skip the fuss, and [get straight down to it](./docs/quick-start.md), then you can spin up a new instance of Dashy by running:
|
||||
```
|
||||
docker run -p 8080:80 lissy93/dashy
|
||||
```
|
||||
@@ -25,7 +25,18 @@ Once you've got Dashy up and running, you'll want to configure it with your own
|
||||
|
||||
### Deploy with Docker
|
||||
|
||||
[](https://hub.docker.com/r/lissy93/dashy)
|
||||
**Container Info**: [
|
||||
|
||||
|
||||
|
||||
](https://hub.docker.com/r/lissy93/dashy)<br>
|
||||
**Status**: [
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
](https://hub.docker.com/r/lissy93/dashy)
|
||||
|
||||
Dashy has a built container image hosted on [Docker Hub](https://hub.docker.com/r/lissy93/dashy). You will need [Docker](https://docs.docker.com/get-docker/) installed on your system.
|
||||
|
||||
@@ -108,8 +119,8 @@ Some hosting providers required a bit of extra configuration, which was why I've
|
||||
|
||||
**Note** If you use a static hosting provider, then status checks, writing new config changes to disk from the UI, and triggering a rebuild through the UI will not be availible. This is because these features need endpoints provided by Dashy's local Node server. Everything else should work just the same though.
|
||||
|
||||
#### Netlify <img src="https://i.ibb.co/ZxtzrP3/netlify.png" width="24"/>
|
||||
[](https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy)
|
||||
#### Netlify
|
||||
[](https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy)
|
||||
|
||||
[Netlify](https://www.netlify.com/) offers Git-based serverless cloud hosting for web applications. Their services are free to use for personal use, and they support deployment from both public and private repos, as well as direct file upload. The free plan also allows you to use your own custom domain or sub-domain, and is easy to setup.
|
||||
|
||||
@@ -118,8 +129,8 @@ To deploy Dashy to Netlify, use the following link
|
||||
https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy
|
||||
```
|
||||
|
||||
#### Heroku <img src="https://i.ibb.co/d2P1WZ7/heroku.png" width="24"/>
|
||||
[](https://heroku.com/deploy?template=https://github.com/Lissy93/dashy)
|
||||
#### Heroku
|
||||
[](https://heroku.com/deploy?template=https://github.com/Lissy93/dashy)
|
||||
|
||||
[Heroku](https://www.heroku.com/) is a fully managed cloud platform as a service. You define app settings in a Procfile and app.json, which specifying how the app should be build and how the server should be started. Heroku is free to use for unlimited, non-commercial, single dyno apps, and supports custom domains. Heroku's single-dyno service is not as quite performant as some other providers, and the app will have a short wake-up time when not visited for a while
|
||||
|
||||
@@ -128,8 +139,8 @@ To deploy Dashy to Heroku, use the following link
|
||||
https://heroku.com/deploy?template=https://github.com/Lissy93/dashy
|
||||
```
|
||||
|
||||
#### Cloudflare Workers <img src="https://i.ibb.co/CvpFM1S/cloudflare.png" width="24"/>
|
||||
[](https://deploy.workers.cloudflare.com/?url=https://github.com/lissy93/dashy/tree/deploy_cloudflare)
|
||||
#### Cloudflare Workers
|
||||
[](https://deploy.workers.cloudflare.com/?url=https://github.com/lissy93/dashy/tree/deploy_cloudflare)
|
||||
|
||||
[Cloudflare Workers](https://workers.cloudflare.com/) is a simple yet powerful service for running cloud functions and hosting web content. It requires a Cloudflare account, but is completely free for smaller projects, and very reasonably priced ($0.15/million requests per month) for large applications. You can use your own domain, and applications are protected with Cloudflare's state of the art DDoS protection. For more info, see the docs on [Worker Sites](https://developers.cloudflare.com/workers/platform/sites)
|
||||
|
||||
@@ -138,8 +149,8 @@ To deploy Dashy to Cloudflare, use the following link
|
||||
https://deploy.workers.cloudflare.com/?url=https://github.com/lissy93/dashy/tree/deploy_cloudflare
|
||||
```
|
||||
|
||||
#### Vercel <img src="https://i.ibb.co/Ld2FZzb/vercel.png" width="24"/>
|
||||
[](https://vercel.com/new/project?template=https://github.com/lissy93/dashy)
|
||||
#### Vercel
|
||||
[](https://vercel.com/new/project?template=https://github.com/lissy93/dashy)
|
||||
|
||||
[Vercel](https://vercel.com/) is a performance-focused platform for hosting static frontend apps. It comes bundled with some useful tools for monitoring and anaylzing application performance and other metrics. Vercel is free for personal use, allows for custom domains and has very reasonable limits.
|
||||
|
||||
@@ -148,8 +159,8 @@ To deploy Dashy to Vercel, use the following link
|
||||
https://vercel.com/new/project?template=https://github.com/lissy93/dashy
|
||||
```
|
||||
|
||||
#### DigitalOcean <img src="https://i.ibb.co/V2MxtGC/digitalocean.png" width="24"/>
|
||||
[](https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean&refcode=3838338e7f79)
|
||||
#### DigitalOcean
|
||||
[](https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean&refcode=3838338e7f79)
|
||||
|
||||
[DigitalOcan](https://www.digitalocean.com/) is a cloud service providing affordable developer-friendly virtual machines from $5/month. But they also have an app platform, where you can run web apps, static sites, APIs and background workers. CDN-backed static sites are free for personal use.
|
||||
|
||||
@@ -157,8 +168,8 @@ https://vercel.com/new/project?template=https://github.com/lissy93/dashy
|
||||
https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean
|
||||
```
|
||||
|
||||
#### Google Cloud Platform <img src="https://i.ibb.co/J7MGymY/googlecloud.png" width="24"/>
|
||||
[](https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git)
|
||||
#### Google Cloud Platform
|
||||
[](https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git)
|
||||
|
||||
[Cloud Run](https://cloud.google.com/run/) is a service offered by [Google Cloud](https://cloud.google.com/). It's a fully managed serverless platform, for developing and deploying highly scalable containerized applications. Similar to AWS and Azure, GCP offers a wide range of cloud services, which are billed on a pay‐per‐use basis, but Cloud Run has a [free tier](https://cloud.google.com/run/pricing) offering 180,000 vCPU-seconds, 360,000 GiB-seconds, and 2 million requests per month.
|
||||
|
||||
@@ -167,8 +178,8 @@ To deploy Dashy to GCP, use the following link
|
||||
https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git
|
||||
```
|
||||
|
||||
#### Platform.sh <img src="https://i.ibb.co/GdfvH3Z/platformsh.png" width="24"/>
|
||||
[](https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy&utm_campaign=deploy_on_platform?utm_medium=button&utm_source=affiliate_links&utm_content=https://github.com/lissy93/dashy)
|
||||
#### Platform.sh
|
||||
[](https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy&utm_campaign=deploy_on_platform?utm_medium=button&utm_source=affiliate_links&utm_content=https://github.com/lissy93/dashy)
|
||||
|
||||
[Platform.sh](https://platform.sh) is an end-to-end solution for developing and deploying applications. It is geared towards enterprise users with large teams, and focuses on allowing applications to scale up and down. Unlike the above providers, Platform.sh is not free, although you can deploy a test app to it without needing a payment method
|
||||
|
||||
@@ -177,8 +188,8 @@ To deploy Dashy to Platform.sh, use the following link
|
||||
https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy
|
||||
```
|
||||
|
||||
#### Render <img src="https://i.ibb.co/xCHtzgh/render.png" width="24"/>
|
||||
[](https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render)
|
||||
#### Render
|
||||
[](https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render)
|
||||
|
||||
[Render](https://render.com) is cloud provider that provides easy deployments for static sites, Docker apps, web services, databases and background workers. Render is great for developing applications, and very easy to use. Static sites are free, and services start at $7/month. Currently there are only 2 server locations - Oregon, USA and Frankfurt, Germany. For more info, see the [Render Docs](https://render.com/docs)
|
||||
|
||||
@@ -187,8 +198,8 @@ To deploy Dashy to Render, use the following link
|
||||
https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render
|
||||
```
|
||||
|
||||
#### Scalingo <img src="https://i.ibb.co/Rvf5c4y/scalingo.png" width="24"/>
|
||||
[](https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master)
|
||||
#### Scalingo
|
||||
[](https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master)
|
||||
|
||||
[Scalingo](https://scalingo.com/) is a scalable container-based cloud platform as a service. It's focus is on compliance and uptime, and is geared towards enterprise users. Scalingo is also not free, although they do have a 3-day free trial that does not require a payment method
|
||||
|
||||
@@ -197,8 +208,8 @@ To deploy Dashy to Scalingo, use the following link
|
||||
https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master
|
||||
```
|
||||
|
||||
#### Play-with-Docker <img src="https://i.ibb.co/HVWVYF7/docker.png" width="24"/>
|
||||
[](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml)
|
||||
#### Play-with-Docker
|
||||
[](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml)
|
||||
|
||||
[Play with Docker](https://labs.play-with-docker.com/) is a community project by Marcos Liljedhal and Jonathan Leibiusky and sponsored by Docker, intended to provide a hands-on learning environment. Their labs let you quickly spin up a Docker container or stack, and test out the image in a temporary, sandboxed environment. There's no need to sign up, and it's completely free.
|
||||
|
||||
@@ -207,9 +218,10 @@ To run Dashy in PWD, use the following URL:
|
||||
https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml
|
||||
```
|
||||
|
||||
#### Surge.sh <img src="https://i.ibb.co/WgVC4mB/surge.png" width="24"/>
|
||||
[Surge.sh](http://surge.sh/) is quick and easy static web publishing platform for frontend-apps.
|
||||
#### Surge.sh
|
||||
|
||||
|
||||
[Surge.sh](http://surge.sh/) is quick and easy static web publishing platform for frontend-apps.
|
||||
Surge supports [password-protected projects](https://surge.sh/help/adding-password-protection-to-a-project). You can also [add a custom domain](https://surge.sh/help/adding-a-custom-domain) and then [force HTTPS by default](https://surge.sh/help/using-https-by-default) and optionally [set a custom SSL certificate](https://surge.sh/help/securing-your-custom-domain-with-ssl)
|
||||
|
||||
To deploy Dashy to Surge.sh, first clone and cd into Dashy, install dependencies, and then use the following commands
|
||||
|
||||
@@ -14,6 +14,8 @@ Both sections and items can have an icon, which is specified using the `icon` at
|
||||
<img width="500" src="https://i.ibb.co/GTVmZnc/dashy-example-icons.png" />
|
||||
</p>
|
||||
|
||||
Note that, if you are using icons from an external source (like font-awesome or material-design-icons), then the relevant font file will be loaded in automatically if and when needed, but combining icons from multiple services may have a negative impact on performance.
|
||||
|
||||
### Font Awesome
|
||||
You can use any [Font Awesome Icon](https://fontawesome.com/icons) simply by specifying it's identifier. This is in the format of `[category] [name]` and can be found on the page for any given icon on the Font Awesome site. For example: `fas fa-rocket`, `fab fa-monero` or `fas fa-unicorn`.
|
||||
|
||||
@@ -54,7 +56,7 @@ You can use almost any emoji as an icon for items or sections. You can specify t
|
||||
<img width="580" src="https://i.ibb.co/YLwgTf9/emoji-icons-1.png" />
|
||||
</p>
|
||||
|
||||
The following example shows the unicode options available, all three will render the 🚀 emoji.
|
||||
The following examples will all render the same rocket (🚀) emoji:
|
||||
|
||||
```yaml
|
||||
items:
|
||||
@@ -74,5 +76,25 @@ You may also want to store your icons locally, bundled within Dashy so that ther
|
||||
|
||||
You can also use sub-folders within the `item-icons` directory to keep things organised. You would then specify an icon with it's folder name slash image name. For example: `networking/monit.png`
|
||||
|
||||
### Material Design Icons
|
||||
Dashy also supports 5000+ [material-design-icons](https://github.com/Templarian/MaterialDesign). To use these, first find the name/ slug for your icon [here](https://dev.materialdesignicons.com/icons), and then prefix is with `mdi-`.
|
||||
|
||||
For example:
|
||||
```yaml
|
||||
sections:
|
||||
- name: Material Design Icons Example
|
||||
items:
|
||||
- title: Alien Icon
|
||||
icon: mdi-alien
|
||||
- title: Fire Icon
|
||||
icon: mdi-fire
|
||||
- title: Dino Icon
|
||||
icon: mdi-google-downasaur
|
||||
|
||||
```
|
||||
|
||||
### Simple Icons
|
||||
To use glyphs from [SimpleIcons.org](https://simpleicons.org/), first find the icon slug, and then prefix it with `si-`. The image will be loaded directly from the Simple Icons
|
||||
|
||||
### No Icon
|
||||
If you don't wish for a given item or section to have an icon, just leave out the `icon` attribute.
|
||||
|
||||
106
docs/quick-start.md
Normal file
106
docs/quick-start.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# Quick Start
|
||||
|
||||
Welcome to Dashy! So glad you're here 😊 In a couple of minutes, you'll have your new dashboard up and running 🚀
|
||||
|
||||
**TDLR;** Run `docker run -p 8080:80 lissy93/dashy`, then open `http://localhost:8080`
|
||||
|
||||
---
|
||||
|
||||
## 1. Prerequisites
|
||||
|
||||
The quickest and easiest method of running Dashy is using Docker (or another container engine). You can find installation instructions for your system in the [Docker Documentation](https://docs.docker.com/get-docker/).
|
||||
If you don't want to use Docker, then you can use one of Dashy's other supported installation methods instead, all of which are outlined in the [Deployment Docs](https://github.com/Lissy93/dashy/blob/master/docs/deployment.md).
|
||||
|
||||
---
|
||||
|
||||
## 2. Installation
|
||||
|
||||
To pull the latest image, and build and start the app run:
|
||||
```
|
||||
docker run -d \
|
||||
-p 8080:80 \
|
||||
--name my-dashboard \
|
||||
--restart=always \
|
||||
lissy93/dashy:latest
|
||||
```
|
||||
|
||||
For a full list of available options, then see [Dashy with Docker](https://github.com/Lissy93/dashy/blob/master/docs/deployment.md#deploy-with-docker) Docs. If you'd prefer to use Docker Compose, then see [Dashy with Docker Compose](https://github.com/Lissy93/dashy/blob/master/docs/deployment.md#using-docker-compose) Docs.
|
||||
|
||||
Your dashboard should now be up and running at `http://localhost:8080` (or your servers IP address/ domain, and the port that you chose). The first build will may take a few minutes
|
||||
|
||||
---
|
||||
|
||||
## 3. Configure
|
||||
|
||||
Now that you've got Dashy running, you are going to want to set it up with your own content.
|
||||
Config is written in [YAML Format](https://yaml.org/), and saved in [`/public/conf.yml`](https://github.com/Lissy93/dashy/blob/master/public/conf.yml).
|
||||
The format on the config file is pretty straight forward. There are three root attributes:
|
||||
- [`pageInfo`](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md#pageinfo) - Dashboard meta data, like title, description, nav bar links and footer text
|
||||
- [`appConfig`](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md#appconfig-optional) - Dashboard settings, like themes, authentication, language and customization
|
||||
- [`sections`](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md#section) - An array of sections, each including an array of items
|
||||
|
||||
|
||||
You can view a full list of all available config options in the [Configuring Docs](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md).
|
||||
|
||||
```yaml
|
||||
pageInfo:
|
||||
title: Home Lab
|
||||
sections: # An array of sections
|
||||
- name: Example Section
|
||||
icon: far fa-rocket
|
||||
items:
|
||||
- title: GitHub
|
||||
description: Dashy source code and docs
|
||||
icon: fab fa-github
|
||||
url: https://github.com/Lissy93/dashy
|
||||
- title: Issues
|
||||
description: View open issues, or raise a new one
|
||||
icon: fas fa-bug
|
||||
url: https://github.com/Lissy93/dashy/issues
|
||||
- name: Local Services
|
||||
items:
|
||||
- title: Firewall
|
||||
icon: favicon
|
||||
url: http://192.168.1.1/
|
||||
- title: Game Server
|
||||
icon: https://i.ibb.co/710B3Yc/space-invader-x256.png
|
||||
url: http://192.168.130.1/
|
||||
```
|
||||
|
||||
Notes:
|
||||
- You can use a Docker volume to pass a config file from your host system to the container
|
||||
- E.g. `-v ./host-system/my-local-conf.yml:/app/public/conf.yml`
|
||||
- It's also possible to edit your config directly through the UI, and changes will be saved in this file
|
||||
- Check your config against Dashy's schema, with `docker exec -it [container-id] yarn validate-config`
|
||||
- You might find it helpful to look at some examples, a collection of which can be [found here](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10)
|
||||
- After editing your config, the app will rebuild in the background, which may take a minute
|
||||
|
||||
---
|
||||
|
||||
## 4. Further Customisation
|
||||
|
||||
Once you've got Dashy setup, you'll want to ensure the container is properly healthy, secured, backed up and kept up-to-date. All this is covered in the [Management Docs](https://github.com/Lissy93/dashy/blob/master/docs/management.md).
|
||||
|
||||
|
||||
You might also want to check out the docs for specific features you'd like to use:
|
||||
- [Authentication](/docs/authentication.md) - Setting up authentication to protect your dashboard
|
||||
- [Backup & Restore](/docs/backup-restore.md) - Guide to Dashy's cloud sync feature
|
||||
- [Icons](/docs/icons.md) - Outline of all available icon types for sections and items
|
||||
- [Localisation](/docs/multi-language-support.md) - How to change language, or add your own
|
||||
- [Status Indicators](/docs/status-indicators.md) - Using Dashy to monitor uptime and status of your apps
|
||||
- [Theming](/docs/theming.md) - Complete guide to applying, writing and modifying themes and styles
|
||||
|
||||
---
|
||||
|
||||
## 5. Final Note
|
||||
|
||||
If you're enjoying Dashy, and have a few minutes to spare, please do take a moment to look at the [Contributing Page](https://github.com/Lissy93/dashy/blob/master/docs/contributing.md). There are a few things that we really need some help with, and whatever your skill set, there are ways you can help out. Any contributions, however small would be greatly appreciated.
|
||||
Thank you to [everyone](https://github.com/Lissy93/dashy/blob/master/docs/credits.md) who is already doing so, without developing and maintaining Dashy would not have been so possible.
|
||||
|
||||
You can also consider sharing your dashboard in the [Showcase](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md), to help provide inspiration for others.
|
||||
|
||||
For more info, check out the [Documentation](https://github.com/Lissy93/dashy/tree/master/docs#readme). If you've got any questions feel free to ask in the [Discussion](https://github.com/Lissy93/dashy/discussions), and if you think you've found a bug you can [raise an issue](https://github.com/Lissy93/dashy/issues/new/choose) to get it fixed.
|
||||
|
||||
Enjoy your dashboard :)
|
||||
|
||||
---
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
This document contains common problems and their solutions.
|
||||
|
||||
### Yarn Error
|
||||
## Yarn Error
|
||||
|
||||
For more info, see [Issue #1](https://github.com/Lissy93/dashy/issues/1)
|
||||
|
||||
@@ -18,3 +18,35 @@ 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)
|
||||
|
||||
---
|
||||
## `Refused to Connect` in Modal or Workspace View
|
||||
|
||||
This is not an issue with Dashy, but instead caused by the target app preventing direct access through embedded elements. It can be fixed by setting the [`X-Frame-Options`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options) HTTP header set to `ALLOW [path to Dashy]` or `SAMEORIGIN`, as defined in [RFC-7034](https://datatracker.ietf.org/doc/html/rfc7034). 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.
|
||||
```
|
||||
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
|
||||
header {
|
||||
X-Frame-Options SAMEORIGIN
|
||||
}
|
||||
```
|
||||
|
||||
### Apache
|
||||
|
||||
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
|
||||
|
||||
```
|
||||
Header set X-Frame-Options: "ALLOW-FROM http://[dashy-location]/"
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user