selfhosted
/
dashy
mirror of https://github.com/lissy93/dashy
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge branch 'Lissy93:master' into main

This commit is contained in:
Bogdan Radu 2024-01-21 13:11:17 +02:00 committed by GitHub
parent 898b04514b 8217dc35b9
commit 7d76400f7d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
465 changed files with 69910 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
.dockerignore Normal file
View File

@ -0,0 +1,9 @@
# Files specified here are not required for Docker
# so ignoring them helps to reduce the container size
# The Docker container MUST have the following files:
# package.json yarn.lock server.js vue.config.js src/ services/
node_modules
docs
.git
.github

24
.editorconfig Normal file
View File

@ -0,0 +1,24 @@
root = true
# Basics - All Files
[*]
end_of_line = lf
charset = utf-8
insert_final_newline = true
# JS, TS and Vue
[*.{js,jsx,ts,tsx,vue}]
indent_style = space
indent_size = 2
trim_trailing_whitespace = true
insert_final_newline = true
# YAML, for config file
[*.{yml,yaml}]
indent_size = 2
# Markdown for docs
[*.md]
trim_trailing_whitespace = false
# Licensed under MIT, (C) 2021 Alicia Sykes <https://aliciasykes.com>

40
.env Normal file
View File

@ -0,0 +1,40 @@
# Store environmental variables here. All variables are optional.
# Lines beginning in '#' are ignored.
# Can be either development, production or test
# NODE_ENV=production
# The port to expose the running application on
# PORT=4000
# If you've proved SSL certs, then can set HTTPS port
# SSL_PORT=4001
# The host that Dashy is running on, domain or IP
# HOST=localhost
# The default base path for serving up static assets
# BASE_URL=./
# Optionally, specify the path of SSL private + public keys
# SSL_PRIV_KEY_PATH=/etc/ssl/certs/dashy-priv.key
# SSL_PUB_KEY_PATH=/etc/ssl/certs/dashy-pub.pem
# If SSL enabled, choose whether or not to redirect http to https
# Defaults to true
# REDIRECT_HTTPS=true
# Usually the same as BASE_URL, but accessible in frontend
# VUE_APP_DOMAIN=https://dashy.to
# Should enable SRI for build script and link resources
# INTEGRITY=true
# Computed automatically on build. Indicates if running in container
# IS_DOCKER=true
# Again, set automatically using package.json during build time
# VUE_APP_VERSION=2.0.0
# Directory for conf.yml backups
# BACKUP_DIR=./public/

14
.github/.lycheeexclude vendored Normal file
View File

@ -0,0 +1,14 @@
# Ignore list, for automated broken link checking
https://fonts.gstatic.com/**
https://metager.org/meta/**
https://developers.cloudflare.com/**
http://localhost**
https://localhost**
http://192.168**
https://192.168**
file:///github/**
http://[dashy-location]**
https://[dashy-location]**
**.local/**

7
.github/.misspell-fixer.ignore vendored Normal file
View File

@ -0,0 +1,7 @@
/src/assets/locales/fr.json
^./src/assets/locales/de.json
^./src/assets/locales/es.json
^./src/assets/locales/fr.json
^./src/assets/locales/nl.json
^./src/assets/locales/sl.json
^./src/assets/locales/zh-CN.json

155
.github/AUTHORS.txt vendored Normal file
View File

@ -0,0 +1,155 @@
0n1cOn3 <0n1cOn3@gmx.ch> - 1 commits
5idereal <nelson22768384@gmail.com> - 1 commits
Alberto <3170731+albcp@users.noreply.github.com> - 1 commits
Alicia <liss-bot@d0h.co> - 1 commits
Artyom <32810520+AaronPorts@users.noreply.github.com> - 1 commits
BRAVO68WEB <jbandyopadhayaya@gmail.com> - 1 commits
Begin <support@begin.com> - 1 commits
Bhasher <github.it@bhasher.com> - 1 commits
Bjorn Lammers <walkxnl@gmail.com> - 1 commits
Bumsoo Kim <bskim45@gmail.com> - 1 commits
BySempron <barquin_rkz@hotmail.com> - 1 commits
David <skaarj1989@gmail.com> - 1 commits
Dawid Pietrykowski <d.pietrykowski16@gmail.com> - 1 commits
DeepSource Bot <bot@deepsource.io> - 1 commits
Desmond Kyeremeh <elDekyfin@gmail.com> - 1 commits
Devin Buhl <devin.kray@gmail.com> - 1 commits
Doug Lock <doug@douglock.co.uk> - 1 commits
Dylan-Bs <35694107+Dylan-Bs@users.noreply.github.com> - 1 commits
Eduardo Gomez <edugof@users.noreply.github.com> - 1 commits
Erwan Miran <emiran.ext@orange.com> - 1 commits
Ethan Hann <github.q2oay@slmail.me> - 1 commits
FedelloKirfed <fedellokirfed@proton.me> - 1 commits
FormatToday <616099456@qq.com> - 1 commits
Garrett Brown <gdbrown09@gmail.com> - 1 commits
Harald Töpfer <62364169+hubortje@users.noreply.github.com> - 1 commits
Ian Neal <wopr@wopr.tech> - 1 commits
Iaroslav Dronskii <iaroslav@dronskii.ru> - 1 commits
Ishan Jain <ishan@jain.se> - 1 commits
JJ Munguia <jj@jjmung.dev> - 1 commits
Jemy SCHNEPP <dev@leethium.fr> - 1 commits
Jeremy Chauvin <jeremychauvin10@gmail.com> - 1 commits
Julian <julian.thanner@gmx.de> - 1 commits
Kieran Eglin <kieran.eglin@gmail.com> - 1 commits
Kieren Connell <Kieren@kierenconnell.com> - 1 commits
Leonardo Colman Lopes <leonardo.dev@colman.com.br> - 1 commits
Luis Pabon <luis.pabon@auronconsulting.co.uk> - 1 commits
M Asenov <m.assenov@gmail.com> - 1 commits
Markus Krause <Krause.Markus@gmx.com> - 1 commits
Max Kulik <pearelectronics@live.com> - 1 commits
Maxime Moreillon <m.moreillon@gmail.com> - 1 commits
Mert Sefa AKGUN <git@msakg.com> - 1 commits
Michael <michaellavaire@gmail.com> - 1 commits
Nicholas Malcolm <bubylou@pm.me> - 1 commits
OKAMOTO Shigehiro <primary@goahi.live> - 1 commits
PlusaN <61884717+PlusaN@users.noreply.github.com> - 1 commits
Prince Carl Velasco <princevelasco16@gmail.com> - 1 commits
Rune Bjørnerås <rune.bjorneras@gmail.com> - 1 commits
Ryan Turner <ryan.e.t@gmail.com> - 1 commits
Rúben Silva <rubensilva945@gmail.com> - 1 commits
Sacha FROMENT <sacha@sacha.house> - 1 commits
Sergio <15928132+BySempron@users.noreply.github.com> - 1 commits
Shahzzad Ali <shazzgit@gmail.com> - 1 commits
Shawn Salat <31082405+ThinkSalat@users.noreply.github.com> - 1 commits
Shreya Roy <shreyaroy.2604@gmail.com> - 1 commits
Singebob <jeremy.chauvin@systeme-u.fr> - 1 commits
Smexhy <roman.bartik@icloud.com> - 1 commits
Stavros Kois <47820033+stavros-k@users.noreply.github.com> - 1 commits
Steffen Schmidt <service.github@nocer.net> - 1 commits
Steven Kast <steven.m.kast@gmail.com> - 1 commits
Tobias <96661824+CrazyWolf13@users.noreply.github.com> - 1 commits
Xert <xertdev@gmail.com> - 1 commits
allozavrr <razviyarrr@gmail.com> - 1 commits
baifengheixi <98794233+baifengheixi@users.noreply.github.com> - 1 commits
deepsource-io[bot] <deepsource-io[bot]@users.noreply.github.com> - 1 commits
dr460nf1r3 <njcrypted@protonmail.com> - 1 commits
flechaig <flechaig@users.noreply.github.com> - 1 commits
huangshaohuai <huangshaohuai@163.com> - 1 commits
icy-comet <50461557+icy-comet@users.noreply.github.com> - 1 commits
imlonghao <github@esd.cc> - 1 commits
jnach <33467747+jnach@users.noreply.github.com> - 1 commits
jrobles98 <jose98_21@hotmail.com> - 1 commits
kxenox <floriandel@msn.com> - 1 commits
laker j.v <la@laker.gay> - 1 commits
pablomalo <paul.gouin50@gmail.com> - 1 commits
poisonadder7 <github.com@loginz.uk> - 1 commits
rtm516 <ryantmilner@hotmail.co.uk> - 1 commits
soaibsafi <soaib.safi@gmail.com> - 1 commits
ssrangisetti <46807508+ssrangisetti@users.noreply.github.com> - 1 commits
ssrangisetti <ssrangisetti@protonmail.com> - 1 commits
sur1v <gsuriv@gmail.com> - 1 commits
tazboyz16 <tazboyz_16@yahoo.com> - 1 commits
zcq100 <zcq100@gmail.com> - 1 commits
Ángel Fernández Sánchez <angelfx19@gmail.com> - 1 commits
Alejandro Pinar Ruiz <37040888+pinarruiz@users.noreply.github.com> - 2 commits
Alessandro Del Prete <alessandro.delprete@gmail.com> - 2 commits
Alexander Mnich <56564725+a-mnich@users.noreply.github.com> - 2 commits
BOZG <sr@bozg.se> - 2 commits
Brendan O&#39;Leary <boleary@gitlab.com> - 2 commits
CHAIYEON CHO <stoutcho21@gmail.com> - 2 commits
Dan Gilbert <ddg@daentech.co.uk> - 2 commits
Denis Savosin <dsavosin@at-consulting.ru> - 2 commits
Ruben Silva <rubensilva945@gmail.com> - 2 commits
Thomas Dissert <dissertthomas@gmail.com> - 2 commits
cauterize <cauterize@programmer.net> - 2 commits
hockeymikey <hockeymikey@hockeymikey.com> - 2 commits
itsmejoeeey <9375730+itsmejoeeey@users.noreply.github.com> - 2 commits
k073l <21180271+k073l@users.noreply.github.com> - 2 commits
kt-alt <kiettrang@hotmail.com> - 2 commits
liss-bot <87835202+liss-bot@users.noreply.github.com> - 2 commits
mmihaly <mmihaly@gmail.com> - 2 commits
patrickheeney <patrickheeney@gmail.com> - 2 commits
rokiden <cheto@bk.ru> - 2 commits
root <root@dashy-dev.alayham.com> - 2 commits
rtm516 <rtm516@users.noreply.github.com> - 2 commits
zcq100 <m@zcq100.com> - 2 commits
ᗪєνιη ᗷυнʟ <onedr0p@users.noreply.github.com> - 2 commits
Alucarddelta <dreyer.brent@gmail.com> - 3 commits
Berk Sümbül <mail@berksmbl.com> - 3 commits
Tuzi555 <jakub.tuzar@gmail.com> - 3 commits
Walkx <71191962+walkxcode@users.noreply.github.com> - 3 commits
aterox <kenneth@kenneth.church> - 3 commits
bogyeong <boggyhint@gmail.com> - 3 commits
stanly0726 <37040069+stanly0726@users.noreply.github.com> - 3 commits
Andreas Violaris <48277853+aviolaris@users.noreply.github.com> - 4 commits
David Alasow <davidalasow@gmail.com> - 4 commits
DimitriDR <dimitridroeck@gmail.com> - 4 commits
Lissy93 <alicia@omg.lol> - 4 commits
Niklas Zabel <nzabel@Mini-von-Niklas.fritz.box> - 4 commits
Rémy GRANDIN <remy.gr@ndin.fr> - 4 commits
Todd E Johnson <todd@toddejohnson.net> - 4 commits
Totto16 <tobiausgais@gmail.com> - 4 commits
Walkx <walkxnl@gmail.com> - 4 commits
dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> - 4 commits
wozboz <philip@iuno.tech> - 4 commits
Alberto Caravaca <3170731+albcp@users.noreply.github.com> - 5 commits
Alicie <gh@d0h.co> - 5 commits
Benjamin Montgomery <bmontgom@montynet.org> - 5 commits
Chris Nielsen <nielsen.chris@gmail.com> - 5 commits
UrekD <urek.denis@gmail.com> - 5 commits
Erik Vroon <erik.vroon22@gmail.com> - 6 commits
Jammo2k5 <jammo2k5@hotmail.co.uk> - 6 commits
Leonardo Covarrubias <leos@leocov.com> - 6 commits
Magnus Sundström <kmvsundstrom@gmail.com> - 6 commits
kristian <kristianbrasel@gmail.com> - 6 commits
liss-bot <liss-bot@users.noreply.github.com> - 6 commits
Josua Blejeru <josua@blejeru.com> - 8 commits
Kashif Sohail <kashif.ezone@gmail.com> - 9 commits
Alejandro Pinar Ruiz <alejandropinarruiz@gmail.com> - 14 commits
Alicia Sykes <&#x3D;> - 16 commits
github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> - 16 commits
snyk-bot <snyk-bot@users.noreply.github.com> - 18 commits
Matthias Bilger <matthias@bilger.info> - 19 commits
aterox <church.kennetha@gmail.com> - 19 commits
EVOTk <45015615+EVOTk@users.noreply.github.com> - 24 commits
Marcell Fülöp <marekful@protonmail.com> - 27 commits
Alicia Sykes <alicia@futr.ai> - 28 commits
Lissy93 <gh@d0h.co> - 78 commits
snyk-bot <snyk-bot@snyk.io> - 83 commits
repo-visualizer <repo-visualizer@users.noreply.github.com> - 121 commits
Lissy93 <Lissy93@users.noreply.github.com> - 217 commits
Alicia Bot <87835202+liss-bot@users.noreply.github.com> - 220 commits
liss-bot <liss-bot@d0h.co> - 220 commits
Alicia Sykes <alicia@omg.lol> - 375 commits
Alicia Sykes <gh@d0h.co> - 440 commits
Alicia Sykes <sykes.alicia@gmail.com> - 1488 commits

673
.github/CHANGELOG.md vendored Normal file
View File

@ -0,0 +1,673 @@
# Changelog
## ✨ 2.1.1 Improvements [PR #775](https://github.com/Lissy93/dashy/pull/775)
- Stop status checks when item destroyed
- #767 by @marekful
- Add Elizabeth + non-underground lines to TFL widget
- #766 by @dougaldhub
- Ensure first SSL certificate check finished before second
- #760 by @marekful
- Huge improvment to the way widgets are defined
- #758 by @patrickheeney
- Update APOD widget to use https://apod.as93.net
- #745 by @k073l
- Small docs update
- #741 by @markusdd
- A set of awesome NextCloud widgets
- #740 by @marekful
- Option to show / hide detailed info for StatPing widget
- #714 by @marekful
- Korean translations
- #711 by @boggy-cs
- Small docs update
- #705 by @pablomalo
## ✨ 2.0.9 Adds Multi-Page Support [PR #685](https://github.com/Lissy93/dashy/pull/685)
- Adds Widgets for AdGuard
## ✨ 2.0.9 Adds Multi-Page Support [PR #663](https://github.com/Lissy93/dashy/pull/663)
- Fix KeyCloak API URL (#564)
- Fix guest has config access (#590)
- Fix collapsible content in multi-page support (#626)
- Fix layout and item size buttons ( #629)
- Refactor make request in RSS widget (#632)
- Fix material-design-icons header in schema (#640)
- Add option to hide seconds in clock widget (#644)
- Fix pageInfo not being read in router (#645)
- Fix startingView not honored (#646)
- Fix Status Check default (#651)
- Add option to hide image in SportsScores Widget (#654)
- Add Adventure-basic theme (#655)
- Write docs for sub-items (#657)
- Add Font-Awesome displaying as square to troubleshooting guide (#659)
- Show expand / collapse in context menu (#660)
- Only deploy new release when relevant files have changed
## ✨ 2.0.8 Adds Multi-Page Support [PR #617](https://github.com/Lissy93/dashy/pull/617)
- Adds support for multiple pages per-dashboard
- Adds new attribute at root of main config file: `pages`
- Updates router and nav-bar to automatically create paths for both local and remote configs
## ⚡️ 2.0.7 Improves handling of Sections and Items [PR #595](https://github.com/Lissy93/dashy/pull/595)
- Adds functionality for sub-items / item-groups
- Creates an item mixin, for reusing functionality
- Item width calculated based on parent section width
- Improved mobile support, long-press for right-click
- Adds 2 new themes (`lissy` and `charry-blossom`)
- Adds 2 new widgets (`mullvad-status`, and `blacklist-check`)
## 🐛 2.0.6 Fixes user requested issues [PR #557](https://github.com/Lissy93/dashy/pull/557)
- Allows middle click open new tab, Re: #492
- Implements Max redirects for status checks, Re: #494
- Adds Gitpod config for cloud-ready IDE, Re: #497
- Adss new screenshots to showcase, Re: #505
- Fixes excess space below footer, Re: #522
- Allows iframe content to be viewed full-screen, Re: #524
- Fixes Glances widgets with Authorization headers, Re: #546
- Adds target attribute to nav links, Re: #552
- Removes fixed max-width on wide-screens, Re: #554
- Adds missing type attribute to external CSS, Re: #560
- Updates path to Keycloak API, Re: #564
- Fixes link to @walkxhub homelab icons, Re #568
- Fixes local image path on sub-page, Re: #570
- Adds typecheck on edit item tags, Re: #575
- Fixes item size in config not honored, Re: #576
## ✨ 2.0.5 - Bug Fixes and a few New Features
#### Partially revert 2.0.4, fixing several issues caused by `conf.yml` not being loaded at startup.
This change requires a rebuild of the application when several options under `appConfig` are changed.
Fixes #544 #555
#### Several other changes since 2.0.4, including:
The `Add New Section` button on the UI editor now displays if no sections are present. #536
When using SSL, the server can now redirect from HTTP to HTTPS. This is enabled by default when using SSL. #538
Section context menus are now accessible on mobile, and will no longer clip off the screen. #541
Italian translations have been added. #556
## ✨ 2.0.4 - Dynamic Config Loading [PR #528](https://github.com/Lissy93/dashy/pull/528)
- `conf.yml` is now loaded dynamically and the app now only needs a browser refresh on config change, not a full rebuild!
## 🐛 2.0.3 - Bug Fixes [PR #488](https://github.com/Lissy93/dashy/pull/488)
- Press enter to submit login form (Re: #483)
- Allow disabling write to local storage and disk (Re: #485)
- Fix malformed YAML from export config (Re: #482)
- Allow global option for useProxy (Re: #486)
- Look into arrow key navigation error (Re: #463)
- Disallow displaying config (Re: #455)
- Round values in Glances Alerts widget (Re: #454)
- Create a CPU temp widget (Re: #452)
- Add to docs: Keycloak in Kubernetes (Re: #479)
- Add a widget for displaying images (Re: #487)
## ⬆️ 2.0.2 - Dependency Updates [PR #471](https://github.com/Lissy93/dashy/pull/471)
- Updates Alpine version for main Dockerfile
- Updates node_modules to latest stable versions
## 🐛 2.0.1 - Fixes Section Height [PR #462](https://github.com/Lissy93/dashy/pull/462)
- Adds `cutToHeight` to config schema (Re: #461)
- Removes the full-height CSS from colorful theme
- Improved config validation warnings in JSON editor
- Removes empty Keycloak block from appConfig editor
- Adds typechecking to search and clear search for Safari
## ⚡️ 2.0.0 - Small Fixes and Docker Multi-Arch Build [PR #451](https://github.com/Lissy93/dashy/pull/451)
- Fixes full-height sections for mobile and Safari (Re: #432, #442)
- Fixes empty section visible in search (Re: #447)
- Fixes numbers omited from tag names (Re: #430)
- Option for custom status code in status check (Re: #456, #448)
- Adds @stuu3k's dashboard to showcase (Re: #446)
- Switches recover and death count in Covid widget (Re: #148)
- Improved contrast in light material theme
- Adds new script to lint, test, build and publish a multi-architecture Docker image to various registries
## 💄 1.9.9 - Minor UI + Docs Updates [PR #431](https://github.com/Lissy93/dashy/pull/431)
- Improved theme support for widgets
- Better widget layout in Workspace and Minimal views
- Updates lots of the docs
## ✨ 1.9.8 - More Widgets and Widget Improvements [PR #425](https://github.com/Lissy93/dashy/pull/425)
- Fixes several minor widget issues raised by users
- Adds several new widgets, for monitoring system
- Better widget data requests and error handling
- Implements widget support into Workspace view
## 🐛 1.9.7 - Minor UI Editor Bug fixes [PR #416](https://github.com/Lissy93/dashy/pull/416)
- Fixes unable to edit item bug (#415)
- Fixes unable to add new app bug (#390)
- Fixes nav links visibility (#389)
## ⚡️ 1.9.6 - Adds Proxy Support for Widget Requests [PR #392](https://github.com/Lissy93/dashy/pull/392)
- Refactors widget mixin to include data requests, so that code can be shared between widgets
- Adds a Node endpoint for proxying requests server-side, used for APIs that are not CORS enabled
- Adds option to config file for user to force proxying of requests
- Writes a Netlify cloud function to support proxying when the app is hosted on Netlify
## 🐛 1.9.5 - Bug fixes and Minor Improvements [PR #388](https://github.com/Lissy93/dashy/pull/388)
- Adds icon.horse to supported favicon APIs
- Fixes tile move bug, Re: #366
- Fixes save items without title bug, Re: #377
## ✨ 1.9.4 - Widget Support [PR #382](https://github.com/Lissy93/dashy/pull/382)
- Adds support for dynamic content, through widgets
- Adds 30+ pre-built widgets for general info and self-hosted services
- Writes docs on widget usage
## ⚡️ 1.9.2 - Native SSL Support + Performance Improvements [PR #326](https://github.com/Lissy93/dashy/pull/326)
- Updates the server to use Express, removing serve-static, connect and body-parser
- Adds native support for passing in self-signed SSL certificates and updates docs
- Updates router to lazy-load additional pages (minimal, workspace, etc)
- Changes default favicon API to allesedv, since faviconkit is down, and adds basic fallback
- Updates GH action build scripts to fallback on context token when running on fork
## 💄 1.9.1 - Editor and Theming Fixes and Improvements [PR #319](https://github.com/Lissy93/dashy/pull/319)
- Bug fixes for interactive editor: #310, #311, #312
- Adds option to modify text font through the UI
- Adds two new themes: One Dark and Adventure
- Theming stylesheet refactor, better inheritance
## 🐳 1.9.0 - Alpha of Dashy-Lite Docker Container [PR #306](https://github.com/Lissy93/dashy/pull/306)
- Create an Alpine-based container, that serves the built app up with plain NGINX, instead of Node.
- This is much lighter, but doesn't currently support any of the server-side actions (like status-checks, and writing changes to disk)
## ✨ 1.8.9 - All New Interactive Config Editor [PR #298](https://github.com/Lissy93/dashy/pull/298)
- Builds a new UI-based config editor
- Support for sections, items, app config and page info
- Live preview, and undoing of local changes
- Export config or write changes to disk through UI
## ✨ 1.8.8 - Improved Item Targets [PR #292](https://github.com/Lissy93/dashy/pull/292)
- Adds support for `_top` and `_parent` anchor targets on items, Re: #289
- Adds `appConfig.defaultOpeningMethod` option to specify default target
- Adds new icons to show items opening method on hover
- Refactors target checking, updates item target docs and schema
## ⚡️ 1.8.7 - Bug Fixes and Improvements [PR #273](https://github.com/Lissy93/dashy/pull/273)
- Clean URLs without the hash, now using history-mode routing
- New initial main example conf.yml
- Minor UI style updates and fixes
- Support for single section view
- A new theme, soft-glow
- Container security in management docs, and other things
- Bug fixes, including missing Firefox favicon and fix custom icon paths with base_url
## ⚡️ 1.8.6 - Implementation of VueX [PR: #271](https://github.com/Lissy93/dashy/pull/271)
- New state management pattern, which should lead to a more organized code base long term, and will also make building out the new UI editor significantly easier to do in a clean and reliable way
## 💄 1.8.5 - Lots of Requested UI Improvements [PR #261](https://github.com/Lissy93/dashy/pull/261)
- Adds an option for landing URL in workspace, Re: #255
- Switches to a new API for generative icons, Re: #163
- Adds new tab functionality to Workspace, Re: #254
- Remove CSS validation in style editor, Re: #259
- Cap item description at 2 lines, Re: #250
- Adds native support for common homelab icons, using dashboard-icons
- Improves general responsiveness of home page sections positioning
- Updates, fixes and adds a bunch of actions for easier repo management
## ✨ 1.8.4 - Custom Error Pages [PR #257](https://github.com/Lissy93/dashy/pull/257)
- Creates a 404 Not Found page
- Routes any missing views to the 404 page
## ⚡️ 1.8.3 - Improved UX for Initial Load [PR #238](https://github.com/Lissy93/dashy/pull/238)
- Removes the old splash screen
- Adds placeholder in the HTML index, which will usually be visible on initial load
- Show progress bar on route switcher
## ✨ 1.8.2 - Serverless Functions for Netlify Instances [PR #235](https://github.com/Lissy93/dashy/pull/235)
- Previously when Dashy was deployed as a static site to Netlify, it was not possible to use several features, which required server-side code
- This PR adds serverless cloud functions to provide most of this functionality
## 🩹 1.8.1 - Additional Languages, Bug Fix, and more [PR #234](https://github.com/Lissy93/dashy/pull/234)
- Merges 5 additional languages
- Adds RickyCZ's dashboard to showcase
- Fixes #323, and improves status indicator tooltip
- Define constants for endpoints
- Updates management, translations and readme docs
## ⚡️ 1.7.7 - Improved Error Handling [PR #226](https://github.com/Lissy93/dashy/pull/226)
- Errors can be viewed via the UI (Config menu --> App Info)
- Service workers should be disabled by default
- Also renames actions to be easier to maintain
- Updates docs to include release schedule + merge strategy
## ✨ 1.7.6 - Adds Multi-Search Support with Bangs [PR #224](https://github.com/Lissy93/dashy/pull/224)
- Adds option for user to add custom search bangs, in order to specify search engine/ target app. Re: #206
## 🎨 1.7.5 - Improved Language Detection & UI [PR #223](https://github.com/Lissy93/dashy/pull/223)
- Makes the auto language detection algo smarter
- Improves responsiveness for the language selector form
## 🌐 1.7.4 - Adds Spanish Translations [PR #222](https://github.com/Lissy93/dashy/pull/222)
- Adds Spanish language file, contributed by @lu4t
## 👷 1.7.3 - CI with GH Actions [PR #212](https://github.com/Lissy93/dashy/pull/212)
- Adds a series of GH actions for repository maintenance and administration
- Auto-labels PR and issues, adds helpful info to PRs based on files changed
- Lints, tests, builds and deploys the app when PR submitted
- Checks app size, dependencies, security, accessibility etc when PR submitted
- Closes incomplete, stale or spammy issues and leaves a comment
## ✨ 1.7.2 - Item Sort Options [PR #203](https://github.com/Lissy93/dashy/pull/203)
- Adds option for user to specify `sortBy` to order items within a section
- Can sort by last clicked, most used, alphabetically and more
- And fixes UI of the item tooltip and, if specified, will show Provider in the tooltip
- Also improves error logging and console warning message
## 🐛 1.7.1 - Lots of Tiny Fixes and Improvements [PR #200](https://github.com/Lissy93/dashy/pull/201)
- Removes background in console art
- Updates auto environmental variables
- Icon image assets max height Force same Icon/Item Height #200
- Adds an action to close spammy issues
- Adds option to enable SRI integrity, plus refactos PWA into defaults
- Updates privacy and security docs
- Adds option for different favicon API for each app [FEATURE_REQUEST] Allow using different faviconApi for each items #196
- Fixes loading of local SVG icons #199
## 🍻 1.7.0 - Documentation Website [PR #190](https://github.com/Lissy93/dashy/pull/190)
- Builds a quick website to host the docs. No code changes, but prepares for V1.7 release
## ✨ 1.6.9 - Web Search Feature [PR #185](https://github.com/Lissy93/dashy/pull/185)
- Adds ability to search the web directly from Dashy by pressing enter on the search bar
- Adds configuration options, for setting default search engine, opening method and disabling
- Adds text under search bar, implements into minimal view also
## ⚡️ 1.6.8 - Improved Loading Experience [PR #183](https://github.com/Lissy93/dashy/pull/183)
- During app initialization, show the build progress and status message
- While requests are being made, show loader at top of screen
- Also adds some UI improvements to Workspace view
## ⚡️ 1.6.7 - Option for non-SSL status checks plus minor things [PR #182](https://github.com/Lissy93/dashy/pull/182)
- Adds an option for user to use status checks with non-HTTPS services, Re: #181
- Updates the .env template, plus the variables used in the server
- Uses the v-cloak to hide text before it's finished loading
- Fixed the parsing of the update-checker during build
## ⚡️ 1.6.6 - Improved Search & Shortcuts [PR #175](https://github.com/Lissy93/dashy/pull/175)
- Refactors the search algorithm to improve performance and code reusability
- Updates search to ignore case, special characters and minor-typos
- Adds the option for user to specify tags, which can be used for searching
## ✨ 1.6.5 - Adds support for Secure Authentication using Keycloak [PR #174](https://github.com/Lissy93/dashy/pull/174)
- Major restructure of auth config
- Implements keycloak support, adds docs and updates schema
## ✨ 1.6.4 - Adds functionality for Granular Auth Control [PR #171](https://github.com/Lissy93/dashy/pull/171)
- Enables sections to be visible for all users except for those specified
- Enables sections to be hidden from all users except for those specified
- Enables sections to be hidden from guests, but visible to all authenticated users
## ⚡️ 1.6.3 - Dependency and Build File Updates [PR #168](https://github.com/Lissy93/dashy/pull/168)
- Removes any dependencies which are not 100% essential
- Moves packages that are only used for building into devDependencies
- Updates dependencies to latest version
- Adds a .dockerignore, so that non-essential files are not included in the container
- Updates deployment config files for Netlify, Heroku and GH actions
- Made a brand new bug-report template, with input fields and validation!
## ✨ 1.6.2 - Support for Guest Access [PR #167](https://github.com/Lissy93/dashy/pull/167)
- Adds functionality for optional read-only guest access to dashboards with authentication
- Can be enabled by setting `appConfig.enableGuestAccess: true`
## 💄 1.6.1 - Adds new Theme [PR #166](https://github.com/Lissy93/dashy/issues/166)
- Adds Dashy theme, for use in the dev dashboard
## ✨ 1.5.9 - New Minimal/ Startpage View [PR #155](https://github.com/Lissy93/dashy/issues/155)
- Adds a new view, called minimal view, designed to be like a light-weight startpage
- Implemented all the required features (filtering, opening methods, icons, etc) into minimal view
- Adds `appConfig.startingView` into schema, for specifying the initial default view to be loaded
## ✨ 1.5.8 - Multi-Tasking Support in Workspace View [PR #146](https://github.com/Lissy93/dashy/pull/146)
- Adds option to keep launched apps open in the background, to reduce friction when switching between websites, Re: #144
- This can be enabled by setting `appConfig.enableMultiTasking: true`
- Note that having many apps opened simultaneously, will have an impact on performance
## ✨ 1.5.7 - Adds Support for Material Design Icons [PR #141](https://github.com/Lissy93/dashy/pull/141)
- Enables user to use any icon from [materialdesignicons.com](https://dev.materialdesignicons.com/icons), Re: #139
- Also adds support for [simpleicons.org](https://simpleicons.org/)
- Assets only loaded when needed
- Adds docs for using MDI icons
## ⚡️ 1.5.6 - Refactor + Couple of small things [PR #135](https://github.com/Lissy93/dashy/pull/135)
- The main Dockerfile now uses yarn.lock instead of package-lock.json
- Adds a check to verify password is not empty in cloud backup screen
- Improves responsiveness of config modals for mobile devices
- Enables the user to use their own self-hosted Sentry instance
- Removes the View Config tab of the Config menu, as not needed
- Updates and fixes some typos in the readme
## 🌐 1.5.5 - Adds Missing Translations + Small UI Issues [PR #129](https://github.com/Lissy93/dashy/pull/129)
- Adds missing translations to several UI elements, Re: #126
- Fixes login translations not being picked up on page load, Re: #127
- Fixes small text overflow glitch in config icon, Re: #123
- Several small UI improvements: height of config editor, scrollbar on theme dropdown, page height, white-on-white on material theme, etc
- Adds an action to auto-assign reviewer based on ./.github/CODEOWNERS file
## 🐳 1.5.4 - Docker ARM Support [PR #122](https://github.com/Lissy93/dashy/pull/122)
- Adds a Dockerfile for `arm64v8` and `arm32v7`, to support Raspberry Pi and other modern ARM-based devices
- Sets up automated workflow to publish ARM containers to DockerHub after every new release
- Adds documentation for running Dashy on RPi/ ARM-based devices, Re: #117
## 🩹 1.5.3 - UI Quick Fix [PR #121](https://github.com/Lissy93/dashy/pull/121)
- Downgrades and pins vue-material-tabs to 0.1.5, to prevent breaking changes. Fixes #118 p1
- Sets auto-width for theme selector, so text doesn't wrap for long theme names. Fixes #119
- Uses flex layout for config menu, so note doesn't overlap menu on small screens. Fixes #118 p2
## 🌐 1.5.2 - Adds Dutch Translations [PR #120](https://github.com/Lissy93/dashy/pull/120)
- Dutch language support, contributed by @evroon
## 🩹 1.5.1 - UI Quick Fix [PR #116](https://github.com/Lissy93/dashy/pull/116)
- Uses min-max width parent layout, to prevent longer languages (e.g. French) text overflow. Fixes #115
## 🔒 1.5.0 - Improve Robustness of Auth [PR #113](https://github.com/Lissy93/dashy/pull/113)
- Use both username + password for generating token, so that a change in either will log the user out
- Prevent privilege escalation by disallowing a user from modifying their user type through the UI
- Improve the isAuthenticated check, by taking account of empty users array
## ✨ 1.4.8 - Optional Crash Reports [PR #112](https://github.com/Lissy93/dashy/pull/112)
- Adds an optional, off by default method of getting crash reports
- This can be enabled in `appConfig.enableErrorReporting`, and will not be used at all unless explicitly activated by user
- This is needed for when a user raises a bug which is hard to fix
- Also improves robustness of config accumulator, don't throw error when config is missing
- Adds Privacy & Security docs
## ♻️ 1.4.7 - Refactor [PR #110](https://github.com/Lissy93/dashy/pull/110)
- Moves cloud sync dialog into the config menu, and removes icon on homepage
- Fixes typo in Default theme name, Re #106
- Spell checks readme
- Updates the contributor CI action, that generates list of contributors + sponsors
## 📝 1.4.6 - Documentation Updates [PR #108](https://github.com/Lissy93/dashy/pull/108)
- Breaks many of the longer files into several more digestible articles
- Writes repo pages including, Security, Code of Conduct, Legal, Updates license
- Makes an automatically generated Credits page
- Adds a contributing page, with several ways that users can help out
- Implements this changelog, as requested in #87
## 🌐 1.4.5 - Adds German Translations [PR #107](https://github.com/Lissy93/dashy/pull/107)
- German language support, contributed by @Niklashere
## ✨ 1.4.4 - Adds Support for Logo Image [PR #105](https://github.com/Lissy93/dashy/pull/105)
- Adds option in config file for user to specify path to an image
- If found, will display said image in the header
## ✨ 1.4.3 - Auto-Checks for Updates [PR #101](https://github.com/Lissy93/dashy/pull/101) and [PR #102](https://github.com/Lissy93/dashy/pull/102)
- Write a script to compare current version with git master version
- Periodically checks for updates, and displays message to user
- Enables user to disable update-checks in the config file
- Checks not using vulnerable version on project-build
## ✨ 1.4.2 - Adds Multi-Language Support [PR #99](https://github.com/Lissy93/dashy/pull/99)
- Implements vue-i18n, sets object globally
- Extracts all text to a single JSON file
- Auto-detects users language, and applies, if availible
- Builds a form to let user manually select their language
- Lets users language be saved and read from local storage, or config file
## ✨ 1.4.1 - Adds Support for Custom Key Bindings [PR #94](https://github.com/Lissy93/dashy/pull/94)
- Adds new attribute under item for saving numeric key binding
- Listens for keypress, and launches corresponding item, if found
## ✨ 1.4.0 - Builds a Custom Theme Configurator
- Adds property to save custom theme variables
- Builds UI form, with color pickers, a pallette and popup
- Integrates the saving colors, and applying saved colors functionality
## 🔨 1.3.9 - Enable Custom Styesheet in Docker [PR #92](https://github.com/Lissy93/dashy/pull/92)
- Enables the user to pass a custom stylesheet in with Docker
- Adds support for 1-Click deployment to Render.com
## 🌟 1.3.8 - Showcase [#91](https://github.com/Lissy93/dashy/pull/91)
- Adds @Shadowking001's screenshot to showcase
## 🌟 1.3.7 - Showcase [PR #84](https://github.com/Lissy93/dashy/pull/84)
- Adds @dtctek's screenshot to showcase
## ✨ 1.3.6 - Enables User to Hide Unwanted Components [PR #78](https://github.com/Lissy93/dashy/pull/78)
- Adds several additional options to the config, allowing the user to hide structural components that they don't need
- Including hideHeading, hideNav, hideSearch, hideSettings, hideFooter, hideSplashScreen
## ✨ 1.3.5 - Adds Support for Emoji Icons [PR #76](https://github.com/Lissy93/dashy/pull/76)
- Enables user to use emojis for item and section icons
- Adds a handler to convert Unicode, or Shortcode into an Emoji
## 🌟 1.3.4 - Showcase Addition [PR #75](https://github.com/Lissy93/dashy/pull/75)
- Adds @cerealconyogurt's screenshot to the showcase
## 💄 1.3.3 - UI Improvements [PR #73](https://github.com/Lissy93/dashy/pull/73)
- New style of Large item
- 2 new color themes
- Added CSS variables for search label and footer background
- Improves process for auto-checking if font-awesome is needed
- Silences non-critical warnings in production build
- Adds new optional font-face for cyber punk
- Shortens readme, and adds contribute links to showcase
## ⚡️ 1.3.0 - Custom Headers for Status Check [PR #72](https://github.com/Lissy93/dashy/pull/72)
- Enables user to pass custom headers to the status check endpoint
- Enables user to use a different URL for the status check request
## 🌟 1.2.9 - Creates a Showcase Page [PR #68](https://github.com/Lissy93/dashy/pull/68)
- Adds a page in the docs for users to share their screenshots of their dashboard
## ✨ 1.2.8 - Adds Remember-Me Functionality into the Login Form [PR #66](https://github.com/Lissy93/dashy/pull/66)
- Adds a dropdown menu in the login form with various time intervals available
- Adds appropriate expiry into session storage, in order to keep user logged in for their desired time interval
## ✨ 1.2.7 - Implements a Right-Click Context Menu [#62](https://github.com/Lissy93/dashy/pull/62)
- Built a context menu, showing all item opening methods, on right-click
- Made a clickOutside directive, in order to close menu when user clicks away
- Adds launching functionality, user can click to launch
## ⚡️ 1.2.6 - Make Font Assets Local [PR #60](https://github.com/Lissy93/dashy/pull/60)
- Downloaded font files to assets
- Removed all calls to font CDN, replaced with local calls
## 🐛 1.2.5 - Small Fixes, and Efficiency Improvements [PR #57](https://github.com/Lissy93/dashy/pull/57)
- Adds correct license
- Improves service workers, and adds serviceWorkerStatus local storage item
- Adds missing statusCheck and statusCheckInterval docs into Configuring.md
- Adds an About App page, containing info needed to raise a bug report
- Adds TDLR license into main readme
- Introduces app versioning
- Adds safeguards into ConfigAccumalaror, to prevent error being thrown
- Updates PR template
- Improved Webpack build experience, with progress bar and completion notification
- Adds new and improved icons for layout options
- Make the Page Title into a home page link
- Adds missing favicon, fixes #55
- Adds assets to PWA manifest.json
- Documents app commands in readme
- Enable passing website as URL param to the workspace
- Modified items, so that title text doesn't get shortened,
## ✨ 1.2.4 - Adds Support for Continuous Status Checking [#52](https://github.com/Lissy93/dashy/pull/52)
- Enables user to re-call the status check at a specified interval
- Processes interval in ms, and updates the traffic light when required
## 🐛 1.2.3 - Bug Fix [PR #49](https://github.com/Lissy93/dashy/pull/49)
- Removes duplicate Docker env var, fixes #48
## ✨ 1.2.2 - Better Favicon Support
- Enables user to force direct/ local favicon fetching
- Adds support for additional favicon API, returning high-res app icons
- Adds support for generative icons
## 🐛 1.2.1 - Bugfix [#44](https://github.com/Lissy93/dashy/pull/44)
- Fixes footer positioning on mobile, makes sticky, fixes #42
## ✨ 1.2.0 - Adds Writing Config to Disk from UI Functionality [PR #43](https://github.com/Lissy93/dashy/pull/43)
- Creates a new server endpoint for handling the backing up of a the file
- Adds backup existing file functionality
- Adds writing new file functionality
- Does error checking, testing and adds some security parameters
- Adds a radio button in the UI, so user chan choose save method
- Process config within the UI, convert to YAML, and write changes to disk
## 🐛 1.1.8 - Bugfix [#40](https://github.com/Lissy93/dashy/pull/40)
- Status check tooltip was not visible in Material themes, raised in issue #39
## ✨ 1.1.7 - Adds Workspace View [PR #38](https://github.com/Lissy93/dashy/pull/38)
- Adds a new route, for the workspace view
- Builds the sidebar, which displays the users apps
- Loads the app into the workspace's main iframe when clicked
- Adds some collapsing functionality, better styles, subtle animations and theme support
## ✨ 1.1.6 - Implements Status Indicators, and Monitoring Functionality [PR #34](https://github.com/Lissy93/dashy/pull/34)
- Wrote a Node endpoint for pinging the users desired services
- Added status checking functionality in frontend
- Build small traffic-light component to display status of users services
- Adds animations, and handles errors
- Writes docs, and tests code
## ✨ 1.1.5 - Adds Authentication / Login Functionality [PR #32](https://github.com/Lissy93/dashy/pull/32)
- Enables the user to protect their dashboard behind a login screen
- Creates a Authentication handler to manage the hashing of passwords, and generation of a token
- Build a quick login form, where user can input username and password
- Adds a log out button
## 💄 1.1.4 - Support for Custom HTML Footer [PR #30](https://github.com/Lissy93/dashy/pull/30)
- Enables user to insert structure for the footer defined as HTML
## 🚀 1.1.3 - Adds Support for 1-Click Cloud Deployments [PR #29](https://github.com/Lissy93/dashy/pull/29)
- Support for 1-Click Deploy to Netlify
- Support for 1-Click Deploy to Heroku
## 🔧 1.1.2 - Docker Efficiency Improvements [PR #26](https://github.com/Lissy93/dashy/pull/26)
- Writes a Node health check script, and implements into the Docker container
- Changes default port in docker-compose, as 8080 is commonly used by other apps
- Adds the 1-Click deploy with PWD into the readme
- Updates dependencies
- Adds a getting started guide to the docs
- Adds splash screen for first load
- Deleted unused assets
- Makes linter run as a pre-commit hook
- Fixes lint errors in server.js and validate-config.js
## 🐛 1.1.1 - Bug Fixes [PR #20](https://github.com/Lissy93/dashy/pull/20) + [PR #21](https://github.com/Lissy93/dashy/pull/21)
- Adds issue template
- Bug fixes
- Improves github PR and issue templates
- Shortens readme file
- Adds documentation in the docs folder
- Fixes Layout tab not showing in portrait #19
- Improves mobile performance for both the settings, config and backup pop-ups
- Fixes issue where theme not applied on load when the settings are hidden
- Adds minimum dimensions to modalsShortens readme file
- Adds documentation in the docs folder
- Adds minimum dimensions to modals
## 🚑️ 1.1.0 - Hotfix [#18](https://github.com/Lissy93/dashy/pull/18)
- Implementing the JSON validator had actually broken the entire JSON editor
- Fixed it by remove explicit use of Ajv, and using a derivative instead
## 📝 1.0.5 - Documentation [PR #16](https://github.com/Lissy93/dashy/pull/16)
- Previously there was very little documentation, this release fixed that
- Wrote specific docs for:
- Getting Started
- Configuring
- Backup & Restore
- Theming
- Developing
## ✨ 1.0.0 - Implements Config Validation [PR #13](https://github.com/Lissy93/dashy/pull/13)
- Write a JSON schema for the conf.yml file
- Wrote a validation script to compare users config against schema
- Adds a formatter to print helpful messages about what needs fixing
- Implements validation process into build script
- Implements validation process into UI config configurator's validation
## 🔧 0.9.5 - Brand New Docker Container [PR #12](https://github.com/Lissy93/dashy/pull/12)
- With help from several users, a new container based on Alpine is released
- A sample Docker Compose script is also written, and docs are updated
- A 1-Click button for deploying to Play-with-Docker is added to the Readme
## ✨ 0.9.0 - Adds Hide Settings Functionality [PR #11](https://github.com/Lissy93/dashy/pull/11)
- Enables user to hide settings from UI
- Users preference is saved in local storage
- User can hide other structural elements of the UI from the config
## 💄 0.8.5 - Adds new Built-In Themes [PR #9](https://github.com/Lissy93/dashy/pull/9)
- Adds Minimal-Dark and Minimal-Light theme
- Adds Material-Dark and Material-Light theme
- Adds additional theme docs
- Adds option for sections to have items too
## ✨ 0.8.0 - Implements Custom CSS Editor [PR: #8](https://github.com/Lissy93/dashy/pull/8)
- Adds a page in the config menu
- Adds syntax highlighting, CSS validation and sanitization
- Saves users CSS, and applies styles on page load
## ✨ 0.7.5 - Adds Cloud Backup and Restore Feature [PR #6](https://github.com/Lissy93/dashy/pull/6)
- Creates a form for entering backup ID and decryption password
- Puts form in modal, and adds button to launch form, with custom icon
- Implemented the cryptography stuff for end-to-end data encryption
- Wrote and tested the backend, and deployed as a serverless function on CF workers
- On the frontend, users input is encrypted, and passed to backend cloud function
- Response from the backend is handles appropriately, and message displayed to the user
- Implements the restoring from server functionality, with data integrity checks
## ✨ 0.7.0 - Support for Custom Nav Links [PR #4](https://github.com/Lissy93/dashy/pull/4)
- User can add custom nav bar links from the Config Settings menu
- Better UI styling to the config menu
- New icons inside buttons
## ✨ 0.6.5 - UI Config Editor [PR #3](https://github.com/Lissy93/dashy/pull/3)
Adds the ability for the user to edit their configuration directly from the UI
- Edit all section and item data using a rich JSON editor
- Download/ backup conf.yml directly from the UI
- Edit site meta data: title, description, footer, etc
- Reset all locally stored data to the initial state
- Also includes a new toast component, for subtle notifications
## ✨ 0.6.0 - Navbar, Footer and Background Image
- Adds option for a custom full-size background image
- Made footer customizable
- Fixes error being thrown when navbar links are empty
## ⚡️ 0.5.5 - Improved Theming
- Makes more specific color variables, which inherit base vars
- Makes it possible for users to write their own theme
- Fix some color edge cases
- Adds docs for theming
## ✨ 0.5.0 - Theme Support
- Converts all SCSS variables to CSS variables
- Implements theme switching functionality
- Adds a dropdown menu, enabling user to select theme
- Adds an initial theme option to `appConfig.theme`
- Saves selected theme to local storage
- Wrote a ton of color themes
## ✨ 0.4.5 - Keyboard Navigation
- Implements arrow key navigation
## ✨ 0.4.0 - Font Awesome Support
- Adds support for Font-Awesome icons
- Auto-loads font-awesome only when needed
- Adds support for SVG icons
## ✨ 0.3.5 - Opening Method
- Shows opening method on hover
- Opening method can be specified in config, as `item[n].target`
## 🔨 0.3.0 - Docker
- Writes a Dockerfile
## 🎨 0.2.5 - Code Quality, Docs and UI
- Huge code quality overhaul, now uses AirBnB style ESLint
- Adds in-code docs, removes unneeded code, moves reusable helpers into utils dir
- Adds a readme, records a demo gif and adds some basic deployment docs
- Removes dependencies which are not 100% necessary
## ✨ 0.2.0 - Collapsible Sections
- Implements collapsing functionality, for less used or very long sections
- Sections can read default state from `section[n].collapsed` within config
- After change, state of each section is stored in local storage
## ⚡️ 0.1.5 - Search and Navigation
- Improves instant search functionality
- Implements keyboard navigation for selecting items
- Launch selected item with enter, or Ctrl + Enter to open in new tab
## 🎉 0.1.0 - Init
Project started. Forked from [Lissy93/Dash](https://github.com/Lissy93/dash)

14
.github/CODEOWNERS vendored Normal file
View File

@ -0,0 +1,14 @@
# Code Owners helps give greater control to those who developed a feature
# PR's which modify files that you own will be marked as trusted
# After developing a feature, you can add yourself as it's owner
# Each line starts with file pattern, followed by one or more owners
# Codeowners Docs: https://github.blog/2017-07-06-introducing-code-owners/
# Repo Owners
* @lissy93
# Translations
src/assets/locales/fr.json @EVOTk
# Bot PR Permissions
docs/assets/CONTRIBUTORS.svg @liss-bot

128
.github/CODE_OF_CONDUCT.md vendored Normal file
View File

@ -0,0 +1,128 @@
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
* Focusing on what is best not just for us as individuals, but for the
overall community
Examples of unacceptable behavior include:
* The use of sexualized language or imagery, and sexual attention or
advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email
address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
alicia@omg.lol.
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series
of actions.
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
the community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.0, available at
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
Community Impact Guidelines were inspired by [Mozilla's code of conduct
enforcement ladder](https://github.com/mozilla/diversity).
[homepage]: https://www.contributor-covenant.org
For answers to common questions about this code of conduct, see the FAQ at
https://www.contributor-covenant.org/faq. Translations are available at
https://www.contributor-covenant.org/translations.

4
.github/FUNDING.yml vendored Normal file
View File

@ -0,0 +1,4 @@
# Support Dashy's Development!
github: lissy93
custom: ['https://notes.aliciasykes.com/tip']

79
.github/ISSUE_TEMPLATE/bug.yml vendored Normal file
View File

@ -0,0 +1,79 @@
name: Bug Report 🐛
description: Report something that's not working the way it's (probably) intended to
title: '[BUG] <title>'
labels: ['🐛 Bug']
assignees:
- lissy93
body:
- type: dropdown
id: environment
attributes:
label: Environment
description: Where are you running Dashy?
options:
- Self-Hosted (Docker)
- Self-Hosted (Bare Metal)
- Cloud Service (Static)
- Other (Specify below)
validations:
required: true
- type: input
id: system
attributes:
label: System
description: >-
For deployment issues, specify your [distro or OS](https://whatsmyos.com/) and/ or Docker version.
For client-side issues, include your [browser version](https://www.whatsmybrowser.org/)
placeholder: e.g. Firefox 101, Manjaro Linux 21.3.0, Docker 20.10.16
validations:
required: false
- type: input
id: version
attributes:
label: Version
description: What version of Dashy are you running?
placeholder: 4.2.0 ← should look like this (check config menu)
validations:
required: false
- type: textarea
id: repro
attributes:
label: Describe the problem
description: Please describe exactly what is not working, include the steps to reproduce, actual result and expected result
placeholder: When doing ABC then DEF, I expect to see XYZ, but I actually see ZYX
validations:
required: true
- type: textarea
id: logs
attributes:
label: Additional info
description: Logs? Screenshots? Yes, please.
placeholder: If the issue happens during build-time, include terminal logs. For run-time errors, include browser logs which you can view in the Dev Tools (F12), under the Console tab. Take care to blank out any personal info.
validations:
required: false
- type: checkboxes
id: idiot-check
attributes:
label: Please tick the boxes
description: Before submitting, please ensure that
options:
- label: You have explained the issue clearly, and included all relevant info
required: true
- label: You are using a [supported](https://github.com/Lissy93/dashy/blob/master/.github/SECURITY.md#supported-versions) version of Dashy
required: true
- label: You've checked that this [issue hasn't already been raised](https://github.com/Lissy93/dashy/issues?q=is%3Aissue)
required: true
- label: You've checked the [docs](https://github.com/Lissy93/dashy/tree/master/docs#readme) and [troubleshooting](https://github.com/Lissy93/dashy/blob/master/docs/troubleshooting.md#troubleshooting) guide ![important](https://img.shields.io/badge/Important!-F6094E)
required: true
- label: You agree to the [code of conduct](https://github.com/Lissy93/dashy/blob/master/.github/CODE_OF_CONDUCT.md#contributor-covenant-code-of-conduct)
required: true
- type: markdown
attributes:
value: |-
## Thanks 🙏
<img align="left" width="160" src="https://i.ibb.co/S5vCnhL/gh-thanks.gif" alt="🐙" />
Thank you for raising this ticket - in doing so you are helping to make the app better for everyone 💪<br>
You should expect a reply within the next 48 hours :)<br>
⭐️ Consider dropping the repo a star if you're enjoying Dashy!<br>
validations:
required: false

62
.github/ISSUE_TEMPLATE/feature-request.yml vendored Normal file
View File

@ -0,0 +1,62 @@
name: Feature Request ✨
description: Suggest an idea for future development of Dashy
title: '[FEATURE_REQUEST] <title>'
labels: ['🦄 Feature Request']
body:
# Field 1 - Is it bug-related
- type: textarea
id: issue
attributes:
label: Is your feature request related to a problem? If so, please describe.
description:
placeholder: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
validations:
required: false
# Field 2 - Describe feature
- type: textarea
id: solution
attributes:
label: Describe the solution you'd like
placeholder: An outline of how you would like this to be implemented, include as much details as possible
validations:
required: true
# Field 3 - Priority
- type: dropdown
id: priority
attributes:
label: Priority
description: How urgent is the development of this feature
options:
- Low (Nice-to-have)
- Medium (Would be very useful)
- High (The app does not function without it)
validations:
required: true
# Field 3 - Can the user implement
- type: dropdown
id: canImplement
attributes:
label: Is this something you would be keen to implement
description: Are you raising this ticket in order to get an issue number for your PR?
options:
- 'No'
- 'Maybe'
- 'Yes!'
validations:
required: false
# Final text
- type: markdown
attributes:
value: |-
## Thanks 🙏
Thank you for your feature suggestion, you should expect a reply within 48 hours :)
Please note that there is no guarantee that your idea will be implemented
If you haven't already done so, please Star the Dashy's repository on GitHub, to help other users discover it
validations:
required: false

64
.github/ISSUE_TEMPLATE/question.yml vendored Normal file
View File

@ -0,0 +1,64 @@
name: Question 🤷‍♂️
description: Got a question about Dashy, deployment, development or usage?
title: '[QUESTION] <title>'
labels: ['🤷‍♂️ Question']
body:
# Filed 1 - Intro Text
- type: markdown
attributes:
value: >
Thanks for using Dashy! Questions are welcome, but in the future will be moving over to
[Discussions](https://github.com/Lissy93/dashy/discussions) page.
Quick questions should be asked [here](https://github.com/Lissy93/dashy/discussions/148) instead.
validations:
required: false
# Field 2 - The actual question
- type: textarea
id: question
attributes:
label: Question
description: Outline your question in a clear and concise manner
validations:
required: true
# Field 3 - Category
- type: dropdown
id: category
attributes:
label: Category
description: What part of the application does this relate to?
options:
- Setup and Deployment
- Configuration
- App Usage
- Development
- Documentation
- Alternate Views
- Authentication
- Using Icons
- Widgets
- Actions
- Language Support
- Search & Shortcuts
- Status Checking
- Theming & Layout
validations:
required: true
# Field 4 - User has RTFM first, and agrees to code of conduct, etc
- type: checkboxes
id: idiot-check
attributes:
label: Please tick the boxes
description: Before submitting, please ensure that
options:
- label: You are using a [supported](https://github.com/Lissy93/dashy/blob/master/.github/SECURITY.md#supported-versions) version of Dashy (check the first two digits of the version number)
required: true
- label: You've checked that this [question hasn't already been raised](https://github.com/Lissy93/dashy/issues?q=is%3Aissue)
required: true
- label: You've checked the [docs](https://github.com/Lissy93/dashy/tree/master/docs#readme) and [troubleshooting](https://github.com/Lissy93/dashy/blob/master/docs/troubleshooting.md#troubleshooting) guide
required: true
- label: You agree to the [code of conduct](https://github.com/Lissy93/dashy/blob/master/.github/CODE_OF_CONDUCT.md#contributor-covenant-code-of-conduct)
required: true

10
.github/ISSUE_TEMPLATE/share-feedback.md vendored Normal file
View File

@ -0,0 +1,10 @@
---
name: "Share Feedback \U0001F308"
about: Share what you think about Dashy, and any ideas or suggestions you have
title: "[FEEDBACK]"
labels: "\U0001F308 Feedback"
assignees: ''
---

58
.github/ISSUE_TEMPLATE/showcase-addition.yml vendored Normal file
View File

@ -0,0 +1,58 @@
name: Add your Dashboard to the Showcase 🌟
description: Share a screenshot of your dashboard to the Readme showcase!
title: '[SHOWCASE] <title>'
labels: ['💯 Showcase']
body:
# 1 - Title
- type: input
id: title
attributes:
label: Title
description: Pick a title for your addition
placeholder: My Awesome Dashboard
validations:
required: false
# 2 - Link to Screenshot
- type: textarea
id: screenshot
attributes:
label: Screenshot
description: Either upload your screenshot here, or include a link to a png/jpg on a CDN / image hosting service
validations:
required: true
# 3 - Credit user
- type: dropdown
id: attribution
attributes:
label: Would you like your name/ username included?
description: This will be displayed above the screenshot to your dashboard in the showcase page
options:
- 'Yes'
- 'No'
validations:
required: true
# 4 - Social links
- type: input
id: links
attributes:
label: Link to your Website/ Profile/ Twitter (optional)
description: You can optionally have your name link to your profile or website. If you'd like this, include the URL to your site below
validations:
required: false
# 5 - Description
- type: textarea
id: description
attributes:
label: Description (Optional)
description: You can optionally also include a short description. If there's anything else you'd like to include, then put it here
validations:
required: false
# 6 - All done
- type: markdown
attributes:
value: |-
## That's It!
Thanks for sharing your dashboard :) You will receive an update to this ticket once it's added to the showcase
validations:
required: false

45
.github/LATEST_CHANGELOG.md vendored Normal file
View File

@ -0,0 +1,45 @@
## ✨ 2.1.1 Improvements [PR #775](https://github.com/Lissy93/dashy/pull/775)
#### Bug Fixes 🐛
- Update APOD widget to use https://apod.as93.net
- #745 by @k073l
- Fixes theme applying bug (#774)
#### Improvements ⚡️
- Stop status checks when item destroyed
- #767 by @marekful
- Ensure first SSL certificate check finished before second
- #760 by @marekful
- Huge improvement to the way widgets are defined
- #758 by @patrickheeney
#### Features ✨
- A set of awesome NextCloud widgets
- #740 by @marekful
- Add Elizabeth + non-underground lines to TFL widget
- #766 by @dougaldhub
- Option to show / hide detailed info for StatPing widget
- #714 by @marekful
- Korean translations
- #711 by @boggy-cs
- Adds option to force ignore widget errors
#### Docs 📕
- Small docs update
- #741 by @markusdd
- Small docs update
- #705 by @pablomalo
- Adds Dipanghosh's dash to showcase
---
Big thanks to the above developers, for their awesome work on this release!
V 2.1.2 is in the works, and includes an overhaul of how the config is loaded, so stay tuned for that!
And Happy Friday!

1117
.github/LEGAL.md vendored Normal file
View File

File diff suppressed because it is too large Load Diff

35
.github/SECURITY.md vendored Normal file
View File

@ -0,0 +1,35 @@
Security is taken very seriously
## Supported Versions
The current versions, and previous minor versions and / or the past 5 versions are supported. Releases either older than 5 versions, or from the last major version are no longer maintained or monitored, and hence the security of which cannot be guaranteed.
## Keeping your Instance of Dashy Secure
See [Docs: Management - Security](/docs/management.md#securing)
## Reporting a Security Issue
If you think you've found a critical issue, please send an email to `security@mail.alicia.omg.lol`, to encrypt it, you can use [`0688 F8D3 4587 D954 E9E5 1FB8 FEDB 68F5 5C02 83A7`](https://keybase.io/aliciasykes/pgp_keys.asc?fingerprint=0688f8d34587d954e9e51fb8fedb68f55c0283a7). You should receive a response within 48 hours.
All non-critical issues can be raised as a ticket.
Please include the following information:
- Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
- Full paths of source file(s) related to the manifestation of the issue
- The location of the affected source code (tag/branch/commit or direct URL)
- Any special configuration required to reproduce the issue
- Step-by-step instructions to reproduce the issue
- Proof-of-concept or exploit code (if possible)
- Impact of the issue, including how an attacker might exploit the issue
This info will help with finding and fixing the issue.
Please use only English.
## Issues That Should Not Be Raised
Please do not raise issues in this repo which relate to Vue or Vue CLI, we're already using the latest versions of these dependencies, so any issues here to be taken up with Vue. The same applies to other dev dependencies that are at the latest version.
## Known Issues
> **01/09/2021** - [Inefficient Regular Expression Complexity](https://www.huntr.dev/bounties/1e8f07fc-c384-4ff9-8498-0690de2e8c31/) in Axios (Re: [CWE-1333](https://cwe.mitre.org/data/definitions/1333.html)).
This ReDos vuln, was raised and fixed by @ready-research in Axios in August 2021. The issue was resolved in [`5b45711`](https://github.com/axios/axios/commit/5b457116e31db0e88fede6c428e969e87f290929), but Snyk sometime just takes a while to show updates. Dashy is using the latest version of Axios, and so is not affected by this issue.

17
.github/SUPPORT.md vendored Normal file
View File

@ -0,0 +1,17 @@
# Support
To report a potential vulnerability, follow the steps in **[Security](https://github.com/Lissy93/dashy/blob/master/.github/SECURITY.md#reporting-a-security-issue)**.
For setup and usage guides, see **[dashy.to/docs](https://dashy.to/)** or the **[GitHub](https://github.com/Lissy93/dashy)** repo.
To raise a bug, for something that's not working, **[Open a new Issue](https://github.com/Lissy93/dashy/issues/new/choose)**.
For help with getting Dashy up and running, please see the **[Discussions](https://github.com/Lissy93/dashy/discussions)**.
If you'd like to help support Dashy's future development, see **[Contributing](https://github.com/Lissy93/dashy/blob/master/docs/contributing.md)**.
To get in contact with the author, email me at **`alicia at omg dot lol`** **[[PGP]](https://keybase.io/aliciasykes/pgp_keys.asc?fingerprint=0688f8d34587d954e9e51fb8fedb68f55c0283a7)**.
-Thank you
> <sub>Prior to raising a ticket, please check the [docs](https://github.com/Lissy93/dashy/tree/master/docs#readme), [troubleshooting guide](https://github.com/Lissy93/dashy/blob/master/docs/troubleshooting.md) and [previous issues](https://github.com/Lissy93/dashy/issues?q=is%3Aissue).</sub><br><sup>If you're new here, consider also staring the repo before submitting your ticket.</sup>

3
.github/close-label.yml vendored Normal file
View File

@ -0,0 +1,3 @@
🐛 Bug: ✅ Fixed
🦄 Feature Request: ✅ Implemented
🤷‍♂️ Question: ✅ Answered

63
.github/issue-auto-comments.yml vendored Normal file
View File

@ -0,0 +1,63 @@
comment:
footer: |
---
> I am a bot, and this is an automated message 🤖
labels:
- name: ✖️ Invalid
labeled:
issue:
action: close
body: >
Hello @{{ issue.user.login }} your ticket has been marked as invalid.
Please ensure you follow the issue template, provide all requested info,
and be sure to check the docs + previous issues prior to raising tickets.
pr:
body: Thank you @{{ pull_request.user.login }} for suggesting this. Please follow the pull request templates.
action: close
- name: 👩‍💻 Good First Issue
labeled:
issue:
body: >
This issue has been marked as a good first issue for first-time contributors to implement!
This is a great way to support the project, while also improving your skills, you'll also be credited as a contributor once your PR is merged.
If you're new to web development, [here are a collection of resources](https://dashy.to/docs/developing#resources-for-beginners)
to help you get started. You can also find step-by-step tutorials for common tasks within Dashy, on the [Dev Guides](https://dashy.to/docs/development-guides) page.
If you need any support at all, feel free to reach out via [GitHub Discussions](https://github.com/Lissy93/dashy/discussions).
- name: ❌ wontfix
labeled:
issue:
action: close
body: >
This ticked has been marked as 'wontfix', which usually means it is out-of-scope, or not feasible at this time.
You can still fork the project and make the changes yourself, for support in doing so, please reference the [Developing Docs](https://dashy.to/docs/developing).
- name: ✅ Fixed
labeled:
issue:
body: >
Hello @{{ issue.user.login }}! It looks like all or part of this issue has now been implemented :)
If you're enjoying Dashy, please consider supporting the project- for ways to get involved, see [Contributing](https://dashy.to/docs/contributing) 💖
- name: ‼️ High Priority
labeled:
issue:
body: >
This ticket has been marked as high priority, and has been bumped to the top of the priority list.
You should expect an implementation to be pushed out within the next 7 days. Thank you for your patience.
- name: 💀 Spam
labeled:
issue:
action: close
locking: lock
lock_reason: spam
body: >
This issue has been identified as spam, and is now locked.
Users who repeatedly raise spam issues may be blocked or reported.
- name: ⛔ Don't Merge
labeled:
pr:
body: This PR has been temporarily blocked from merging.

24
.github/issue-report-config.json vendored Normal file
View File

@ -0,0 +1,24 @@
[
{
"section": "Feature Requests",
"labels": [
"🦄 Feature Request"
],
"threshold": 100
},
{
"section": "Bugs",
"labels": [
"🐛 Bug"
],
"threshold": 100
},
{
"section": "Questions & Feedback",
"labels": [
"🤷‍♂️ Question",
"🌈 Feedback"
],
"threshold": 100
}
]

135
.github/pr-auto-comments.yml vendored Normal file
View File

@ -0,0 +1,135 @@
comment:
on-update: edit
header: |
Hi {{ prAuthor }}! Thank you for contributing to Dashy! ✨
footer: |
---
> I'm a bot, and this is an automated comment 🤖
snippets:
- id: docs-changes
files:
- docs/**.md
body: |
When making changes to the documentation, be sure to double check that:
- Link and images URLs properly resolve
- Your spelling and grammar is correct
- Any markdown formatting is valid
- id: vue-config
files:
- vue.config.js
body: >
You're making changes to the main Vue app config. Please test the app thoroughly,
as any misconfigurations here may cause the app to stop functioning.
- id: server-entry
files:
- server.js
body: >
You're making changes to the main server entry point. Please test the app thoroughly,
as any misconfigurations here may cause the app to stop functioning.
- id: dependency-changes
files:
- yarn.lock
body: >
When updating dependencies, take a moment to verify that there are not security
issues associated with any added or modified packages. If adding a new dependency,
ensure that it is totally necessary, and check the packages size is not too large,
as this will increase overall bundle size.
- id: environmental-vars
files: [ '.env', '*.env', '.env*' ]
body: >
You're making changes to the main server entry point. Please test the app thoroughly,
as any misconfigurations here may cause the app to stop functioning.
- id: license
files: [ 'LICENSE', '**/**/LICENSE*' ]
body: >
Dashy is licensed under MIT. Your modifying the license file, which shouldn't usually
need to be changed. Please ensure that you intended to make this update before continuing.
- id: cname-file
files:
- CNAME
body: >
Are you sure you want to modify the CNAME file? This may stop the documentation
website hosted on GitHub pages from working.
- id: git-ignore
files:
- .gitignore
body: >
When modifying the .gitignore, please do not remove any of the existing paths,
as this may cause files and directories to be unintentionally committed to git
- id: netlify-file
files:
- netlify.toml
body: >
Please ensure you've tested the app on Netlify, so that the 1-Click deployment
does not break, before merging these changes
- id: heroku-ignore
files:
- Procfile
body: >
Please ensure you've tested the app on Heroku, so that the 1-Click deployment
does not break, before merging these changes
- id: ignored-dist
files:
- dist/**/*
body: >
Please do not commit the built application to git. The contents of the dist
directory will be generated after the app is compiled
- id: ignored-dependencies
files:
- node_modules/**/*
body: >
Please do not commit dependencies to git. Node modules will be pulled down
when yarn is run, prior to building the app
- id: user-themes
files:
- src/styles/user-defined-themes.scss
body: >
Please do not commit changes to this file, as it is intended to be overridden with Docker.
You can instead add your styles to the color-themes file, or for element-specific styles
put it within the appropriate component. Thank you
- id: code-owners
files:
- .github/CODEOWNERS
body: >
Are you adding yourself as a code owner? Please specify the file path as specific
as possible, and only assign yourself to files that you created and wish to help
maintain (such as a language file, specific feature or widget).
If the above is not met, your PR will be declined or modified.
- id: config-schema
files:
- src/utils/ConfigSchema.json
body: >
Don't forget to verify they the config validator script responds correctly to
your new attribute.
- id: showcase
files:
- docs/showcase.md
body: >
Thank you for adding your dashboard to the showcase! 🌟
- id: translations
files:
- src/assets/locales/**.json
body: >
Thank you for contributing to Dashy's translations 💖
- id: themes
files:
- src/styles/color-themes.scss
body: >
Thank you for contributing to Dashy's themes 🎨

145
.github/pr-badge.yml vendored Normal file
View File

@ -0,0 +1,145 @@
# Config file for pull-request-badge. See: https://pullrequestbadge.com/ by @stefanbuck
# Dynamically inserts status badges into PR description, based on certain conditions
# Show submitting user's username and profile link
- label: 💕 Submitted by
message: $payload.pull_request.user.login
color: '#f73ae6'
when: $payload.pull_request.author_association !== 'OWNER'
url: 'https://github.com/$payload.pull_request.user.login'
# Show a badge indicating the PR category, based on tag
- label: Type
message: ✨ Feature
color: '#39b0fd'
when: $labels.includes('✨ New Feature')
- label: Type
message: 🐛 Fix
color: '#39b0fd'
when: $labels.includes('🦋 Bug Fix')
- label: Type
message: 📕 Docs
color: '#39b0fd'
when: $labels.includes('📕 Docs')
- label: Type
message: 🛠️ Build Changes
color: '#39b0fd'
when: $labels.includes('🛠️ Build Changes')
- label: Type
message: 🛠️ Build Changes
color: '#39b0fd'
when: $labels.includes('🛠️ Build Changes')
- label: Type
message: 🚚 Refactor
color: '#39b0fd'
when: $labels.includes('🚚 Refactor')
- label: Type
message: 💄 Stylistic Changes
color: '#39b0fd'
when: $labels.includes('💄 Stylistic Changes')
- label: Type
message: 🌟 Showcase Addition
color: '#39b0fd'
when: $labels.includes('💯 Showcase')
- label: Type
message: 🏗️ Architecture
color: '#39b0fd'
when: $labels.includes('🏗️ Architectural Changes')
- label: Type
message: 🤖 Auto Submission
color: '#39b0fd'
when: $labels.includes('🤖 Auto')
- label: Type
message: 🌐 Language Update
color: '#39b0fd'
when: $labels.includes('🌐 Language')
# Add size label based on very large or tiny PRs
- label: PR Size
message: Extra Large
color: '#f9833e'
when: '$additions > 1000'
- label: PR Size
message: Large
color: '#f4b546'
when: '$additions > 500 && $additions < 1000'
- label: PR Size
message: Medium
color: '#f3ff59'
when: '$additions > 10 && $additions < 500'
- label: PR Size
message: Quick
color: '#3eef8b'
when: '$additions < 10'
# Show badge indicating PR status
- label: Status
message: ✏️ Draft
when: $isDraft
color: '#ffa933'
- label: Status
message: 🧱 Work in Progress
when: $payload.pull_request.title.includes('WIP')
color: '#29e3f4'
- label: Status
message: ✅ Ready
color: '#3ef963'
when: $labels.includes('🔀 Ready for Merge')
# Show PR number, to destination and from destination
- label: '#$prNumber'
message: '$payload.pull_request.user.login /$payload.pull_request.head.ref → $payload.repository.full_name'
color: '#ab5afc'
url: 'https://github.com/$slug/tree/$branchName'
# Show total code added minus deleted
- label: New Code
message: 'Commits: $payload.pull_request.commits | Files Changed: $payload.pull_request.changed_files | Additions: $payload.pull_request.additions-$payload.pull_request.deletions'
color: '#dddd00'
# Checks if the required sections are missing
- label: ⚠️Missing
message: Category
color: '#f25265'
when: $payload.pull_request.body.includes('Category') === false
- label: ⚠️Missing
message: Overview
color: '#f25265'
when: $payload.pull_request.body.includes('Overview') === false
- label: ⚠️Missing
message: Quality Checklist
color: '#f25265'
when: $payload.pull_request.body.includes('Code Quality Checklist') === false
- label: ⚠️Description
message: Incomplete
color: '#f25265'
when: $payload.pull_request.body.length < 25
- label: ⚠️Missing
message: Label
color: '#f25265'
when: $labels.length == 0
# Show note when task list has unfinished items
- label: ⚠️Notice
message: Unchecked Tasks
when: $payload.pull_request.body.includes('- [ ] ')
color: '#f25265'
# Show warning, when certain tags are applied
- label: Warning
message: ⛔ Do Not Merge
color: '#f25265'
when: $labels.includes("⛔ Don't Merge")
- label: Warning
message: 🚫 Merge Conflicts
color: '#f25265'
when: $labels.includes('🚫 Merge Conflicts')
- label: Warning
message: 🕸️ Inactive
color: '#f25265'
when: $labels.includes('🕸️ Inactive')
- label: Warning
message: 💀 Spam
color: '#f25265'
when: $labels.includes('💀 Spam')

11
.github/pr-branch-labeler.yml vendored Normal file
View File

@ -0,0 +1,11 @@
# PR labels and the branch patterns they should be auto-assigned to
✨ New Feature: ['FEATURE/*', 'FEAT/*']
🚚 Refactor: ['IMPROVMENTS/*', 'REFACTOR/*']
🦋 Bug Fix: ['FIX/*', 'HOT-FIX/*', 'BUG-FIX/*']
💯 Showcase: ['SHOWCASE/*', 'SHOWCASE_SUBMISSION/*']
💄 Stylistic Changes: ['STYLES/*', 'THEME/*', 'UI/*']
🏗️ Architectural Changes: ['ARCH/*', 'ARCHITECTURE/*']
🛠️ Build Changes: ['DOCKER/*', 'BUILD/*', 'CI/*', 'ACTIONS/*']
🌐 Language: ['LANG/*', 'INTERNATIONALIZATION/*', 'I18N/*', 'TEXT-UPDATE/*']
🤖 Auto: ['AUTO/*', 'BOT/*', 'snyk-upgrade-*', 'snyk-fix-*']
⛔ Don't Merge: ['WEBSITE/*', 'EXPERIMENT/*', 'DEPLOY/*', 'deploy_*', 'gh-pages', 'dev-demo']

24
.github/pull_request_template.md vendored Normal file
View File

@ -0,0 +1,24 @@
*Thank you for contributing to Dashy! So that your PR can be handled effectively, please populate the following fields (delete sections that are not applicable)*
**Category**:
> One of: Bugfix / Feature / Code style update / Refactoring Only / Build related changes / Documentation / Other (please specify)
**Overview**
> Briefly outline your new changes...
**Issue Number** _(if applicable)_ #00
**New Vars** _(if applicable)_
> If you've added any new build scripts, environmental variables, config file options, dependency or devDependency, please outline here
**Screenshot** _(if applicable)_
> If you've introduced any significant UI changes, please include a screenshot
**Code Quality Checklist** _(Please complete)_
- [ ] All changes are backwards compatible
- [ ] All lint checks and tests are passing
- [ ] There are no (new) build warnings or errors
- [ ] _(If a new config option is added)_ Attribute is outlined in the schema and documented
- [ ] _(If a new dependency is added)_ Package is essential, and has been checked out for security or performance
- [ ] Bumps version, if new feature added

27
.github/workflows/add-comment-from-tag.yml vendored Normal file
View File

@ -0,0 +1,27 @@
# Based on a label applied to an issue, the bot will add a comment with some additional info
name: 🎯 Auto-Reply to Labeled Tickets
on:
issues:
types:
- labeled
- unlabeled
pull_request_target:
types:
- labeled
- unlabeled
permissions:
contents: read
issues: write
pull-requests: write
jobs:
comment:
runs-on: ubuntu-20.04
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Label Commenter
uses: peaceiris/actions-label-commenter@v1
with:
config_file: .github/issue-auto-comments.yml
github_token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}

13
.github/workflows/apply-done-label.yml vendored Normal file
View File

@ -0,0 +1,13 @@
# When a PR is merged, any associated issues will have a Done label applied
# The label will depend on the issue type, see: ./github/close-label.yml
name: 💡 Apply Done Label
on:
pull_request:
types: [opened, merged, closed]
jobs:
triage:
runs-on: ubuntu-latest
steps:
- uses: logerfo/close-label@0.0.4
with:
repo-token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}

15
.github/workflows/assign-reviewer.yml vendored Normal file
View File

@ -0,0 +1,15 @@
# Automatically assigns the author as a reviewer to opened PRs and issues
name: 💡 Auto-Assign Author to PR
on:
pull_request:
types: [opened]
issues:
types: [opened]
jobs:
assign-author:
runs-on: ubuntu-latest
steps:
- name: Assign author
uses: technote-space/assign-author@v1
with:
GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}

23
.github/workflows/auto-rebase-pr.yml vendored Normal file
View File

@ -0,0 +1,23 @@
# When a '/rebase' comment is added to a PR, it will be rebased from the main branch
name: 🏗️ Automatic PR Rebase
on:
issue_comment:
types: [created]
jobs:
rebase:
name: Rebase
if: >
github.event.issue.pull_request != ''
&& contains(github.event.comment.body, '/rebase')
&& github.event.comment.author_association == 'MEMBER'
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
with:
token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
fetch-depth: 0
- name: Rebase
uses: cirrus-actions/rebase@1.4
env:
GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}

40
.github/workflows/auto-tag-pr.yml vendored Normal file
View File

@ -0,0 +1,40 @@
# Creates a new tag, whenever the app version (in package.json) is updated in master
# And marks any relevant issues as fixed
name: 🏗️ Release Tag new Versions
on:
push:
branches:
- master
jobs:
tag-pre-release:
runs-on: ubuntu-latest
outputs:
tag: ${{ steps.autotag.outputs.tagname }}
steps:
- uses: actions/checkout@v2
- uses: butlerlogic/action-autotag@stable
id: autotag
with:
GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
strategy: package
commit_message_template: "🔖 {{number}} {{message}} (by {{author}})\nSHA: {{sha}}\n."
github-release:
runs-on: ubuntu-latest
needs: tag-pre-release
if: ${{ needs.tag-pre-release.outputs.tag }}
steps:
- uses: actions/checkout@v2
- uses: ncipollo/release-action@v1
with:
token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
tag: ${{ needs.tag-pre-release.outputs.tag }}
bodyFile: ".github/LATEST_CHANGELOG.md"
mark-issue-fixed:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Label Fixed Issues
uses: gh-bot/fix-labeler@master
with:
token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
label: '✅ Fixed'

14
.github/workflows/broadcast-message.yml vendored Normal file
View File

@ -0,0 +1,14 @@
# Updates multiple issues with a certain tag, with a comment containing a given message
name: 🎯 Broadcast Message across Issues
on:
workflow_dispatch:
inputs:
message: { required: false }
labels: { required: false }
jobs:
broadcast:
runs-on: ubuntu-latest
steps:
- uses: jenschelkopf/broadcast-action@master
with:
token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}

25
.github/workflows/build-app.yml vendored Normal file
View File

@ -0,0 +1,25 @@
# This action builds and deploys the master branch
name: 🏗️ Build App to Branch
on:
push:
branches: [ master ]
pull_request:
branches: [ master ]
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout 🛎️
uses: actions/checkout@v2.3.1
- name: Install and Build 🔧
run: |
npm install
npm run build
- name: Deploy 🚀
uses: JamesIves/github-pages-deploy-action@4.1.4
if: ${{ github.repository_owner == 'lissy93' }}
with:
branch: dev-demo
folder: dist

13
.github/workflows/cache-artifacts.yml vendored Normal file
View File

@ -0,0 +1,13 @@
# Caches artifacts, including NPM dependencies, to speed up build times
name: 🏗️ Caching Artifacts
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/cache@v2
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-

22
.github/workflows/check-duplicate-issues.yml vendored Normal file
View File

@ -0,0 +1,22 @@
# Attempts to auto-detect weather an issue is a duplicate, and adds a comment
name: 🎯 Issue Duplicate Check
on:
issues:
types: [opened, edited]
jobs:
check-duplicate:
runs-on: ubuntu-latest
steps:
- uses: wow-actions/potential-duplicates@v1
with:
GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
filter: ''
exclude: '[BUG] [QUESTION] [FEEDBACK] [SHOWCASE]'
label: '🕸️ Potential Duplicate'
state: all
threshold: 0.75
reactions: 'eyes'
comment: >
Potential duplicates: {{#issues}}
- [#{{ number }}] {{ title }} ({{ accuracy }}%)
{{/issues}}

16
.github/workflows/check-merge-conflicts.yml vendored Normal file
View File

@ -0,0 +1,16 @@
# Detect and label pull requests that have merge conflicts
name: 🏗️ Check Merge Conflicts
on:
push:
branches:
- master
jobs:
check-conflicts:
runs-on: ubuntu-latest
steps:
- uses: mschilde/auto-label-merge-conflicts@master
with:
CONFLICT_LABEL_NAME: "🚫 Merge Conflicts"
GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
MAX_RETRIES: 5
WAIT_MS: 5000

21
.github/workflows/close-incomplete-issues.yml vendored Normal file
View File

@ -0,0 +1,21 @@
# Close any issue that does not match any of the issue templates
name: 🎯 Close Incomplete Issues
on:
issues:
types: [opened, edited]
jobs:
auto_close_issues:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v1
- name: Automatically close issues that don't follow the issue template
uses: lucasbento/auto-close-issues@v1.0.2
with:
github-token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
closed-issues-label: '🙁 Auto-Closed'
issue-close-message: |
Hello @${issue.user.login} 👋
Unfortunately your issue does not follow the format outlined in the template, and has therefore been auto-closed.
To ensure that all relevant info is included, please either update or recreate your issue, and complete the sub-headings provided.
Thank you :)

79
.github/workflows/close-stale-issues.yml vendored Normal file
View File

@ -0,0 +1,79 @@
# Closes any issues that no longer have user interaction
name: 🎯 Close Stale Issues
on:
workflow_dispatch:
schedule:
- cron: '0 1 * * *' # Run at 01:00 each day
jobs:
stale:
runs-on: ubuntu-latest
steps:
# Comment on, then close issues that haven't been updated for ages
- name: Close Stale Issues
uses: actions/stale@v4
with:
repo-token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
days-before-stale: 360
days-before-close: 5
operations-per-run: 30
remove-stale-when-updated: true
enable-statistics: true
stale-issue-message: >
This issue has gone 3 months without an update. To keep the ticket open, please indicate that it is still relevant in a comment below.
Otherwise it will be closed in 5 working days.
stale-pr-message: >
This PR is stale because it has been open 6 weeks with no activity. Either remove the stale label or comment below with a short update,
otherwise this PR will be closed in 5 days.
close-issue-message: >
This issue was automatically closed because it has been stalled for over 1 year with no activity.
close-pr-message: >
This pull request was automatically closed because it has been stalled for over 1 year with no activity.
stale-issue-label: '⚰️ Stale'
close-issue-label: '🕸️ Inactive'
stale-pr-label: '⚰️ Stale'
close-pr-label: '🕸️ Inactive'
exempt-issue-labels: '📌 Keep Open'
exempt-pr-labels: '📌 Keep Open'
labels-to-add-when-unstale: '📌 Keep Open'
# Comment on, then close issues that required a response from the user, but didn't get one
- name: Close Issues without Response
uses: actions/stale@v4
with:
repo-token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
days-before-stale: 5
days-before-close: 3
operations-per-run: 30
remove-stale-when-updated: true
stale-issue-message: >
Hello! Looks like additional info is required for this issue to be addressed.
Don't forget to provide this within the next few days to keep your ticket open.
close-issue-message: 'Issue closed due to no response from user.'
only-labels: '🚏 Awaiting User Response'
labels-to-remove-when-unstale: '🚏 Awaiting User Response, 🛑 No Response'
stale-issue-label: '🛑 No Response'
close-issue-label: '🕸️ Inactive'
exempt-issue-labels: '📌 Keep Open'
exempt-pr-labels: '📌 Keep Open'
# Comment on issues that I should have replied to
- name: Notify Repo Owner to Respond
uses: actions/stale@v4
with:
repo-token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
days-before-stale: 7
days-before-close: 365
operations-per-run: 30
remove-stale-when-updated: true
stale-issue-message: Hey @Lissy93 - Don't forget to respond!
stale-pr-message: Hey @Lissy93 - Don't forget to respond!
only-labels: '👤 Awaiting Maintainer Response'
labels-to-remove-when-unstale: '👤 Awaiting Maintainer Response'
close-issue-message: 'Closed due to no response from repo author for over a year'
close-pr-message: 'Closed due to no response from repo author for over a year'
stale-issue-label: '👤 Awaiting Maintainer Response'
stale-pr-label: '👤 Awaiting Maintainer Response'
close-issue-label: '🕸️ Inactive'
close-pr-label: '🕸️ Inactive'
exempt-issue-labels: '📌 Keep Open'
exempt-pr-labels: '📌 Keep Open'

20
.github/workflows/code-linter.yml vendored Normal file
View File

@ -0,0 +1,20 @@
# Lints code merged into master branch
name: 🌈 Lint Code Base
on:
pull_request:
branches: [master]
jobs:
build:
name: Lint Code Base
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v2
with:
fetch-depth: 0
- name: Lint Code Base
uses: github/super-linter@v4
env:
VALIDATE_ALL_CODEBASE: false
DEFAULT_BRANCH: master
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

30
.github/workflows/code-spell-check.yml vendored Normal file
View File

@ -0,0 +1,30 @@
# Finds typos in the English language within the app, submits a PR with fixes
name: 🌈 Spelling Auto-Fix
on:
push:
branches: [ master ]
pull_request:
types: [opened]
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
if: startsWith(github.head_ref, 'AUTO/') == false
uses: actions/checkout@v2
- name: Spell Check
if: startsWith(github.head_ref, 'AUTO/') == false
uses: sobolevn/misspell-fixer-action@master
- name: Create PR
uses: peter-evans/create-pull-request@v3.10.1
if: startsWith(github.head_ref, 'AUTO/') == false
with:
token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
base: master
commit-message: ':pencil2: Auto-fix typos in text'
title: '[AUTO] Fix spelling and language'
branch: 'AUTO/spelling-corrections'
committer: 'Liss-Bot <alicia-gh-bot@mail.as93.net>'
assignees: Lissy93
reviewers: Lissy93

18
.github/workflows/dependency-updates-summary.yml vendored Normal file
View File

@ -0,0 +1,18 @@
# Shows changes to any yarn.lock in PR comment
# Useful for easily understanding dependency changes and consequences
name: 💡 Show Dependency Changes
on: [pull_request]
jobs:
check:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Yarn Lock Changes
uses: Simek/yarn-lock-changes@main
with:
token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
collapsibleThreshold: '25'
failOnDowngrade: 'false'
path: 'yarn.lock'
updateComment: 'true'

105
.github/workflows/docker-build-publish.yml vendored Normal file
View File

@ -0,0 +1,105 @@
# Scans, builds and releases a multi-architecture docker image
name: 🐳 Build + Publish Multi-Platform Image
on:
workflow_dispatch:
push:
branches: ['master']
tags: [v*]
paths:
- '**.js'
- 'src/**'
- 'public/**'
- 'services/**'
env:
DH_IMAGE: ${{ secrets.DOCKER_REPO }}
GH_IMAGE: ${{ github.repository_owner }}/${{ github.event.repository.name }}
jobs:
docker:
runs-on: ubuntu-latest
permissions: { contents: read, packages: write }
if: "!contains(github.event.head_commit.message, '[ci-skip]')"
steps:
- name: 🛎️ Checkout Repo
uses: actions/checkout@v2
- name: 🔖 Get App Version
uses: tyankatsu0105/read-package-version-actions@v1
id: package-version
# - name: ✨ Validate Dockerfile
# uses: ghe-actions/dockerfile-validator@v1
# with:
# dockerfile: 'Dockerfile'
# lint: 'hadolint'
- name: 🗂️ Make Docker Meta
id: meta
uses: docker/metadata-action@v3
with:
images: |
${{ env.DH_IMAGE }}
ghcr.io/${{ env.GH_IMAGE }}
# ${{ secrets.ACR_SERVER }}/${{ secrets.ACR_USERNAME }}
tags: |
type=ref,event=tag,prefix=release-,suffix={{tag}}
type=semver,pattern={{raw}},value=${{ steps.package-version.outputs.version }}
labels: |
maintainer=Lissy93
org.opencontainers.image.title=Dashy
org.opencontainers.image.description=A self-hosted startpage for your server
org.opencontainers.image.documentation=https://dashy.to/docs
org.opencontainers.image.authors=Alicia Sykes
org.opencontainers.image.licenses=MIT
- name: 🔧 Set up QEMU
uses: docker/setup-qemu-action@v1
- name: 🔧 Set up Docker Buildx
uses: docker/setup-buildx-action@v1
- name: 🔑 Login to DockerHub
uses: docker/login-action@v1
with:
username: ${{ secrets.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_PASSWORD }}
- name: 🔑 Login to GitHub Container Registry
uses: docker/login-action@v1
with:
registry: ghcr.io
username: ${{ github.repository_owner }}
password: ${{ secrets.GITHUB_TOKEN }}
# - name: 🔑 Login to Azure Container Registry
# uses: docker/login-action@v1
# with:
# registry: ${{ secrets.ACR_SERVER }}
# username: ${{ secrets.ACR_USERNAME }}
# password: ${{ secrets.ACR_PASSWORD }}
- name: 🚦 Check Registry Status
uses: crazy-max/ghaction-docker-status@v1
- name: ⚒️ Build and push
uses: docker/build-push-action@v2
with:
context: .
file: ./Dockerfile
platforms: linux/amd64,linux/arm64,linux/arm/v7
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
push: true
# - name: 💬 Set Docker Hub Description
# uses: peter-evans/dockerhub-description@v2
# with:
# repository: lissy93/dashy
# readme-filepath: ./docker/docker-readme.md
# short-description: Dashy - A self-hosted start page for your server
# username: ${{ secrets.DOCKER_USERNAME }}
# password: ${{ secrets.DOCKER_USER_PASS }}

63
.github/workflows/docker-publish.yml vendored Normal file
View File

@ -0,0 +1,63 @@
# Builds a Docker image from with latest tag when master branch is updated
# The publishes it to GitHub container registry as a package
name: 🏗️ Build + Publish Docker Image to GHCR
on:
workflow_dispatch:
push:
branches: ['master']
tags: [v*]
env:
REGISTRY: ghcr.io
IMAGE_NAME: dashy
jobs:
build-and-push-image:
runs-on: ubuntu-latest
if: "!contains(github.event.head_commit.message, '[ci-skip]')"
permissions:
contents: read
packages: write
steps:
# Fetch the code
- name: Checkout repository
uses: actions/checkout@v2
- name: Prepare
id: prep
run: echo ::set-output name=version::${GITHUB_REF##*/}
# Use QEMU for multi-architecture builds
- name: Set up QEMU
uses: docker/setup-qemu-action@v1
with:
platforms: all
# # Use Moby BuildKit
# - name: Set up Docker Buildx
# id: buildx
# uses: docker/setup-buildx-action@v1
# with:
# install: true
# version: latest
# driver-opts: image=moby/buildkit:master
# Login into GH container registry
- name: Log in to registry
run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
# Build the image from default Dockerfile
- name: Build image
run: docker build . --file docker/Dockerfile-multi-arch --tag $IMAGE_NAME --label "runnumber=${GITHUB_RUN_ID}"
# Push build image
- name: Push image
run: |
IMAGE_ID=ghcr.io/${{ github.repository_owner }}/$IMAGE_NAME
IMAGE_ID=$(echo $IMAGE_ID | tr '[A-Z]' '[a-z]')
VERSION=$(echo "${{ github.ref }}" | sed -e 's,.*/\(.*\),\1,')
[[ "${{ github.ref }}" == "refs/tags/"* ]] && VERSION=$(echo $VERSION | sed -e 's/^v//')
[ "$VERSION" == "master" ] && VERSION=latest
echo IMAGE_ID=$IMAGE_ID
echo VERSION=$VERSION
docker tag $IMAGE_NAME $IMAGE_ID:$VERSION
docker push $IMAGE_ID:$VERSION

33
.github/workflows/docs-link-checker.yml vendored Normal file
View File

@ -0,0 +1,33 @@
# Checks for any broken links in the docs, and raises an issue if found
name: 🌈 Broken Link Checker
on:
repository_dispatch:
workflow_dispatch:
schedule:
- cron: '0 1 1 * *' # Run monthly
jobs:
link-checker:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Load Excludes
run: |
LYCHEE_EXCLUDE=$(sed -e :a -e 'N;s/\n/ /;ta' .github/.lycheeexclude)
echo "LYCHEE_EXCLUDE=$LYCHEE_EXCLUDE" >> $GITHUB_ENV
- name: Check for Broken Links
uses: lycheeverse/lychee-action@v1.0.8
with:
args: --verbose -a 200,302,304,429 --exclude ${{ env.LYCHEE_EXCLUDE }} --exclude-mail --no-progress **/*.md
env:
GITHUB_TOKEN: ${{secrets.BOT_GITHUB_TOKEN}}
LYCHEE_OUT: .github/broken-link-report.md
- name: Raise an Issue with Results
uses: peter-evans/create-issue-from-file@v3
with:
token: ${{secrets.BOT_GITHUB_TOKEN}}
title: '[DOCS] Broken Links found in Documentation'
content-filepath: .github/broken-link-report.md
labels: '📕 Docs, 👩‍💻 Good First Issue, 💤 Low Priority, 🤖 Auto'

43
.github/workflows/domain-expirey-check.yml vendored Normal file
View File

@ -0,0 +1,43 @@
name: 📕 Check Docs Domain Expiry
on:
workflow_dispatch:
schedule:
- cron: '0 1 * * 0' # At 01:00 on Sunday.
jobs:
check-domain:
runs-on: ubuntu-latest
name: Check domain
strategy:
matrix:
domain:
- https://dashy.to
steps:
- name: Check domain SSL and registry expire date
id: check-domain
uses: codex-team/action-check-domain@v1
with:
url: ${{ matrix.domain }}
- name: Raise issue if domain expiring soon
if: ${{ steps.check-domain.outputs.paid-till-days-left && steps.check-domain.outputs.paid-till-days-left < 30 }}
uses: rishabhgupta/git-action-issue@v2
with:
token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
assignees: Lissy93
title: '[WEBSITE] Domain Expiring Soon'
body: >
**Priority Notice**
Domain, ${{ matrix.domain }} will expire in ${{ steps.check-domain.outputs.paid-till-days-left }} days.
@Lissy93 - Please take action immediately to prevent any downtime
- name: Raise issue if SSL Cert expiring soon
if: ${{ steps.check-domain.outputs.ssl-expire-days-left && steps.check-domain.outputs.ssl-expire-days-left < 14 }}
uses: rishabhgupta/git-action-issue@v2
with:
token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
assignees: Lissy93
title: '[WEBSITE] SSL Cert Expiring Soon'
body: >
**Priority Notice**
The SSL Certificate for ${{ matrix.domain }} will expire in ${{ steps.check-domain.outputs.ssl-expire-days-left }} days, on ${{ steps.check-domain.outputs.ssl-expire-date }}.
@Lissy93 - Please take action immediately to prevent any downtime

83
.github/workflows/generate-credits.yml vendored Normal file
View File

@ -0,0 +1,83 @@
# Inserts list of contributors and community members into ./docs/credits.md
# Also generates an SVG showing all contributors, which is embedded into readme
name: 📊 Generate Contributor Credits
on:
workflow_dispatch: # Manual dispatch
schedule:
- cron: '0 1 * * 0' # At 01:00 on Sunday.
jobs:
# Job #1 - Generate an embedded SVG asset, showing all contributors
generate-contributors:
runs-on: ubuntu-latest
steps:
- uses: bubkoo/contributors-list@v1
with:
GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
svgPath: docs/assets/CONTRIBUTORS.svg
affiliation: all
includeBots: false
excludeUsers: BeginCI snyk-bot
avatarSize: 96
userNameHeight: 20
svgWidth: 830
commitMessage: ':blue_heart: Updates contributor SVG'
# Job #2 - Fetches sponsors and inserts into readme and credits page
insert-sponsors:
runs-on: ubuntu-latest
steps:
- name: Checkout 🛎️
uses: actions/checkout@v2
- name: Generate Sponsors in Readme 💖
uses: JamesIves/github-sponsors-readme-action@1.0.5
with:
token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
file: 'README.md'
- name: Generate Sponsors in Credits 💖
uses: JamesIves/github-sponsors-readme-action@1.0.5
with:
token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
file: 'docs/credits.md'
# Job #3 - Update the Credits page
insert-credits:
runs-on: ubuntu-latest
name: Inserts contributors into credits.md
steps:
- name: Contributer List - Credits Page
uses: akhilmhdh/contributors-readme-action@v2.3.6
env:
GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
with:
image_size: 80
readme_path: docs/credits.md
columns_per_row: 6
commit_message: ':purple_heart: Updates contributors list'
collaborators: all
committer_username: liss-bot
committer_email: liss-bot@d0h.co
- name: Sponsors List - Readme
uses: akhilmhdh/contributors-readme-action@v2.2
env:
GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
with:
image_size: 80
readme_path: README.md
columns_per_row: 6
commit_message: ':yellow_heart: Updates sponsors table'
committer_username: liss-bot
committer_email: liss-bot@d0h.co
make-author-list:
runs-on: ubuntu-latest
steps:
- name: Checkout 🛎️
uses: actions/checkout@v2
with:
fetch-depth: 0
- uses: wow-actions/update-authors@v1.1.4
with:
GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
sort: commits
bots: true
path: .github/AUTHORS.txt
commit: ':blue_heart: Makes author list'
template: '{{name}} <{{email}}> - {{commits}} commits'

38
.github/workflows/get-size.yml vendored Normal file
View File

@ -0,0 +1,38 @@
# Adds a comment to new PRs, showing the compressed size and size difference of new code
# And also labels the PR based on the number of lines changes
name: 🌈 Check PR Size
on: [pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
# Find and comment with compressed size
- name: Get Compressed Size
uses: preactjs/compressed-size-action@v2
with:
repo-token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
pattern: './dist/**/*.{js,css,html}'
strip-hash: '\\b\\w{8}\\.'
exclude: '{./dist/manifest.json,**/*.map,**/node_modules/**}'
minimum-change-threshold: 100
# Check number of lines of code added
- name: Label based on Lines of Code
uses: codelytv/pr-size-labeler@v1
with:
GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
xs_max_size: '10'
s_max_size: '100'
m_max_size: '500'
l_max_size: '1000'
s_label: '🟩 PR - Small'
m_label: '🟨 PR - Medium'
l_label: '🟧 PR - Large'
xl_label: '🟥 PR - XL'
fail_if_xl: 'false'
message_if_xl: >
It looks like this PR is very large (over 1000 lines).
Try to avoid addressing multiple issues in a single PR, and
in the future consider breaking large tasks down into smaller steps.
This it to make reviewing, testing, reverting and general quality management easier.

18
.github/workflows/issue-translator.yml vendored Normal file
View File

@ -0,0 +1,18 @@
# Will translate any issues opened in foraign language, and add the English translation as a comment
name: 🎯 Issue Translator
on:
issue_comment:
types: [created]
issues:
types: [opened]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: tomsun28/issues-translate-action@v2.5
with:
BOT_GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
BOT_LOGIN_NAME: liss-bot
IS_MODIFY_TITLE: true
CUSTOM_BOT_NOTE: It looks like this issue isn't in English - not a problem, here's the translation! 🇬🇧

16
.github/workflows/label-sponsors.yml vendored Normal file
View File

@ -0,0 +1,16 @@
# Adds a label to any issues raised by a sponsor of Lissy93/Dashy
# In order to allow their request can be prioritized
name: 🎯 Label sponsors
on:
issues:
types: [opened]
jobs:
build:
name: is-sponsor-label
runs-on: ubuntu-latest
steps:
- uses: JasonEtco/is-sponsor-label-action@v1
with:
label: Priority Request - Sponsor 💖
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

18
.github/workflows/label-top-issues.yml vendored Normal file
View File

@ -0,0 +1,18 @@
# Applies the 'Top Issue' label to tickets with most user reactions
name: 🎯 Label Top Issues
on:
workflow_dispatch:
schedule:
- cron: '0 1 * * *' # Run at 01:00 each day
jobs:
labelTopIssues:
name: Label Top Issues
runs-on: ubuntu-latest
steps:
- name: Label Issues
uses: adamzolyak/top-issues-action@master
env:
GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
TOP_NUMBER_OF_ISSUES: 10
TOP_LABEL_NAME: "👍 Top 10 Issue!"
TOP_LABEL_COLOR: FBCA04

27
.github/workflows/lgtm-comment.yml vendored Normal file
View File

@ -0,0 +1,27 @@
# Replies with a random looks-good GIF, when a PR is reviewed with a LGTM comment
name: 💡 Random LGTM GIF
on:
issue_comment: { types: [created] }
pull_request_review: { types: [submitted] }
jobs:
post:
runs-on: ubuntu-latest
if: (!contains(github.actor, '[bot]')) # Exclude bot comment
steps:
- uses: ddradar/choose-random-action@v1
id: act
with:
contents: |
https://media4.giphy.com/media/11ISwbgCxEzMyY/giphy.gif
https://media4.giphy.com/media/SgwPtMD47PV04/giphy.gif
https://media1.giphy.com/media/3orifdxwbvVLfS3CrS/giphy.gif
https://media4.giphy.com/media/RPwrO4b46mOdy/giphy.gif
https://media2.giphy.com/media/3o7abGQa0aRJUurpII/giphy.gif
https://media3.giphy.com/media/ZZrDTGSJXlHW9Y2khu/giphy.gif
https://media3.giphy.com/media/5DQdk5oZzNgGc/giphy.gif
https://media4.giphy.com/media/3o7abB06u9bNzA8lu8/giphy.gif
https://media4.giphy.com/media/l2JJrEx9aRsjNruhi/giphy.gif
- uses: ddradar/lgtm-action@v1
with:
image-url: ${{ steps.act.outputs.selected }}
token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}

17
.github/workflows/manage-pending-labels-closed.yml vendored Normal file
View File

@ -0,0 +1,17 @@
# When a new comment is added to an issue, if it had the Stale or Awaiting User Response labels,
# then those labels will be removed, providing it was not user lissy93 who added the commend.
name: 🎯 Remove Pending Labels on Close
on:
issues:
types: [closed]
jobs:
remove-labels:
runs-on: ubuntu-latest
steps:
- name: Remove Labels when Closed
uses: actions-cool/issues-helper@v2
with:
actions: remove-labels
token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
issue-number: ${{ github.event.issue.number }}
labels: '🚏 Awaiting User Response,⚰️ Stale,👤 Awaiting Maintainer Response'

42
.github/workflows/manage-pending-labels.yml vendored Normal file
View File

@ -0,0 +1,42 @@
# When a new comment is added to an issue, if it had the Stale or Awaiting User Response labels,
# then those labels will be removed, providing it was not user lissy93 who added the commend.
name: 🎯 Add/ Remove Awaiting Response Labels
on:
issue_comment:
types: [created]
jobs:
remove-stale:
runs-on: ubuntu-latest
if: ${{ github.event.comment.author_association != 'COLLABORATOR' && github.event.comment.author_association != 'OWNER' }}
steps:
- name: Remove Stale labels when Updated
uses: actions-cool/issues-helper@v2
with:
actions: remove-labels
token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
issue-number: ${{ github.event.issue.number }}
labels: '🚏 Awaiting User Response,⚰️ Stale'
add-awaiting-author:
runs-on: ubuntu-latest
if: ${{!github.event.issue.pull_request && github.event.comment.author_association != 'COLLABORATOR' && github.event.comment.author_association != 'OWNER' && github.event.issue.state == 'open' }}
steps:
- name: Add Awaiting Author labels when Updated
uses: actions-cool/issues-helper@v2
with:
actions: add-labels
token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
issue-number: ${{ github.event.issue.number }}
labels: '👤 Awaiting Maintainer Response'
remove-awaiting-author:
runs-on: ubuntu-latest
if: ${{ github.event.comment.author_association == 'OWNER' }}
steps:
- name: Remove Awaiting Author labels when Updated
uses: actions-cool/issues-helper@v2
with:
actions: remove-labels
token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
issue-number: ${{ github.event.issue.number }}
labels: '👤 Awaiting Maintainer Response'

20
.github/workflows/mind-your-language.yml vendored Normal file
View File

@ -0,0 +1,20 @@
# Detects offensive language in comments and takes reaction
name: 🎯 Mind your language
on:
issues:
types: [opened]
issue_comment:
types: [created]
pull_request:
types: [opened]
jobs:
echo_issue_comment:
runs-on: ubuntu-latest
name: profanity check
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Profanity check step
uses: tailaiw/mind-your-language-action@v1.0.3
env:
GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}

16
.github/workflows/mirror.yml vendored Normal file
View File

@ -0,0 +1,16 @@
# Pushes the contents of the repo to the Codeberg mirror
name: 🪞 Mirror to Codeberg
on:
workflow_dispatch:
schedule:
- cron: '30 3 * * 0' # At 03:30 on Sunday
jobs:
codeberg:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with: { fetch-depth: 0 }
- uses: pixta-dev/repository-mirroring-action@v1
with:
target_repo_url: git@codeberg.org:alicia/dashy.git
ssh_private_key: ${{ secrets.CODEBERG_SSH }}

22
.github/workflows/new-issues-check.yml vendored Normal file
View File

@ -0,0 +1,22 @@
name: ⭐ Hello non-Stargazers
on:
issues:
types: [opened, reopened]
jobs:
check-user:
if: >
${{
! contains( github.event.issue.labels.*.name, '📌 Keep Open') &&
! contains( github.event.issue.labels.*.name, '🌈 Feedback') &&
! contains( github.event.issue.labels.*.name, '💯 Showcase') &&
github.event.comment.author_association != 'CONTRIBUTOR'
}}
runs-on: ubuntu-latest
name: Add comment to issues opened by non-stargazers
steps:
- name: comment
uses: qxip/please-star-light@v4
with:
token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
autoclose: false
message: "If you're enjoying Dashy, consider dropping us a ⭐<br>_<sub>🤖 I'm a bot, and this message was automated</sub>_"

13
.github/workflows/pr-commenter.yml vendored Normal file
View File

@ -0,0 +1,13 @@
# Adds comments to PR, based on which files are modified
name: 💡 PR Commenter
on: [ pull_request_target ]
jobs:
pr-comment:
runs-on: ubuntu-latest
steps:
- uses: exercism/pr-commenter-action@v1.3.0
with:
github-token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
config-file: .github/pr-auto-comments.yml
template-variables: |
{ "prAuthor": "${{ github.event.pull_request.user.login }}" }

12
.github/workflows/pr-labler.yml vendored Normal file
View File

@ -0,0 +1,12 @@
# Labels pull requests based on their branch name
name: 💡 PR Branch Labeler
on: pull_request
jobs:
label-pr:
runs-on: ubuntu-latest
steps:
- name: Label PR
if: github.event.action == 'opened'
uses: ffittschen/pr-branch-labeler@v1
with:
repo-token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}

13
.github/workflows/raise-issue-from-todo.yml vendored Normal file
View File

@ -0,0 +1,13 @@
# Finds any TO-DO notes within the code, and opens up an issue for it to be fixed
name: 🌈 Open issue for Todos
on: ["push"]
jobs:
build:
runs-on: "ubuntu-latest"
steps:
- uses: "actions/checkout@master"
- name: "TODO to Issue"
uses: "alstr/todo-to-issue-action@v4.2"
id: "todo"
with:
TOKEN: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}

19
.github/workflows/release-commenter.yml vendored Normal file
View File

@ -0,0 +1,19 @@
# Adds a comment to all issues & PRs that were fixed on a new release
name: 💡 Update Issue after Release
on:
release:
types: [published]
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: apexskier/github-release-commenter@v1
with:
GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
label-template: 🛩️ Released {release_tag}, 🔨 Fixed
comment-template: |
**The fix for this issue has now been released in {release_name} ✨**
If you haven't done so already, please [update your instance](https://github.com/Lissy93/dashy/blob/master/docs/management.md#updating) to `{release_tag}` or later. See {release_link} for full info.
Feel free to reach out if you need any more support. If you are enjoying Dashy, consider [supporting the project](https://github.com/Lissy93/dashy/blob/master/docs/contributing.md#contributing).

92
.github/workflows/repo-visualization.yml vendored Normal file
View File

@ -0,0 +1,92 @@
# Generates series of diagrams and visualizations
name: 📊 Generate Repo Stats
on:
workflow_dispatch: # Manual dispatch
schedule:
- cron: '0 1 * * 0' # At 01:00 on Sunday.
jobs:
# File structure chart
file-structure:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@master
- name: Generate File Structure Diagram
uses: githubocto/repo-visualizer@0.7.1
with:
root_path: 'src/'
output_file: docs/assets/repo-visualization.svg
excluded_paths: dist,node_modules
commit_message: ':yellow_heart: Updates repo diagram'
branch: master
# Hercules git branching stats
git-stats:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@master
with:
fetch-depth: 0
- name: Hercules
uses: src-d/hercules@master
- uses: actions/upload-artifact@master
with:
name: hercules_charts
path: hercules_charts.tar
# Lowlighter metrics community metrics
community-stats:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@master
- name: Generate Repo Metrics
uses: lowlighter/metrics@latest
with:
token: ${{ secrets.LISSY93_PAT }}
committer_token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
committer_branch: master
committer_message: ':purple_heart: Adds repo metrics'
filename: docs/assets/repo-metrics.*
template: classic
user: Lissy93
repo: dashy
delay: 5
- name: Generate License Metrics
uses: lowlighter/metrics@latest
with:
token: ${{ secrets.LISSY93_PAT }}
committer_token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
committer_branch: master
committer_message: ':purple_heart: Adds license metrics'
filename: docs/assets/license-metrics.*
template: repository
user: Lissy93
repo: dashy
delay: 5
plugin_licenses: yes
plugin_licenses_setup: yarn build
plugin_licenses_ratio: yes
plugin_licenses_legal: yes
- name: Generate Contributor Metrics
uses: lowlighter/metrics@latest
with:
token: ${{ secrets.LISSY93_PAT }}
committer_token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
committer_branch: master
committer_message: ':purple_heart: Adds contributor metrics'
filename: docs/assets/controbutor-metrics.*
user: Lissy93
repo: dashy
delay: 5
plugin_contributors: yes
plugin_contributors_base: ""
plugin_contributors_head: master
plugin_contributors_ignored: bot
plugin_contributors_contributions: yes
plugin_contributors_sections: contributors

15
.github/workflows/save-repo-analytics.yml vendored Normal file
View File

@ -0,0 +1,15 @@
name: 📊 Save Repo Analytics
on:
workflow_dispatch:
schedule:
- cron: '0 1 * * 0' # At 01:00 on Sunday.
jobs:
gen-stats:
runs-on: ubuntu-latest
steps:
- name: Repo Analytics
uses: jgehrcke/github-repo-stats@HEAD
with:
repository: lissy93/dashy
databranch: DATA/repo-stats
ghtoken: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}

19
.github/workflows/security-scanning.yml vendored Normal file
View File

@ -0,0 +1,19 @@
# Uses Snyk to check for potential vulnerabilities, then sends results to GH security tab
name: 💡 Vulnerability Scanning
on: push
jobs:
security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@master
- name: Run Snyk to check for vulnerabilities
uses: snyk/actions/node@master
continue-on-error: true
env:
SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
with:
args: --sarif-file-output=snyk.sarif
- name: Upload result to GitHub Code Scanning
uses: github/codeql-action/upload-sarif@v1
with:
sarif_file: snyk.sarif

17
.github/workflows/unfurl-links.yml vendored Normal file
View File

@ -0,0 +1,17 @@
# Expands any raw pasted link in comments. Useful so people know what they're clicking
name: 🎯 Unfurl Links
on:
issues:
types: [opened]
issue_comment:
types: [created]
pull_request:
types: [opened]
jobs:
run:
runs-on: ubuntu-latest
steps:
- uses: wow-actions/unfurl-links@v1
with:
GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
raw: true

30
.github/workflows/wiki-sync.yml vendored Normal file
View File

@ -0,0 +1,30 @@
# Uses the contents of the ./docs directory for Dashy's GH Wiki page
name: 📊 Wiki Sync
on:
workflow_dispatch: # Manual dispatch
schedule:
- cron: '0 1 * * 0' # At 01:00 on Sunday.
jobs:
update-wiki:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@master
- name: Upload Docs to GH Wiki
uses: docker://decathlon/wiki-page-creator-action:latest
env:
GH_PAT: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
ACTION_MAIL: alicia-gh-bot@mail.as93.net
ACTION_NAME: liss-bot
OWNER: Lissy93
REPO_NAME: Dashy
MD_FOLDER: docs/
# - name: Sync Wiki
# uses: joeizzard/action-wiki-sync@master
# with:
# username: example
# access_token: ${{ secrets.GITHUB_TOKEN }}
# wiki_folder: ./docs
# commit_username: 'liss-bot'
# commit_email: 'liss-bot@d0h.co'
# commit_message: '📕 Chore: Sync Wiki'

21
.gitignore vendored Normal file
View File

@ -0,0 +1,21 @@
.DS_Store
node_modules
/dist
# local env files
.env.local
.env.*.local
# Log files
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Editor directories and files
.idea
.vscode
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?

29
.gitpod.yml Normal file
View File

@ -0,0 +1,29 @@
# Config for running Dashy in GitPod's cloud dev environment
# Docs: https://www.gitpod.io/docs/references/gitpod-yml
# Commands to start on workspace startup
tasks:
- init: yarn install
command: yarn dev
# Ports to expose on workspace startup
ports:
- port: 8080 # Default dev server
visibility: private
onOpen: open-preview
- port: 4000 # Default prod server
visibility: public
onOpen: open-preview
prebuilds:
# Adds 'Open in GitPod' to PRs
addBadge: true
addComment: false
vscode:
# Adds Vue.js and formatting extensions
extensions:
- octref.vetur
- dbaeumer.vscode-eslint
- streetsidesoftware.code-spell-checker
- PKief.material-icon-theme
- wix.vscode-import-cost
- oderwat.indent-rainbow
- eamodio.gitlens

1
CNAME Normal file
View File

@ -0,0 +1 @@
dashy.to

53
Dockerfile Normal file
View File

@ -0,0 +1,53 @@
FROM node:16.13.2-alpine AS BUILD_IMAGE
# Set the platform to build image for
ARG TARGETPLATFORM
ENV TARGETPLATFORM=${TARGETPLATFORM:-linux/amd64}
# Install additional tools needed if on arm64 / armv7
RUN \
case "${TARGETPLATFORM}" in \
'linux/arm64') apk add --no-cache python3 make g++ ;; \
'linux/arm/v7') apk add --no-cache python3 make g++ ;; \
esac
# Create and set the working directory
WORKDIR /app
# Install app dependencies
COPY package.json yarn.lock ./
RUN yarn install --frozen-lockfile --network-timeout 1000000
# Copy over all project files and folders to the working directory
COPY . ./
# Build initial app for production
RUN yarn build --mode production
# Production stage
FROM node:16.13.2-alpine
# Define some ENV Vars
ENV PORT=80 \
DIRECTORY=/app \
IS_DOCKER=true
# Create and set the working directory
WORKDIR ${DIRECTORY}
# Update tzdata for setting timezone
RUN apk add --no-cache tzdata
# Copy built application from build phase
COPY --from=BUILD_IMAGE /app ./
# Ensure only one version of conf.yml exists
RUN rm dist/conf.yml
# Finally, run start command to serve up the built application
CMD [ "yarn", "start" ]
# Expose the port
EXPOSE ${PORT}
# Run simple healthchecks every 5 mins, to check that everythings still great
HEALTHCHECK --interval=5m --timeout=5s --start-period=30s CMD yarn health-check

21
LICENSE Normal file
View File

@ -0,0 +1,21 @@
MIT License
Copyright (c) 2021-2022 Alicia Sykes <https://aliciasykes.com>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

1
Procfile Normal file
View File

@ -0,0 +1 @@
web: npm run build-and-start

829
README.md Normal file
View File

@ -0,0 +1,829 @@
<h1 align="center">Dashy</h1>
<p align="center">
<i>Dashy helps you organize your self-hosted services by making them accessible from a single place</i>
<br/>
<img width="120" src="https://i.ibb.co/yhbt6CY/dashy.png" />
<br/>
<b><a href="./docs/showcase.md">User Showcase</a></b> | <b><a href="https://demo.dashy.to">Live Demo</a></b> | <b><a href="./docs/quick-start.md">Getting Started</a></b> | <b><a href="https://dashy.to/docs">Documentation</a></b> | <b><a href="https://github.com/Lissy93/dashy">GitHub</a></b>
<br/><br/>
<a href="https://github.com/awesome-selfhosted/awesome-selfhosted#personal-dashboards">
<img src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg" alt="Awesome Self-Hosted">
</a>
<a href="./LICENSE">
<img src="https://img.shields.io/badge/License-MIT-0aa8d2?logo=opensourceinitiative&logoColor=fff" alt="License MIT">
</a>
<a href="./.github/CHANGELOG.md">
<img src="https://img.shields.io/github/package-json/v/lissy93/dashy?logo=azurepipelines&amp;color=0aa8d2" alt="Current Version">
</a>
<a href="https://hub.docker.com/r/lissy93/dashy">
<img src="https://img.shields.io/docker/pulls/lissy93/dashy?logo=docker&color=0aa8d2&logoColor=fff" alt="Docker Pulls">
</a>
<a href="http://as93.link/dashy-build-status">
<img src="https://badgen.net/github/status/lissy93/dashy?icon=github" alt="GitHub Status">
</a>
<a href="https://snyk.io/test/github/lissy93/dashy">
<img src="https://snyk.io/test/github/lissy93/dashy/badge.svg" alt="Known Vulnerabilities">
</a>
</p>
<details>
<summary><b>Table of Contents</b></summary>
<p>
- **Getting Started**
- [🌈 Features](#features-)
- [⚡Demo](#demo-)
- [🚀 Getting Started](#getting-started-)
- [🔧 Configuring](#configuring-)
- **Feature Overview**
- [🎨 Theming](#theming-)
- [🧸 Icons](#icons-)
- [🚦 Status Indicators](#status-indicators-)
- [📊 Widgets](#widgets-)
- [🔐 Authentication](#authentication-)
- [👓 Alternate Views](#alternate-views-)
- [🖱️ Opening Methods](#opening-methods-)
- [🔎 Searching and Shortcuts](#searching-and-shortcuts-)
- [⚙️ Config Editor](#config-editor-)
- [☁ Cloud Backup & Sync](#cloud-backup--sync-)
- [🌎 Language Switching](#language-switching-)
- [📃 Multi-Page Support](#multi-page-support-)
- **Community**
- [📊 System Requirements](#system-requirements-)
- [🙋‍♀️ Support](#support-)
- [💖 Supporting Dashy](#supporting-dashy-)
- [🏆 Credits](#credits-)
- [🧱 Developing](#developing-)
- [🗞️ Release Schedule](#release-schedule-)
- [📘 Documentation](#documentation-)
- [🛣️ Roadmap](#roadmap-)
- [🙌 Alternatives](#alternatives-)
- [📜 License](#license-)
</p>
</details>
## Features 🌈
- 📃 Support for multiple pages
- 🚦 Real-time status monitoring for each of your apps/links
- 📊 Use widgets to display info and dynamic content from self-hosted services
- 🔎 Instant search by name, domain, or tags + customizable hotkeys & keyboard shortcuts
- 🎨 Many built-in color themes, with UI color editor and support for custom CSS
- 🧸 Many icon options - Font-Awesome, homelab icons, auto-fetching Favicon, images, emojis, etc.
- 💂 Optional authentication with multi-user access, configurable privileges, and SSO support
- 🌎 Multi-language support, with 10+ human-translated languages, and more on the way
- ☁ Optional, encrypted, free off-site cloud backup and restore feature available
- 💼 A workspace view, for easily switching between multiple apps simultaneously
- 🛩️ A minimal view, for use as a fast-loading browser Startpage
- 🖱️ Choose app launch methods: new tab, same tab, clipboard, pop-up modal, or open in workspace view
- 📏 Customizable layout, sizes, text, component visibility, sort order, behavior, etc.
- 🖼️ Options for a full-screen background image, custom nav-bar links, HTML footer, title, etc.
- 🚀 Easy to setup with Docker, or on bare metal, or with 1-Click cloud deployment
- ⚙️ Easy single-file YAML-based configuration, and option to configure app through the UI
- ✨ Under active development with improvements and new features added regularly
- 🤏 Small bundle size, fully responsive UI, and PWA for basic offline access
- 🆓 100% free and open-source
- 🔐 Strong focus on privacy
- 🌈 And loads more...
**[⬆️ Back to Top](#dashy)**
## Demo ⚡
**Live Instances**: [Demo 1](https://demo.dashy.to) (Live Demo) ┆ [Demo 2](https://live.dashy.to) (Dashy Links) ┆ [Demo 3](https://dev.dashy.to) (Dev Preview)
**Screenshots**: Checkout the [Showcase](./docs/showcase.md), to see example dashboards from the community
**Spin up your own demo**: [![One-Click Deploy with PWD](https://img.shields.io/badge/Play--with--Docker-Deploy-2496ed?style=flat-square&logo=docker)](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml) or [`docker run -p 8080:80 lissy93/dashy`](./docs/quick-start.md)
<p align="center">
<img width="800" src="https://i.ibb.co/L8YbNNc/dashy-demo2.gif" alt="Demo" />
</p>
**[⬆️ Back to Top](#dashy)**
---
## Getting Started 🚀
> For full setup instructions, see: [**Deployment**](./docs/deployment.md)
### Deploying from Docker Hub 🐳
You will need [Docker](https://docs.docker.com/get-docker/) installed on your system
```
docker run -p 8080:80 lissy93/dashy
```
Or
```docker
docker run -d \
-p 4000:80 \
-v /root/my-local-conf.yml:/app/public/conf.yml \
--name my-dashboard \
--restart=always \
lissy93/dashy:latest
```
[![Dashy on Docker Hub](https://dockeri.co/image/lissy93/dashy)](https://hub.docker.com/r/lissy93/dashy)
See also: [examples with Docker Compose](./docs/deployment.md#using-docker-compose). Dashy is also available via GHCR, and tags for other architectures (`arm32v7`, `arm64v8`, etc.) and set versions are supported
> Once you've got Dashy running, see [App Management Docs](./docs/management.md) for info on using health checks, updating, backups, web-server configs, logs, performance, security, and more.
### Deploying from Source 🔨
You will need [git](https://git-scm.com/downloads), the latest or LTS version of [Node.js](https://nodejs.org/) and _(optionally)_ [Yarn](https://yarnpkg.com/) installed on your system.
- Clone the Repo: `git clone https://github.com/Lissy93/dashy.git` and `cd dashy`
- Configuration: Fill in your settings in `./public/conf.yml`
- Install dependencies: `yarn`
- Build: `yarn build`
- Run: `yarn start`
> See docs: [Full list of Dashy's commands](./docs/management.md#basic-commands)
### Deploy to the Cloud ☁️
Dashy supports **1-Click deployments** on several popular cloud platforms. To spin up a new instance, just click a link below:
- [<img src="https://i.ibb.co/ZxtzrP3/netlify.png" width="18"/> Deploy to Netlify](https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy)
- [<img src="https://i.ibb.co/d2P1WZ7/heroku.png" width="18"/> Deploy to Heroku](https://heroku.com/deploy?template=https://github.com/Lissy93/dashy)
- [<img src="https://i.ibb.co/Ld2FZzb/vercel.png" width="18"/> Deploy to Vercel](https://vercel.com/new/project?template=https://github.com/lissy93/dashy)
- [<img src="https://i.ibb.co/xCHtzgh/render.png" width="18"/> Deploy to Render](https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render)
- [<img src="https://i.ibb.co/J7MGymY/googlecloud.png" width="18"/> Deploy to GCP](https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git)
- [<img src="https://i.ibb.co/HVWVYF7/docker.png" width="18"/> Deploy to PWD](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml)
- [<img src="https://i.ibb.co/7NxnM2P/easypanel.png" width="18"/> Deploy to Easypanel](https://easypanel.io/docs/templates/dashy)
> For more 1-click cloud deployments, see [Cloud Deployment](./docs/deployment.md#deploy-to-cloud-service)
**[⬆️ Back to Top](#dashy)**
---
## Configuring 🔧
> For full configuration documentation, see: [**Configuring**](./docs/configuring.md)
Dashy is configured through a YAML file, located at `./public/conf.yml`. In addition, you can find a complete list of available options in the [Configuring Docs](./docs/configuring.md). The config can also be edited and saved directly through the UI.
**[⬆️ Back to Top](#dashy)**
---
## Theming 🎨
> For full theming documentation, see: [**Theming**](./docs/theming.md)
Dashy comes pre-bundled with several built-in themes, which you can preview, apply and edit through the UI. With the theme configurator and support for custom CSS, everything is in place to quickly develop your own unique-looking dashboard.
<p align="center">
<a href="https://i.ibb.co/BVSHV1v/dashy-themes-slideshow.gif">
<img alt="Example Themes" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/theme-slideshow.gif" width="400" />
</a>
</p>
<p align="center">
<a href="https://i.ibb.co/cLDXj1R/dashy-theme-configurator.gif">
<img alt="Example Themes" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/theme-config-demo.gif" width="400" />
</a>
</p>
**[⬆️ Back to Top](#dashy)**
---
## Icons 🧸
> For full iconography documentation, see: [**Icons**](./docs/icons.md)
Both sections and items can have an icon associated with them, defined under the `icon` attribute. With several different icon packs supported, you'll be able to find the perfect thumbnail for any app or service.
The following icon types are supported:
- **Favicon** - Automatically fetch an apps icon from its Favicon or logo image
- **Icon Packs** - Use any icon from [font-awesome], [simple-icons] or [material icons]
- **Emoji** - Any valid emoji can be used as an icon
- **Generative** - Unique, auto-generated images for easily identifying services
- **URL** - Pass the URL of any valid image in to have it fetched and rendered
- **Local** - Store custom images locally and reference by filename
- **Homelab Icons** - Using [dashboard-icons] for logos of commonly self-hosted services
[font-awesome]: https://fontawesome.com/icons
[simple-icons]: https://simpleicons.org/
[material icons]: https://github.com/Templarian/MaterialDesign
[dashboard-icons]: https://github.com/WalkxCode/dashboard-icons
<p align="center">
<img width="400" src="https://i.ibb.co/GTVmZnc/dashy-example-icons.png" />
</p>
**[⬆️ Back to Top](#dashy)**
---
## Status Indicators 🚦
> For full monitoring documentation, see: [**Status Indicators**](./docs/status-indicators.md)
Dashy has an optional feature to check if each app/ service is up and responding, then display a small status indicator icon. Hovering over it will show additional stats like response time and status code.
Status indicators can be globally enabled by setting `appConfig.statusCheck: true` or enabled/ disabled on a per-item basis. Status is checked on page load, but you can allow continuous polling by specifying a time interval between checks, in seconds under `appConfig.statusCheckInterval`. You can also use a different endpoint for status checking, with `statusCheckUrl`, and if needed, pass in custom headers under `statusCheckHeaders`.
<p align="center">
<img alt="Status Checks demo" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/status-check-demo.gif" width="600" />
</p>
**[⬆️ Back to Top](#dashy)**
---
## Widgets 📊
> For full widget documentation, see: [**Widgets**](./docs/widgets.md)
You can display dynamic content from services in the form of widgets. There are several pre-built widgets availible for showing useful info, and integrations with commonly self-hosted services, but you can also easily create your own for almost any app.
<p align="center">
<img width="600" src="https://i.ibb.co/GFjXVHy/dashy-widgets.png" />
</p>
**[⬆️ Back to Top](#dashy)**
---
## Authentication 🔐
> For full authentication documentation, see: [**Authentication**](./docs/authentication.md)
Dashy has full support for secure single-sign-on using [Keycloak](https://www.keycloak.org/) for secure, easy authentication, see [setup docs](/docs/authentication.md#keycloak) for a full usage guide.
There is also a basic auth feature, which doesn't require additional setup. To enable this, add an `auth` attribute under `appConfig`, containing an array of `users`, each with a username, SHA-256 hashed password and optional user type. Basic auth also supports several access control features, including read-only guest access and granular controls.
```yaml
appConfig:
auth:
users:
- user: alicia
hash: 4D1E58C90B3B94BCAD9848ECCACD6D2A8C9FBC5CA913304BBA5CDEAB36FEEFA3
type: admin
```
Other access control systems are also supported, see the [Alternative Auth Methods](./docs/authentication.md#alternative-authentication-methods) docs.
**[⬆️ Back to Top](#dashy)**
---
## Alternate Views 👓
As well as the default homepage, there is also:
- A minimal view, valid for use as a browser start page
- A workspace view, useful for visiting many apps simultaneously
You can change the view from the UI, using the switch icon in the top-right corner, or select a default view in the config under `appConfig.startingView` attribute.
<p align="center">
<b>Example of Workspace View</b><br>
<img alt="Workspace view demo" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/workspace-demo.gif" width="600" />
</p>
<p align="center">
<b>Example of Minimal View</b><br>
<img alt="Workspace view demo" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/minimal-view-demo.gif" width="600" />
</p>
**[⬆️ Back to Top](#dashy)**
---
## Opening Methods 🖱️
> For full documentation on views and opening methods, see: [**Alternate Views**](./docs/alternate-views.md)
There are several different ways you can launch apps. You can specify the default opening method for any given item under the `target` attribute or set a site-wide default under `appConfig.defaultOpeningMethod`. Right-click on an item to item for all options. The following options are supported:
- `sametab` - The app will be launched in the current tab
- `newtab` - The app will be launched in a new tab (or use Ctrl + Click)
- `modal` - Launch app in a resizable/ movable popup modal on the current page (or use Alt + Click)
- `workspace` - Changes to Workspace view and launches app
- `clipboard` - Copy the app's URL to your system clipboard
- `top` - Opens in the top-most browsing context, useful if you're accessing Dashy through an iframe
**[⬆️ Back to Top](#dashy)**
---
## Searching and Shortcuts 🔎
> For full documentation on searching, see: [**Searching & Shortcuts**](./docs/searching.md)
Quickly finding and launching applications is the primary aim of Dashy. To that end, instant search and customizable keyboard shortcuts are built-in.
To start filtering, start typing—no need to select the search bar or use any special key. Then use either the tab key or arrow keys to select and move between results, and hit enter to launch the currently selected application.
For apps that you use regularly, you can set a custom keybinding. Use the `hotkey` parameter on a certain item to specify a numeric key between `0 - 9`. You can then launch that app by just pressing that key.
You can also add custom tags to a given item to make finding them based on keywords easier. For example, in the following example, searching for 'Movies' will show 'Plex'
```yaml
items:
- title: Plex
hotkey: 8
icon: favicon
description: Media library
url: https://plex.lab.local
tags: [ movies, videos, music ]
```
To search the web directly through Dashy, just press enter after typing your query. Options for web search are set under `appConfig.webSearch`. There is built-in support for [10+ search engines](./docs/searching.md#setting-search-engine), or [use your own custom provider](./docs/searching.md#using-custom-search-engine) or self-hosted instance. With the web search, you can also define your bangs to redirect results to any given app, website, or search engine, when the query is preceded with a certain character sequence (usually beginning in `/`, `!` or `:`).
```yaml
webSearch:
searchEngine: duckduckgo
openingMethod: newtab
searchBangs:
/r: reddit
/w: wikipedia
/s: https://whoogle.local/search?q=
':wolf': wolframalpha
':so': stackoverflow
':git': github
```
Hit `Esc` at any time to close any open apps, clear the search field, or hide any modals.
**[⬆️ Back to Top](#dashy)**
---
## Config Editor ⚙️
> For full config documentation, see: [**Configuring**](./docs/configuring.md)
As well as passing in a YAML config file, you can also configure the app directly through the UI and preview changes live.
To edit any section or item, right-click on it, and select "Edit", or enter the Edit Mode (using the Pen icon in the top-right), then click any part of the page to edit. Changes will be visible immediately but will not be saved until clicking "Save to Disk" or "Save Locally".
Under the config menu, you can export, view, backup, or reset app config and edit the raw config file in a text editor with built-in schema validation. It's recommended to keep a backup of your config.
<p align="center">
<img alt="Interactive Editor demo" src="https://user-images.githubusercontent.com/1862727/139543020-b0576d28-0830-476f-afc8-a815d4de6def.gif" width="600" />
</p>
<p align="center">
<img alt="Config Editor demo" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/config-editor-demo.gif" width="600" />
</p>
**[⬆️ Back to Top](#dashy)**
---
## Cloud Backup & Sync ☁
> For full backup documentation, see: [**Cloud Backup & Sync**](./docs/backup-restore.md)
Dashy has an **optional** built-in feature for securely backing up your config to a hosted cloud service and then restoring it on another instance. This is useful not only for backing up your configuration off-site but also enables Dashy to be used without having to write a YAML config file.
All data is fully E2E encrypted before being sent to the backend (done in [`CloudBackup.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/CloudBackup.js) using [crypto.js](https://github.com/brix/crypto-js) 's AES method). The data is then sent to a [Cloudflare worker](https://developers.cloudflare.com/workers/learning/how-workers-works) and stored in a [KV](https://developers.cloudflare.com/workers/learning/how-kv-works) data store.
**[⬆️ Back to Top](#dashy)**
---
## Language Switching 🌎
> For full internationalization documentation, see: [**Multi-Language Support**](./docs/multi-language-support.md)
Dashy supports multiple languages and locales. When available, your language should be automatically detected and applied on load. But you can also select a language through the UI (under config --> Switch Language) or set `appConfig.language` to your language (specified as a 2-digit [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)), as seen below, e.g. `language: de`.
#### Supported Languages
- 🇬🇧 **English**: `en` - _Default_
- 🇦🇪 **Arabic**: `ar` - _Auto-generated_
- 🇧🇩 **Bengali**: `bn` - Contributed by **[@soaibsafi](https://github.com/soaibsafi)**
- 🇧🇬 **Bulgarian**: `bg` - Contributed by **[@asenov](https://github.com/asenov)**
- 🇨🇳 **Chinese**: `cn` - Contributed by **[@FormatToday](https://github.com/FormatToday)**
- 🇨🇿 **Czech**: `cs` - Contributed by **[@Tuzi555](https://github.com/Tuzi555)**
- 🇩🇰 **Danish**: `da` - Contributed by **[@lordpansar](https://github.com/lordpansar)**
- 🇳🇱 **Dutch**: `nl` - Contributed by **[@evroon](https://github.com/evroon)**
- 🇫🇷 **French**: `fr` - Contributed by **[@EVOTk](https://github.com/EVOTk)**
- 🇩🇪 **German**: `de` - Contributed by **[@Niklashere](https://github.com/Niklashere)**
- 🇬🇷 **Greek**: `el` - Contributed by **[@aviolaris](https://github.com/aviolaris)**
- 🇮🇳 **Hindi**: `hi` - _Auto-generated_
- 🇮🇹 **Italian**: `it` - Contributed by **[@alexdelprete](https://github.com/alexdelprete)**
- 🇯🇵 **Japanese**: `ja` - _Auto-generated_
- 🇰🇷 **Korean**: `ko` - Contributed by **[@boggy-cs](https://github.com/boggy-cs)**
- 🇳🇴 **Norwegian Bokmål**: `nb` - Contributed by **[@rubjo](https://github.com/rubjo)**
- 🇵🇱 **Polish**: `pl` - Contributed by **[@skaarj1989](https://github.com/skaarj1989)**
- 🇵🇹 **Portuguese**: `pt` - Contributed by **[@LeoColman](https://github.com/LeoColman)**
- 🛰️ **Galician**: `gl` - Contributed by **[@pvillaverde](https://github.com/pvillaverde)**
- 🇷🇺 **Russian**: `ru` - _Auto-generated_
- 🇸🇰 **Slovak**: `sk` - Contributed by **[@Smexhy](https://github.com/Smexhy)**
- 🇸🇮 **Slovenian**: `sl` - Contributed by **[@UrekD](https://github.com/UrekD)**
- 🇪🇸 **Spanish**: `es` - Contributed by **[@lu4t](https://github.com/lu4t)**
- 🇸🇪 **Swedish**: `sv` - Contributed by **[@BOZG](https://github.com/BOZG)**
- 🇹🇼 **Traditional Chinese**: `zh-TW` - Contributed by **[@stanly0726](https://github.com/stanly0726)**
- 🇹🇷 **Turkish**: `tr` - Contributed by **[@imsakg](https://github.com/imsakg)**
- 🏴‍☠️ **Pirate**: `pirate` - Contributed by **[@Lissy93](https://github.com/lissy93)**
#### Add your Language
I would love Dashy to be available to everyone without language being a barrier to entry. If you've got a few minutes to spare, consider adding translations for your language. It's a quick task, and all text is in [a single JSON file](https://github.com/Lissy93/dashy/tree/master/src/assets/locales). Since any missing text will fall back to English, you don't need to translate it all.
**[⬆️ Back to Top](#dashy)**
---
## Multi-Page Support 📃
> For full multi-page documentation, see: [**Pages & Sections**](./docs/pages-and-sections.md)
Within your dashboard, you can have as many sub-pages as you require. To load additional pages, specify a name, and path to a config file under `pages`. The config file can be either local (stored in `/public`), or remote (located anywhere accessible).
```yaml
pages:
- name: Networking Services
path: 'networking.yml'
- name: Work Stuff
path: 'work.yml'
```
Or
```yaml
pages:
- name: Getting Started
path: 'https://snippet.host/tvcw/raw'
- name: Homelab
path: 'https://snippet.host/tetp/raw'
- name: Browser Startpage
path: 'https://snippet.host/zcom/raw'
```
---
## System Requirements 📊
If running on bare metal, Dashy requires [Node](https://nodejs.org/en/) V 16.0.0 or later, LTS (16.13.2) is recommended.
If running in Docker container, the recommended base image is Alpine (3.15)
The hardware requirements vary depending on where and how you are running Dashy. Generally speaking, on a bare-metal system or Docker container, 1GB of memory should be more than enough, and depending on whether you are using your own assets, then 1GB of disk space should be sufficient.
If you are using one of the 1-click cloud deployment methods, serving the app through a CDN or using a static hosting provider, then there are no specific requirements, as the built app is just a series of static JS files, and so is very light-weight.
Dashy also wells run on low-powered ARM-based single board computers, such as a Raspberry Pi (tested on Pi 3)
**Browser Support**
![Chrome](https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_48x48.png) | ![Firefox](https://raw.githubusercontent.com/alrra/browser-logos/master/src/firefox/firefox_48x48.png) | ![IE](https://raw.githubusercontent.com/alrra/browser-logos/master/src/edge/edge_48x48.png) | ![Opera](https://raw.githubusercontent.com/alrra/browser-logos/master/src/opera/opera_48x48.png) | ![Safari](https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_48x48.png)
--- | --- | --- | --- | --- |
Latest ✔ | Latest ✔ | 10+ ✔ | Latest ✔ | 6.1+ ❌ |
**[⬆️ Back to Top](#dashy)**
---
## Support 🙋‍♀️
If you're having trouble getting Dashy up and running, or have a question about usage or configuration, feel free to ask. The best place to do this is via [the Discussions](https://github.com/Lissy93/dashy/discussions).
If you've found something which isn't working as it should, please raise a bug by [opening a ticket](https://github.com/Lissy93/dashy/issues/new/choose).
It's best to check the [docs](./docs), [previous issues](https://github.com/Lissy93/dashy/issues?q=label%3A%22%F0%9F%A4%B7%E2%80%8D%E2%99%82%EF%B8%8F+Question%22+) and [troubleshooting guide](./docs/troubleshooting.md) first.
**[⬆️ Back to Top](#dashy)**
---
## Supporting Dashy 💖
> For full details and other ways you can help out, see: [**Contributing**](./docs/contributing.md)
If you're using Dashy and would like to help support its development, then that would be awesome! Contributions of any type, any size, are always very much appreciated, and we will appropriately credit you for your effort.
Several areas that we need a bit of help with at the moment are:
- Translating - Help make Dashy available to non-native English speakers by [adding your language](./docs/multi-language-support.md#adding-a-new-language)
- Donate a small amount by [Sponsoring @Lissy93 on GitHub](https://github.com/sponsors/Lissy93) and receive some extra perks!
- Complete a [short survey](https://survey.typeform.com/to/gl0L68ou) to have your say about future features
- Share your dashboard in the [Showcase](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md#dashy-showcase-), to inspire others
- Spread the word by sharing Dashy or a screenshot of your dashboard to help new users discover it
- Submit a PR to add a new feature, fix a bug, update the docs, add a theme, widget or something else
- Star Dashy on GitHub/ DockerHub or leave an upvote / review on [these platforms](https://github.com/Lissy93/dashy/blob/master/docs/contributing.md#star-upvote-or-leave-a-review)
[![Sponsor Lissy93 on GitHub](./docs/assets/sponsor-button.svg)](https://github.com/sponsors/Lissy93)
**[⬆️ Back to Top](#dashy)**
## Credits 🏆
> For a complete list of credits, and attributions to packages used within Dashy, see: [**Credits**](./docs/credits.md)
Thank you so much to everyone who has helped with Dashy so far; every contribution is very much appreciated.
#### Sponsors
Huge thanks to the sponsors helping to support Dashy's development!
<!-- readme: sponsors -start -->
<table>
<tr>
<td align="center">
<a href="https://github.com/koconder">
<img src="https://avatars.githubusercontent.com/u/25068?u=582657b23622aaa3dfe68bd028a780f272f456fa&v=4" width="80;" alt="koconder"/>
<br />
<sub><b>Vincent Koc</b></sub>
</a>
</td>
<td align="center">
<a href="https://github.com/peng1can">
<img src="https://avatars.githubusercontent.com/u/225854?v=4" width="80;" alt="peng1can"/>
<br />
<sub><b>Peng1can</b></sub>
</a>
</td>
<td align="center">
<a href="https://github.com/tbjers">
<img src="https://avatars.githubusercontent.com/u/1117052?u=539d96d5e581b3139c75713ce35b89a36626404c&v=4" width="80;" alt="tbjers"/>
<br />
<sub><b>Torgny Bjers</b></sub>
</a>
</td>
<td align="center">
<a href="https://github.com/emlazzarin">
<img src="https://avatars.githubusercontent.com/u/1141361?u=714e3487a3f2e0df721b01a0133945f075d3ff68&v=4" width="80;" alt="emlazzarin"/>
<br />
<sub><b>Eddy Lazzarin</b></sub>
</a>
</td>
<td align="center">
<a href="https://github.com/AnandChowdhary">
<img src="https://avatars.githubusercontent.com/u/2841780?u=747e554b3a7f12eb20b7910e1c87d817844f714f&v=4" width="80;" alt="AnandChowdhary"/>
<br />
<sub><b>Anand Chowdhary</b></sub>
</a>
</td>
<td align="center">
<a href="https://github.com/shrippen">
<img src="https://avatars.githubusercontent.com/u/2873570?v=4" width="80;" alt="shrippen"/>
<br />
<sub><b>Shrippen</b></sub>
</a>
</td></tr>
<tr>
<td align="center">
<a href="https://github.com/davidpaulyoung">
<img src="https://avatars.githubusercontent.com/u/3418369?v=4" width="80;" alt="davidpaulyoung"/>
<br />
<sub><b>David Young</b></sub>
</a>
</td>
<td align="center">
<a href="https://github.com/bile0026">
<img src="https://avatars.githubusercontent.com/u/5022496?u=aec96ad173c0ea9baaba93807efa8a848af6595c&v=4" width="80;" alt="bile0026"/>
<br />
<sub><b>Zach Biles</b></sub>
</a>
</td>
<td align="center">
<a href="https://github.com/UlisesGascon">
<img src="https://avatars.githubusercontent.com/u/5110813?u=3c41facd8aa26154b9451de237c34b0f78d672a5&v=4" width="80;" alt="UlisesGascon"/>
<br />
<sub><b>Ulises Gascón</b></sub>
</a>
</td>
<td align="center">
<a href="https://github.com/digitalarche">
<img src="https://avatars.githubusercontent.com/u/6546135?u=d033c9c16e8367987aec3f9ff5922bc67dd1eedf&v=4" width="80;" alt="digitalarche"/>
<br />
<sub><b>Digital Archeology</b></sub>
</a>
</td>
<td align="center">
<a href="https://github.com/bmcgonag">
<img src="https://avatars.githubusercontent.com/u/7346620?u=2a0f9284f3e12ac1cc15288c254d1ec68a5081e8&v=4" width="80;" alt="bmcgonag"/>
<br />
<sub><b>Brian McGonagill</b></sub>
</a>
</td>
<td align="center">
<a href="https://github.com/vlad-timofeev">
<img src="https://avatars.githubusercontent.com/u/11474041?u=eee43705b54d2ec9f51fc4fcce5ad18dd17c87e4&v=4" width="80;" alt="vlad-timofeev"/>
<br />
<sub><b>Vlad Timofeev</b></sub>
</a>
</td></tr>
<tr>
<td align="center">
<a href="https://github.com/helixzz">
<img src="https://avatars.githubusercontent.com/u/12218889?u=d06d0c103dfbdb99450623064f7da3c5a3675fb6&v=4" width="80;" alt="helixzz"/>
<br />
<sub><b>HeliXZz</b></sub>
</a>
</td>
<td align="center">
<a href="https://github.com/undefined">
<img src="" width="80;" alt="undefined"/>
<br />
<sub><b>Undefined</b></sub>
</a>
</td>
<td align="center">
<a href="https://github.com/Bastii717">
<img src="https://avatars.githubusercontent.com/u/53431819?u=604977bed6ad6875ada890d0d3765a4cacc2fa14&v=4" width="80;" alt="Bastii717"/>
<br />
<sub><b>Bastii717</b></sub>
</a>
</td>
<td align="center">
<a href="https://github.com/ratty222">
<img src="https://avatars.githubusercontent.com/u/92832598?u=137b65530cbd5f5af9c24cde51baa6cc77cc934b&v=4" width="80;" alt="ratty222"/>
<br />
<sub><b>Ratty222</b></sub>
</a>
</td>
<td align="center">
<a href="https://github.com/CrazyWolf13">
<img src="https://avatars.githubusercontent.com/u/96661824?v=4" width="80;" alt="CrazyWolf13"/>
<br />
<sub><b>Tobias</b></sub>
</a>
</td>
<td align="center">
<a href="https://github.com/Glydeon">
<img src="https://avatars.githubusercontent.com/u/121807526?v=4" width="80;" alt="Glydeon"/>
<br />
<sub><b>Byron</b></sub>
</a>
</td></tr>
<tr>
<td align="center">
<a href="https://github.com/NixyJuppie">
<img src="https://avatars.githubusercontent.com/u/138570196?v=4" width="80;" alt="NixyJuppie"/>
<br />
<sub><b>Nixy</b></sub>
</a>
</td></tr>
</table>
<!-- readme: sponsors -end -->
#### Contributors
[![Auto-generated contributors](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/CONTRIBUTORS.svg)](./docs/credits.md)
#### Stats
[![Stats](https://repobeats.axiom.co/api/embed/48546e3c768d38c450ba136e32c0992bcf58ad73.svg "Repobeats analytics image")](https://github.com/Lissy93/dashy/blob/master/docs/credits.md)
**[⬆️ Back to Top](#dashy)**
---
## Developing 🧱
> For full development documentation, see: [**Developing**](./docs/developing.md)
[![Open Project in VS Code](https://img.shields.io/badge/Open_in-VS_Code-863cfc?style=flat-square&logo=visualstudiocode)](https://open.vscode.dev/Lissy93/Dashy)
[![Open in GitPod](https://img.shields.io/badge/Open_in-GitPod-ffae33?style=flat-square&logo=gitpod)](https://gitpod.io/#github.com/lissy93/dashy.git)
[![Open in GitHub Code Spaces](https://img.shields.io/badge/Open_in-Code%20Spaces-131313?style=flat-square&logo=github)](https://github.dev/Lissy93/dashy)
Before getting started, you'll need [Git](https://git-scm.com/downloads), [Node](https://nodejs.org/en/download/) and optionally [Yarn](https://yarnpkg.com/) (run `npm i -g yarn`) installed.
To set up the development environment:
1. Get Code: `git clone https://github.com/Lissy93/dashy.git` and `cd dashy`
2. Install dependencies: `yarn`
3. Start dev server: `yarn dev`
4. Open the browser: `http://localhost:8080`
When you're ready, you can build the production app with `yarn build`, and then run it with `yarn start`
If you're new to web development, I've put together a short [list of resources](https://github.com/Lissy93/dashy/blob/master/docs/developing.md#resources-for-beginners) to help beginners get started
**Repo Status**:
[![Open PRs](https://flat.badgen.net/github/open-prs/lissy93/dashy?icon=github)](https://github.com/Lissy93/dashy/pulls)
[![Total PRs](https://flat.badgen.net/github/prs/lissy93/dashy?icon=github)](https://github.com/Lissy93/dashy/pulls?q=)
[![GitHub commit activity](https://img.shields.io/github/commit-activity/m/lissy93/dashy?style=flat-square)](https://github.com/Lissy93/dashy/commits/master)
[![Last Commit](https://flat.badgen.net/github/last-commit/lissy93/dashy?icon=github)](https://github.com/Lissy93/dashy/commits/master)
[![Contributors](https://flat.badgen.net/github/contributors/lissy93/dashy?icon=github)](https://github.com/Lissy93/dashy/graphs/contributors)
**[⬆️ Back to Top](#dashy)**
---
## Documentation 📘
> For full docs, see: **[Documentation Contents](./docs/readme.md)**
#### Running Dashy
- 💨 [Quick Start](/docs/quick-start.md) - TDLR guide on getting Dashy up and running in under 5 minutes
- 🚀 [Deployment](/docs/deployment.md) - Full guide on setting up Dashy on various different environments
- 🔧 [Configuring](/docs/configuring.md) - Complete list of all available options in the config file
- 💻 [Management](/docs/management.md) - Managing your app, updating, security, web server configuration, etc
- 🚒 [Troubleshooting](/docs/troubleshooting.md) - Common errors and problems, and how to fix them
#### Feature Docs
- 🛡️ [Authentication](/docs/authentication.md) - Guide to setting up authentication to protect your dashboard
- 🌈 [Alternate Views](/docs/alternate-views.md) - Outline of available pages / views and item opening methods
- 💾 [Backup & Restore](/docs/backup-restore.md) - Guide to backing up config with Dashy's cloud sync feature
- 🧸 [Icons](/docs/icons.md) - Outline of all available icon types for sections and items, with examples
- 🌐 [Multi-Language Support](/docs/multi-language-support.md) - Switching languages, and adding a new locales
- 🚦 [Status Indicators](/docs/status-indicators.md) - Using Dashy to monitor uptime and status of your apps
- 🔍 [Searching & Shortcuts](/docs/searching.md) - Searching, launching methods + keyboard shortcuts
- 🎨 [Theming](/docs/theming.md) - Complete guide to applying, writing and modifying themes + styles
- 📊 [Widgets](/docs/widgets.md) - List of all dynamic content widgets, with usage guides and examples
#### Development and Contributing
- 🧱 [Developing](/docs/developing.md) - Running Dashy development server locally, and general workflow
- 🛎️ [Development Guides](/docs/development-guides.md) - Common development tasks, to help new contributors
- 💖 [Contributing](/docs/contributing.md) - How to contribute to Dashy
- 🌟 [Showcase](/docs/showcase.md) - See how others are using Dashy, and share your dashboard
- 🏆 [Credits](/docs/credits.md) - Shout out to the amazing people who have contributed so far
- 🗞️ [Release Workflow](/docs/release-workflow.md) - Info about releases, CI and automated tasks
#### Misc
- 🔐 [Privacy & Security](/docs/privacy.md) - List of requests, potential issues, and security resources
- 📄 [License](/LICENSE) - Copy of the MIT License
- ⚖️ [Legal](/.github/LEGAL.md) - Licenses of direct dependencies
- 📏 [Code of Conduct](/.github/CODE_OF_CONDUCT.md) - Contributor Covenant Code of Conduct
- 🌳 [Changelog](/.github/CHANGELOG.md) - Details of recent changes, and historical versions
**[⬆️ Back to Top](#dashy)**
---
## Roadmap 🛣️
For upcoming features that will be released in the near future, see the [**Current Roadmap**](https://github.com/Lissy93/dashy/discussions/405)
For past updates, see the [**Changelog**](/.github/CHANGELOG.md)
**[⬆️ Back to Top](#dashy)**
---
## Alternatives 🙌
A few self-hosted web apps serve a similar purpose to Dashy. If you're looking for a dashboard, and Dashy doesn't meet your needs, I highly recommend you check these projects out!
- [Flame](https://github.com/pawelmalak/flame) by @pawelmalak (`MIT`)
- [HomeDash2](https://lamarios.github.io/Homedash2)
- [Homer](https://github.com/bastienwirtz/homer) (`Apache License 2.0`)
- [Organizr](https://organizr.app/) (`GPL-3.0 License`)
- [Heimdall](https://github.com/linuxserver/Heimdall) (`MIT`)
- [Smashing](https://github.com/Smashing/smashing) (`MIT`)
- See more 👉 [Awesome Self-Hosted](https://github.com/awesome-selfhosted/awesome-selfhosted#personal-dashboards)
**[⬆️ Back to Top](#dashy)**
---
## License 📜
Dashy is Licensed under [MIT X11](https://en.wikipedia.org/wiki/MIT_License)
```
Copyright © 2021-2022 Alicia Sykes <https://aliciasykes.com>
Permission is hereby granted, free of charge, to any person obtaining a copy of this
software and associated documentation files (the "Software"), to deal in the Software
without restriction, including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE
OR OTHER DEALINGS IN THE SOFTWARE.
Except as contained in this notice, Dashy shall not be used in advertising or otherwise
to promote the sale, use, or other dealings in this Software without prior written
authorization from the repo owner.
```
**TDLR;** _You can do whatever you like with Dashy: use it in private or commercial settings,_
_redistribute and modify it. But you must display this license and credit the author._
_There is no warranty that this app will work as expected, and the author cannot be held_
_liable for anything that goes wrong._
For more info, see TLDR Legal's [Explanation of MIT](https://tldrlegal.com/license/mit-license)
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2FLissy93%2Fdashy.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2FLissy93%2Fdashy?ref=badge_large)
**[⬆️ Back to Top](#dashy)**
---
<p align="center">
<br>
<a href="https://dashboard.trackgit.com/token/ks0bx7bb14lsvbwoc3ik">
<img src="https://us-central1-trackgit-analytics.cloudfunctions.net/token/ping/ks0bx7bb14lsvbwoc3ik?style=flat-square" />
</a>
<br><br>
<a href="https://github.com/Lissy93/dashy">
<img src="https://github.githubassets.com/images/icons/emoji/octocat.png" />
</a>
<br><br>
<i>Thank you for Visiting</i>
</p>

17
app.json Normal file
View File

@ -0,0 +1,17 @@
{
"name": "Dashy",
"website": "https://dashy.to/",
"description": "A Dashboard for your Homelab 🚀",
"repository": "https://github.com/lissy93/dashy",
"logo": "https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/logo.png",
"keywords": [
"node",
"vue",
"static",
"dashboard",
"self-hosted",
"home-lab",
"lissy93"
],
"stack": "heroku-20"
}

47
docker-compose.yml Normal file
View File

@ -0,0 +1,47 @@
---
# Welcome to Dashy! To get started, run `docker compose up -d`
# You can configure your container here, by modifying this file
version: "3.8"
services:
dashy:
container_name: Dashy
# Pull latest image from DockerHub
image: lissy93/dashy
# To build from source, replace 'image: lissy93/dashy' with 'build: .'
# build: .
# Or, to use a Dockerfile for your archtecture, uncomment the following
# context: .
# dockerfile: ./docker/Dockerfile-arm32v7
# You can also use an image with a different tag, or pull from a different registry, e.g:
# image: ghcr.io/lissy93/dashy or image: lissy93/dashy:arm64v8
# Pass in your config file below, by specifying the path on your host machine
# volumes:
# - /path/to/my-config.yml:/app/public/conf.yml
# - /path/to/item-icons:/app/public/item-icons
# Set port that web service will be served on. Keep container port as 80
ports:
- 4000:80
# Set any environmental variables
environment:
- NODE_ENV=production
# Specify your user ID and group ID. You can find this by running `id -u` and `id -g`
# - UID=1000
# - GID=1000
# Specify restart policy
restart: unless-stopped
# Configure healthchecks
healthcheck:
test: ['CMD', 'node', '/app/services/healthcheck']
interval: 1m30s
timeout: 10s
retries: 3
start_period: 40s

43
docker/Dockerfile-arm32v7 Normal file
View File

@ -0,0 +1,43 @@
FROM alpine:3.12 AS builder
# Download QEMU, see https://github.com/docker/hub-feedback/issues/1261
RUN QEMU_URL=https://github.com/balena-io/qemu/releases/download/v5.2.0%2Bbalena4/qemu-5.2.0.balena4-arm.tar.gz \
&& apk add curl && curl -L $QEMU_URL | tar zxvf - -C . --strip-components 1
# Start second (arm32v7) stage
FROM arm32v7/alpine:3.12
# Add QEMU from build stage
COPY --from=builder qemu-arm-static /usr/bin
# Install Node and Yarn
RUN apk add --update --no-cache nodejs npm yarn
# Define some ENV Vars
ENV PORT=80 \
DIRECTORY=/app \
IS_DOCKER=true
# Create and set the working directory
WORKDIR ${DIRECTORY}
# Copy over both 'package.json' and 'package-lock.json' (if available)
COPY package*.json ./
# Install project dependencies
RUN yarn
# Copy over all project files and folders to the working directory
COPY . .
# Build initial app for production
RUN yarn build
# Expose given port
EXPOSE ${PORT}
# Finally, run start command to serve up the built application
CMD [ "yarn", "build-and-start"]
# Run simple healthchecks every 5 mins, to check the Dashy's everythings great
HEALTHCHECK --interval=5m --timeout=2s --start-period=30s CMD yarn health-check

43
docker/Dockerfile-arm64v8 Normal file
View File

@ -0,0 +1,43 @@
FROM alpine:3.12 AS builder
# Download QEMU, see https://github.com/docker/hub-feedback/issues/1261
RUN QEMU_URL=https://github.com/balena-io/qemu/releases/download/v5.2.0%2Bbalena4/qemu-5.2.0.balena4-aarch64.tar.gz \
&& apk add curl && curl -L $QEMU_URL | tar zxvf - -C . --strip-components 1
# Start second (arm64v8) stage
FROM arm64v8/alpine:3.12
# Add QEMU from build stage
COPY --from=builder qemu-aarch64-static /usr/bin
# Install Node and Yarn
RUN apk add --update --no-cache nodejs npm yarn
# Define some ENV Vars
ENV PORT=80 \
DIRECTORY=/app \
IS_DOCKER=true
# Create and set the working directory
WORKDIR ${DIRECTORY}
# Copy over both 'package.json' and 'package-lock.json' (if available)
COPY package*.json ./
# Install project dependencies
RUN yarn
# Copy over all project files and folders to the working directory
COPY . .
# Build initial app for production
RUN yarn build
# Expose given port
EXPOSE ${PORT}
# Finally, run start command to serve up the built application
CMD [ "yarn", "build-and-start"]
# Run simple healthchecks every 5 mins, to check the Dashy's everythings great
HEALTHCHECK --interval=5m --timeout=2s --start-period=30s CMD yarn health-check

22
docker/Dockerfile-lite Normal file
View File

@ -0,0 +1,22 @@
# -----------------------------------------------------------------------------------------
# A light-weight alternative Docker image, using NGINX rather than Node.js to serve the app
# This means that certain features that require server-side endpoints will not be available
# -----------------------------------------------------------------------------------------
# Build Stage - Install dependencies + build the app
FROM node:lts-alpine3.14 as build
WORKDIR /dashy
COPY package*.json .
COPY yarn.lock .
RUN yarn
COPY . .
RUN yarn build
# Production Stage - Serve up built files with NGINX
FROM nginx:alpine as production
COPY ./docker/nginx.conf /etc/nginx/nginx.conf
COPY --from=build /dashy/dist /usr/share/nginx/html
EXPOSE 80
ENTRYPOINT ["nginx", "-g", "daemon off;"]
LABEL maintainer="Alicia Sykes <alicia@omg.lol>"

31
docker/Dockerfile-old Normal file
View File

@ -0,0 +1,31 @@
FROM node:lts-alpine3.14
# Define some ENV Vars
ENV PORT=80 \
DIRECTORY=/app \
IS_DOCKER=true
# Create and set the working directory
WORKDIR ${DIRECTORY}
# Copy over both 'package.json' and 'package-lock.json' (if available)
COPY package*.json ./
COPY yarn.lock ./
# Install project dependencies
RUN yarn
# Copy over all project files and folders to the working directory
COPY . .
# Build initial app for production
RUN yarn build
# Expose given port
EXPOSE ${PORT}
# Finally, run start command to serve up the built application
CMD [ "yarn", "build-and-start"]
# Run simple healthchecks every 5 mins, to check the Dashy's everythings great
HEALTHCHECK --interval=5m --timeout=2s --start-period=30s CMD yarn health-check

136
docker/docker-readme.md Normal file
View File

@ -0,0 +1,136 @@
<h1 align="center">Dashy</h1>
<p align="center">
<i>Dashy helps you organize your self-hosted services by making them accessible from a single place</i>
<br/>
<img width="120" src="https://i.ibb.co/yhbt6CY/dashy.png" />
<br/>
<b><a href="https://github.com/Lissy93/dashy/blob/master/docs/showcase.md">User Showcase</a></b> | <b><a href="https://demo.dashy.to">Live Demo</a></b> | <b><a href="https://github.com/Lissy93/dashy/blob/master/docs/quick-start.md">Getting Started</a></b> | <b><a href="https://dashy.to/docs">Documentation</a></b> | <b><a href="https://github.com/Lissy93/dashy">GitHub</a></b>
<br/><br/>
<a href="https://github.com/awesome-selfhosted/awesome-selfhosted#personal-dashboards">
<img src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg" alt="Awesome Self-Hosted">
</a>
<a href="https://github.com/Lissy93/dashy/blob/master/LICENSE">
<img src="https://img.shields.io/badge/License-MIT-0aa8d2?logo=opensourceinitiative&logoColor=fff" alt="License MIT">
</a>
<a href="https://github.com/Lissy93/dashy/blob/master/.github/CHANGELOG.md">
<img src="https://img.shields.io/github/package-json/v/lissy93/dashy?logo=azurepipelines&amp;color=0aa8d2" alt="Current Version">
</a>
<a href="https://hub.docker.com/r/lissy93/dashy">
<img src="https://img.shields.io/docker/pulls/lissy93/dashy?logo=docker&color=0aa8d2&logoColor=fff" alt="Docker Pulls">
</a>
<a href="http://as93.link/dashy-build-status">
<img src="https://badgen.net/github/status/lissy93/dashy?icon=github" alt="GitHub Status">
</a>
<a href="https://snyk.io/test/github/lissy93/dashy">
<img src="https://snyk.io/test/github/lissy93/dashy/badge.svg" alt="Known Vulnerabilities">
</a>
</p>
## Features 🌈
- 🔎 Instant search by name, domain, or tags + customizable hotkeys & keyboard shortcuts
- 🎨 Multiple built-in color themes, with UI color editor and support for custom CSS
- 🧸 Many icon options - Font-Awesome, homelab icons, auto-fetching Favicon, images, emojis, etc.
- 🚦 Status monitoring for each of your apps/links for basic availability and uptime checking
- 📊 Widgets for displaying info and dynamic content from your self-hosted services
- 💂 Optional authentication with multi-user access, configurable privileges, and SSO support
- 🌎 Multi-language support, with 10+ human-translated languages, and more on the way
- ☁ Optional, encrypted, free off-site cloud backup and restore feature available
- 💼 A workspace view, for easily switching between multiple apps simultaneously
- 🛩️ A minimal view, for use as a fast-loading browser Startpage
- 🖱️ Choose app launch method, either new tab, same tab, a pop-up modal, or in the workspace view
- 📏 Customizable layout, sizes, text, component visibility, sort order, behavior, etc.
- 🖼️ Options for a full-screen background image, custom nav-bar links, HTML footer, title, etc.
- 🚀 Easy to setup with Docker, or on bare metal, or with 1-Click cloud deployment
- ⚙️ Easy configuration, either through the UI, or using a YAML file
- ✨ Under active development with improvements and new features added regularly
- 🤏 Small bundle size, fully responsive UI, and PWA for basic offline access
- 🆓 100% free and open-source
- 🔐 Strong focus on privacy
- 🌈 And loads more...
## Demo ⚡
**Live Instances**: [Demo 1](https://demo.dashy.to) (Live Demo) ┆ [Demo 2](https://live.dashy.to) (Dashy Links) ┆ [Demo 3](https://dev.dashy.to) (Dev Preview)
**Screenshots**: Checkout the [Showcase](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md), to see example dashboards from the community
**Spin up your own demo**: [![One-Click Deploy with PWD](https://img.shields.io/badge/Play--with--Docker-Deploy-2496ed?style=flat-square&logo=docker)](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml) or [`docker run -p 8080:80 lissy93/dashy`](./docs/quick-start.md)
<p align="center">
<img width="800" src="https://i.ibb.co/L8YbNNc/dashy-demo2.gif" alt="Demo" />
</p>
**[⬆️ Back to Top](#dashy)**
---
## Getting Started 🛫
To deploy Dashy with Docker, just run `docker run -p 8080:80 lissy93/dashy`, then open `http://localhost:8080`
For full list of options and a Docker compose file, see the [Deployment Docs](https://github.com/Lissy93/dashy/blob/master/docs/deployment.md).
Dashy can also be run on bare metal using Node.js, or deployed to a cloud service, using the 1-Click deploy script.
---
## Documentation 📝
#### Running Dashy
- **[Quick Start](https://github.com/Lissy93/dashy/blob/master/docs/quick-start.md)** - TDLR guide on getting Dashy up and running
- **[Deployment](https://github.com/Lissy93/dashy/blob/master/docs/deployment.md)** - Full guide on deploying Dashy either locally or online
- **[Configuring](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md)** - Complete list of all available options in the config file
- **[App Management](https://github.com/Lissy93/dashy/blob/master/docs/management.md)** - Managing your app, updating, security, web server configuration, etc
- **[Troubleshooting](https://github.com/Lissy93/dashy/blob/master/docs/troubleshooting.md)** - Common errors and problems, and how to fix them
#### Feature Docs
- **[Authentication](https://github.com/Lissy93/dashy/blob/master/docs/authentication.md)** - Guide to setting up authentication to protect your dashboard
- **[Alternate Views](https://github.com/Lissy93/dashy/blob/master/docs/alternate-views.md)** - Outline of available pages / views and item opening methods
- **[Backup & Restore](https://github.com/Lissy93/dashy/blob/master/docs/backup-restore.md)** - Guide to backing up config with Dashy's cloud sync feature
- **[Icons](https://github.com/Lissy93/dashy/blob/master/docs/icons.md)** - Outline of all available icon types for sections and items, with examples
- **[Language Switching](https://github.com/Lissy93/dashy/blob/master/docs/multi-language-support.md)** - Details on how to switch language, or add a new locale
- **[Status Indicators](https://github.com/Lissy93/dashy/blob/master/docs/status-indicators.md)** - Using Dashy to monitor uptime and status of your apps
- **[Searching & Shortcuts](https://github.com/Lissy93/dashy/blob/master/docs/searching.md)** - Searching, launching methods + keyboard shortcuts
- **[Theming](https://github.com/Lissy93/dashy/blob/master/docs/theming.md)** - Complete guide to applying, writing and modifying themes + styles
- **[Widgets](https://github.com/Lissy93/dashy/blob/master/docs/widgets.md)** - List of all dynamic content widgets, with usage guides and examples
#### Development and Contributing
- **[Developing](https://github.com/Lissy93/dashy/blob/master/docs/developing.md)** - Running Dashy development server locally, and general workflow
- **[Development Guides](https://github.com/Lissy93/dashy/blob/master/docs/development-guides.md)** - Common development tasks, to help new contributors
- **[Contributing](https://github.com/Lissy93/dashy/blob/master/docs/contributing.md)** - How you can help keep Dashy alive
- **[Showcase](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md)** - See how others are using Dashy, and share your dashboard
- **[Credits](https://github.com/Lissy93/dashy/blob/master/docs/credits.md)** - List of people and projects that have made Dashy possible
- **[Release Workflow](https://github.com/Lissy93/dashy/blob/master/docs/release-workflow.md)** - Info about releases, CI and automated tasks
---
## License 📜
Dashy is Licensed under [MIT X11](https://en.wikipedia.org/wiki/MIT_License)
```
Copyright © 2021 Alicia Sykes <https://aliciasykes.com>
Permission is hereby granted, free of charge, to any person obtaining a copy of this
software and associated documentation files (the "Software"), to deal in the Software
without restriction, including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE
OR OTHER DEALINGS IN THE SOFTWARE.
Except as contained in this notice, Dashy shall not be used in advertising or otherwise
to promote the sale, use, or other dealings in this Software without prior written
authorization from the repo owner.
```

8
docker/hooks/pre_build Normal file
View File

@ -0,0 +1,8 @@
#!/bin/bash
# Used to setup QEMU to build arm images on amd64 processors.
# Source: https://git.io/J0ezo
# Register qemu-*-static for all supported processors except the
# current one, but also remove all registered binfmt_misc before
docker run --rm --privileged multiarch/qemu-user-static:register --reset

15
docker/nginx.conf Normal file
View File

@ -0,0 +1,15 @@
worker_processes 4;
events { worker_connections 1024; }
http {
server {
listen 80;
root /usr/share/nginx/html;
include /etc/nginx/mime.types;
location /appui {
try_files $uri /index.html;
}
}
}

64
docs/alternate-views.md Normal file
View File

@ -0,0 +1,64 @@
# Alternate Views & Opening Methods
## Views
Dashy has three different views:
- Default View - This is the main homepage with sections in a grid layout
- Workspace View - Items displayed on the side, and are launched within Dashy
- Minimal View - A clean + simple tabbed view
You can switch between views using the dropdown in the top-right corner. Set your chosen Starting View with `appConfig.startingView`. Click the page title at any time to go back to your selected starting view.
### Default
This is the main page that you will land on when you first launch the application. Here all of your sections (with items + widgets) are visible in a grid layout.
<p align="center">
<b>Example of Default View</b><br>
<img width="800" src="https://i.ibb.co/L8YbNNc/dashy-demo2.gif" alt="Demo" />
</p>
### Workspace
The workspace view displays your links in a sidebar on the left-hand side, and apps are launched inside an iframe without having to leave Dashy. This enables you to use all of your self-hosted apps from one place, and makes multi-tasking easy.
You can specify a default app to be opened when you land on the workspace, by setting `appConfig.workspaceLandingUrl: https://app-to-open/`. If this app exists within your sections.items, then the corresponding section will also be expanded.
You can also opt to keep previously opened websites/ apps open in the background, by setting `appConfig.enableMultiTasking: true`. This comes at the cost of performance, but does mean that your session with each app is preserved, enabling you to quickly switch between them.
<p align="center">
<b>Example of Workspace View</b><br>
<img alt="Workspace view demo" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/workspace-demo.gif" width="800" />
</p>
### Minimal View
The minimal view aims to be super fast and simple, and can be used as a browser startpage. Items are grouped into a tab view, and the last opened tab will be remembered. Similar to the main view, you can search and launch items just by typing, and right-clicking will show more options (like open in modal, workspace or new tab).
<p align="center">
<b>Example of Minimal View</b><br>
<img alt="Workspace view demo" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/minimal-view-demo.gif" width="800" />
</p>
## Opening Methods
Dashy supports several different ways to launch your apps. The primary opening method for each app can be specified using the `target` attribute, with a value of one of the following:
- `sametab` - The app will be launched in the current tab
- `newtab` - The app will be launched in a new tab
- `top` - Opens in the top-most browsing context, useful if you're accessing Dashy through an iframe
- `modal` - Launch app in a resizable/ movable popup modal on the current page
- `workspace` - Changes to Workspace view, and launches app
You can also set a default opening method, which will be applied to all items that don't have a specified target, using `appConfig.defaultOpeningMethod`, to one of the above values.
Even if the target is not set (or is set to `sametab`), you can still launch any given app in an alternative method. Either right-click to see all options, or use one of the keyboard shortcuts: Alt + Click will open the modal, and Ctrl + Click will open in a new tab.
<p align="center">
<img width="500" src="https://i.ibb.co/vmZdSRt/dashy-context-menu-2.png" />
</p>
If you don't like the custom context menu, it can be disabled by setting `appConfig.disableContextMenu: true`.
If you get a 'Refused to Connect' error in the modal or workspace views, then the target app has it's X-Frame-Options HTTP set to block requests from embedded content. You can easily fix this by setting this header to ALLOW, for instructions on how to do so, see the [Troubleshooting Docs](/docs/troubleshooting.md#refused-to-connect-in-modal-or-workspace-view).

345
docs/assets/CONTRIBUTORS.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 28 MiB

BIN
docs/assets/config-editor-demo.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.9 MiB

BIN
docs/assets/logo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 58 KiB

BIN
docs/assets/minimal-view-demo.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.0 MiB

1
docs/assets/repo-visualization.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 94 KiB

7
docs/assets/sponsor-button.svg Normal file
View File

@ -0,0 +1,7 @@
<svg width="223px" height="30px" version="1.1" viewBox="0 0 223 30" xmlns="http://www.w3.org/2000/svg">
<title>Artboard</title>
<desc>Created with Sketch.</desc>
<rect id="Rectangle" width="223" height="30" rx="8" fill="#ff5e5b" style="fill-rule:evenodd;fill:#ff8eff"/>
<path d="m19.011 10.912c0.57462-1.6874 1.9364-2.531 4.0853-2.531 3.2234 0 4.4184 4.0247 2.7288 6.6559-1.1264 1.7541-3.3978 3.9728-6.8141 6.6559-3.4163-2.6832-5.6877-4.9018-6.8141-6.6559-1.6896-2.6312-0.49462-6.6559 2.7288-6.6559 2.1489 0 3.5107 0.84368 4.0853 2.531z" fill="#ff5e5b" style="fill:none;stroke-width:1.5;stroke:#fff"/>
<text x="55" y="20" style="fill:#ffffff;font-family:sans-serif;font-size:16px;letter-spacing:0px;line-height:1.25;word-spacing:0px" xml:space="preserve"><tspan x="31.423412" y="20.493532" style="fill:#ffffff;font-size:16px">Sponsor me on Github</tspan></text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 879 B

BIN
docs/assets/status-check-demo.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.1 MiB

BIN
docs/assets/theme-config-demo.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.6 MiB

BIN
docs/assets/theme-slideshow.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 MiB

BIN
docs/assets/workspace-demo.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.8 MiB

362
docs/authentication.md Normal file
View File

@ -0,0 +1,362 @@
# Authentication
- [Basic Auth](#built-in-auth)
- [Setting Up Authentication](#setting-up-authentication)
- [Hash Password](#hash-password)
- [Logging In and Out](#logging-in-and-out)
- [Guest Access](#enabling-guest-access)
- [Per-User Access](#granular-access)
- [Security Considerations](#security)
- [Keycloak Auth](#keycloak)
- [Deploying Keycloak](#1-deploy-keycloak)
- [Setting up Keycloak](#2-setup-keycloak-users)
- [Configuring Dashy for Keycloak](#3-enable-keycloak-in-dashy-config-file)
- [Alternative Authentication Methods](#alternative-authentication-methods)
- [VPN](#vpn)
- [IP-Based Access](#ip-based-access)
- [Web Server Authentication](#web-server-authentication)
- [OAuth Services](#oauth-services)
- [Auth on Cloud Hosting Services](#static-site-hosting-providers)
## Built-In Auth
Dashy has a basic login page included, and frontend authentication. You can enable this by adding users to the `auth` section under `appConfig` in your `conf.yml`. If this section is not specified, then no authentication will be required to access the app, and the homepage will resolve to your dashboard.
### Setting Up Authentication
The `auth` property takes an array of users. Each user needs to include a username, hash and optional user type (`admin` or `normal`). The hash property is a [SHA-256 Hash](https://en.wikipedia.org/wiki/SHA-2) of your desired password.
For example:
```yaml
appConfig:
auth:
users:
- user: alicia
hash: 4D1E58C90B3B94BCAD9848ECCACD6D2A8C9FBC5CA913304BBA5CDEAB36FEEFA3
type: admin
- user: bob
hash: 5E884898DA28047151D0E56F8DC6292773603D0D6AABBDD62A11EF721D1542D8
```
### Hash Password
Dashy uses [SHA-256 Hash](https://en.wikipedia.org/wiki/Sha-256), a 64-character string, which you can generate using an online tool, such as [this one](https://passwordsgenerator.net/sha256-hash-generator/) or [CyberChef](https://gchq.github.io/CyberChef/) (which can be self-hosted/ ran locally).
A hash is a one-way cryptographic function, meaning that it is easy to generate a hash for a given password, but very hard to determine the original password for a given hash. This means, that so long as your password is long, strong and unique, it is safe to store its hash in the clear. Having said that, you should never reuse passwords, hashes can be cracked by iterating over known password lists, generating a hash of each.
### Logging In and Out
Once authentication is enabled, so long as there is no valid token in cookie storage, the application will redirect the user to the login page. When the user enters credentials in the login page, they will be checked, and if valid, then a token will be generated, and they can be redirected to the home page. If credentials are invalid, then an error message will be shown, and they will remain on the login page. Once in the application, to log out: the user can click the logout button (in the top-right), which will clear cookie storage, causing them to be redirected back to the login page.
### Enabling Guest Access
With authentication set up, by default no access is allowed to your dashboard without first logging in with valid credentials. Guest mode can be enabled to allow for read-only access to a secured dashboard by any user, without the need to log in. A guest user cannot write any changes to the config file, but can apply modifications locally (stored in their browser). You can enable guest access, by setting `appConfig.auth.enableGuestAccess: true`.
### Granular Access
You can use the following properties to make certain pages, sections or items only visible to some users, or hide pages, sections and items from guests.
- `hideForUsers` - Page, Section or Item will be visible to all users, except for those specified in this list
- `showForUsers` - Page, Section or Item will be hidden from all users, except for those specified in this list
- `hideForGuests` - Page, Section or Item will be visible for logged in users, but not for guests
For Example:
```yaml
pages:
- name: Home Lab
path: home-lab.yml
displayData:
showForUsers: [admin]
- name: Intranet
path: intranet.yml
displayData:
hideForGuests: true
hideForUsers: [alicia, bob]
```
```yaml
- name: Code Analysis & Monitoring
icon: fas fa-code
displayData:
cols: 2
hideForUsers: [alicia, bob]
items:
...
```
```yaml
- name: Deployment Pipelines
icon: fas fa-rocket
displayData:
hideForGuests: true
items:
- title: Hide Me
displayData:
hideForUsers: [alicia, bob]
```
### Permissions
Any user who is not an admin (with `type: admin`) will not be able to write changes to disk.
You can also prevent any user from writing changes to disk, using `preventWriteToDisk`. Or prevent any changes from being saved locally in browser storage, using `preventLocalSave`. Both properties can be found under [`appConfig`](./docs/configuring.md#appconfig-optional).
To disable all UI config features, including View Config, set `disableConfiguration`. Alternatively you can disable UI config features for all non admin users by setting `disableConfigurationForNonAdmin` to true.
### Security
With basic auth, all logic is happening on the client-side, which could mean a skilled user could manipulate the code to view parts of your configuration, including the hash. If the SHA-256 hash is of a common password, it may be possible to determine it, using a lookup table, in order to find the original password. Which can be used to manually generate the auth token, that can then be inserted into session storage, to become a valid logged in user. Therefore, you should always use a long, strong and unique password, and if you instance contains security-critical info and/ or is exposed directly to the internet, and alternative authentication method may be better. The purpose of the login page is merely to prevent immediate unauthorized access to your homepage.
**[⬆️ Back to Top](#authentication)**
---
## Keycloak
Dashy also supports using a [Keycloak](https://www.keycloak.org/) authentication server. The setup for this is a bit more involved, but it gives you greater security overall, useful for if your instance is exposed to the internet.
[Keycloak](https://www.keycloak.org/about.html) is a Java-based [open source](https://github.com/keycloak/keycloak), high-performance, secure authentication system, supported by [RedHat](https://www.redhat.com/en). It is easy to setup ([with Docker](https://quay.io/repository/keycloak/keycloak)), and enables you to secure multiple self-hosted applications with single-sign-on using standard protocols (OpenID Connect, OAuth 2.0, SAML 2.0 and social login). It's also very customizable, you can write or use custom [themes](https://wjw465150.gitbooks.io/keycloak-documentation/content/server_development/topics/themes.html), [plugins](https://www.keycloak.org/extensions.html), [password policies](https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/authentication/password-policies.html) and more.
The following guide will walk you through setting up Keycloak with Dashy. If you already have a Keycloak instance configured, then skip to Step 3.
### 1. Deploy Keycloak
First thing to do is to spin up a new instance of Keycloak. You will need [Docker installed](https://docs.docker.com/engine/install/), and can then choose a tag, and pull the container from [quay.io/keycloak/keycloak](https://quay.io/repository/keycloak/keycloak)
Use the following run command, replacing the attributes (default credentials, port and name), or incorporate this into your docker-compose file.
```bash
docker run -d \
-p 8081:8080 \
--name auth-server \
-e KEYCLOAK_USER=admin \
-e KEYCLOAK_PASSWORD=admin \
quay.io/keycloak/keycloak:15.0.2
```
If you need to pull from DockerHub, a non-official image is available [here](https://registry.hub.docker.com/r/jboss/keycloak). Or if you would prefer not to use Docker, you can also directly install Keycloak from source, following [this guide](https://www.keycloak.org/docs/latest/getting_started/index.html).
You should now be able to access the Keycloak web interface, using the port specified above (e.g. `http://127.0.0.1:8081`), login with the default credentials, and when prompted create a new password.
### 2. Setup Keycloak Users
Before we can use Keycloak, we must first set it up with some users. Keycloak uses Realms (similar to tenants) to create isolated groups of users. You must create a Realm before you will be able to add your first user.
1. Head over to the admin console
2. In the top-left corner there is a dropdown called 'Master', hover over it and then click 'Add Realm'
3. Give your realm a name, and hit 'Create'
You can now create your first user.
1. In the left-hand menu, click 'Users', then 'Add User'
2. Fill in the form, including username and hit 'Save'
3. Under the 'Credentials' tab, give the new user an initial password. They will be prompted to change this after first login
The last thing we need to do in the Keycloak admin console is to create a new client
1. Within your new realm, navigate to 'Clients' on the left-hand side, then click 'Create' in the top-right
2. Choose a 'Client ID', set 'Client Protocol' to 'openid-connect', and for 'Valid Redirect URIs' put a URL pattern to where you're hosting Dashy (if you're just testing locally, then * is fine), and do the same for the 'Web Origins' field
3. Make note of your client-id, and click 'Save'
### 3. Enable Keycloak in Dashy Config File
Now that your Keycloak instance is up and running, all that's left to do is to configure Dashy to use it. Under `appConfig`, set `auth.enableKeycloak: true`, then fill in the details in `auth.keycloak`, including: `serverUrl` - the URL where your Keycloak instance is hosted, `realm` - the name you gave your Realm, and `clientId` - the Client ID you chose.
For example:
```yaml
appConfig:
...
auth:
enableKeycloak: true
keycloak:
serverUrl: 'http://localhost:8081'
realm: 'alicia-homelab'
clientId: 'dashy'
```
Note that if you are using Keycloak V 17 or older, you will also need to set `legacySupport: true` (also under `appConfig.auth.keycloak`). This is because the API endpoint was updated in later versions.
If you use Keycloak with an external Identity Provier, you can set the `idpHint: 'alias-of-kc-idp'` option to allow the IdP Hint to be passed to Keycloak. This will cause Keycloak to skip its login page and redirect the user directly to the specified IdP's login page. Set to the value of the 'Alias' field of the desired IdP as defined in Keycloak under 'Identity Providers'.
### 4. Add groups and roles (Optional)
Keycloak allows you to assign users roles and groups. You can use these values to configure who can access various sections or items in Dashy.
Keycloak server administration and configuration is a deep topic; please refer to the [server admin guide](https://www.keycloak.org/docs/latest/server_admin/index.html#assigning-permissions-and-access-using-roles-and-groups) to see details about creating and assigning roles and groups.
Once you have groups or roles assigned to users you can configure access under each section or item `displayData.showForKeycloakUser` and `displayData.hideForKeycloakUser`.
Both show and hide configurations accept a list of `groups` and `roles` that limit access. If a users data matches one or more items in these lists they will be allowed or excluded as defined.
```yaml
sections:
- name: DeveloperResources
displayData:
showForKeycloakUsers:
roles: ['canViewDevResources']
hideForKeycloakUsers:
groups: ['ProductTeam']
items:
- title: Not Visible for developers
displayData:
hideForKeycloakUsers:
groups: ['DevelopmentTeam']
```
Depending on how you're hosting Dashy and Keycloak, you may also need to set some HTTP headers, to prevent a CORS error. This would typically be the `Access-Control-Allow-Origin [URL-of Dashy]` on your Keycloak instance. See the [Setting Headers](https://github.com/Lissy93/dashy/blob/master/docs/management.md#setting-headers) guide in the management docs for more info.
Your app is now secured :) When you load Dashy, it will redirect to your Keycloak login page, and any user without valid credentials will be prevented from accessing your dashboard.
From within the Keycloak console, you can then configure things like time-outs, password policies, etc. You can also backup your full Keycloak config, and it is recommended to do this, along with your Dashy config. You can spin up both Dashy and Keycloak simultaneously and restore both applications configs using a `docker-compose.yml` file, and this is recommended.
---
## Alternative Authentication Methods
If you are self-hosting Dashy, and require secure authentication to prevent unauthorized access, then you can either use Keycloak, or one of the following options:
- [Authentication Server](#authentication-server) - Put Dashy behind a self-hosted auth server
- [VPN](#vpn) - Use a VPN to tunnel into the network where Dashy is running
- [IP-Based Access](#ip-based-access) - Disallow access from all IP addresses, except your own
- [Web Server Authentication](#web-server-authentication) - Enable user control within your web server or proxy
- [OAuth Services](#oauth-services) - Implement a user management system using a cloud provider
- [Password Protection (for cloud providers)](#static-site-hosting-providers) - Enable password-protection on your site
### Authentication Server
#### Authelia
[Authelia](https://www.authelia.com/) is an open-source full-featured authentication server, which can be self-hosted and either on bare metal, in a Docker container or in a Kubernetes cluster. It allows for fine-grained access control rules based on IP, path, users etc, and supports 2FA, simple password access or bypass policies for your domains.
- `git clone https://github.com/authelia/authelia.git`
- `cd authelia/examples/compose/lite`
- Modify the `users_database.yml` the default username and password is authelia
- Modify the `configuration.yml` and `docker-compose.yml` with your respective domains and secrets
- `docker-compose up -d`
For more information, see the [Authelia docs](https://www.authelia.com/docs/)
### VPN
A catch-all solution to accessing services running from your home network remotely is to use a VPN. It means you do not need to worry about implementing complex authentication rules, or trusting the login implementation of individual applications. However it can be inconvenient to use on a day-to-day basis, and some public and corporate WiFi block VPN connections. Two popular VPN protocols are [OpenVPN](https://openvpn.net/) and [WireGuard](https://www.wireguard.com/)
### IP-Based Access
If you have a static IP or use a VPN to access your running services, then you can use conditional access to block access to Dashy from everyone except users of your pre-defined IP address. This feature is offered by most cloud providers, and supported by most web servers.
#### Apache
In Apache, this is configured in your `.htaccess` file in Dashy's root folder, and should look something like:
```text
Order Deny,Allow
Deny from all
Allow from [your-ip]
```
#### NGINX
In NGINX you can specify [control access](https://docs.nginx.com/nginx/admin-guide/security-controls/controlling-access-proxied-http/) rules for a given site in your `nginx.conf` or hosts file. For example:
```text
server {
listen 80;
server_name www.dashy.example.com;
location / {
root /path/to/dashy/;
passenger_enabled on;
allow [your-ip];
deny all;
}
}
```
#### Caddy
In Caddy, [Request Matchers](https://caddyserver.com/docs/caddyfile/matchers) can be used to filter requests
```text
dashy.site {
@public_networks not remote_ip [your-ip]
respond @public_networks "Access denied" 403
}
```
### Web Server Authentication
Most web servers make password protecting certain apps very easy. Note that you should also set up HTTPS and have a valid certificate in order for this to be secure.
#### Apache
First crate a `.htaccess` file in Dashy's route directory. Specify the auth type and path to where you want to store the password file (usually the same folder). For example:
```text
AuthType Basic
AuthName "Please Sign into Dashy"
AuthUserFile /path/dashy/.htpasswd
require valid-user
```
Then create a `.htpasswd` file in the same directory. List users and their hashed passwords here, with one user on each line, and a colon between username and password (e.g. `[username]:[hashed-password]`). You will need to generate an MD5 hash of your desired password, this can be done with an [online tool](https://www.web2generators.com/apache-tools/htpasswd-generator). Your file will look something like:
```text
alicia:$apr1$jv0spemw$RzOX5/GgY69JMkgV6u16l0
```
#### NGINX
NGINX has an [authentication module](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html) which can be used to add passwords to given sites, and is fairly simple to set up. Similar to above, you will need to create a `.htpasswd` file. Then just enable auth and specify the path to that file, for example:
```text
location / {
auth_basic "closed site";
auth_basic_user_file conf/htpasswd;
}
```
#### Caddy
Caddy has a [basic-auth](https://caddyserver.com/docs/caddyfile/directives/basicauth) directive, where you specify a username and hash. The password hash needs to be base-64 encoded, the [`caddy hash-password`](https://caddyserver.com/docs/command-line#caddy-hash-password) command can help with this. For example:
```text
basicauth /secret/* {
alicia JDJhJDEwJEVCNmdaNEg2Ti5iejRMYkF3MFZhZ3VtV3E1SzBWZEZ5Q3VWc0tzOEJwZE9TaFlZdEVkZDhX
}
```
For more info about implementing a single sign on for all your apps with Caddy, see [this tutorial](https://joshstrange.com/securing-your-self-hosted-apps-with-single-signon/)
#### Lighttpd
You can use the [mod_auth](https://doc.lighttpd.net/lighttpd2/mod_auth.html) module to secure your site with Lighttpd. Like with Apache, you need to first create a password file listing your usernames and hashed passwords, but in Lighttpd, it's usually called `.lighttpdpassword`.
Then in your `lighttpd.conf` file (usually in the `/etc/lighttpd/` directory), load in the mod_auth module, and configure it's directives. For example:
```text
server.modules += ( "mod_auth" )
auth.debug = 2
auth.backend = "plain"
auth.backend.plain.userfile = "/home/lighttpd/.lighttpdpassword"
$HTTP["host"] == "dashy.my-domain.net" {
server.document-root = "/home/lighttpd/dashy.my-domain.net/http"
server.errorlog = "/var/log/lighttpd/dashy.my-domain.net/error.log"
accesslog.filename = "/var/log/lighttpd/dashy.my-domain.net/access.log"
auth.require = (
"/docs/" => (
"method" => "basic",
"realm" => "Password protected area",
"require" => "user=alicia"
)
)
}
```
Restart your web server for changes to take effect.
### OAuth Services
There are also authentication services, such as [Ory.sh](https://www.ory.sh/), [Okta](https://developer.okta.com/), [Auth0](https://auth0.com/), [Firebase](https://firebase.google.com/docs/auth/). Implementing one of these solutions would involve some changes to the [`Auth.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/Auth.js) file, but should be fairly straightforward.
### Static Site Hosting Providers
If you are hosting Dashy on a cloud platform, you will probably find that it has built-in support for password protected access to web apps. For more info, see the relevant docs for your provider, for example: [Netlify Password Protection](https://docs.netlify.com/visitor-access/password-protection/), [Cloudflare Access](https://www.cloudflare.com/teams/access/), [AWS Cognito](https://aws.amazon.com/cognito/), [Azure Authentication](https://docs.microsoft.com/en-us/azure/app-service/scenario-secure-app-authentication-app-service) and [Vercel Password Protection](https://vercel.com/docs/platform/projects#password-protection).
**[⬆️ Back to Top](#authentication)**

111
docs/backup-restore.md Normal file
View File

@ -0,0 +1,111 @@
# Cloud Backup and Restore
Dashy has a built-in feature for securely backing up your config to a hosted cloud service, and then restoring it on another instance. This feature is totally optional, and if you do not enable it, then Dashy will not make any external network requests.
This is useful not only for backing up your configuration off-site, but it also enables Dashy to be used without having write a YAML config file, and makes it possible to use a public hosted instance, without the need to self-host.
<p align="center">
<img src="https://i.ibb.co/p4pxSqX/dashy-backup-restore.png" width="600" />
</p>
## How it Works
All data is encrypted before being sent to the backend. In Dashy, this is done in [`CloudBackup.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/CloudBackup.js), using [crypto.js](https://github.com/brix/crypto-js)'s AES method, using the users chosen password as the key. The data is then sent to a [Cloudflare worker](https://developers.cloudflare.com/workers/learning/how-workers-works) (a platform for running serverless functions), and stored in a [KV](https://developers.cloudflare.com/workers/learning/how-kv-works) data store.
## Creating a Backup
Once you've got Dashy configured to your preference, open the Backup & Restore menu (click the Cloud icon in the top-right corner). Here you will be prompted to choose a password, which will be used to encrypt your data. If you forget this password, there will be no way to recover your config. After clicking 'Backup' your data will be encrypted, compressed and sent to the hosted cloud service. A backup ID will be returned (in the format of xxxx-xxxx-xxxx-xxxx), this is what you use, along with your password to restore the backup on another system, so take note of it. To update a backup, return to this menu, enter your password, and click 'Update Backup'.
## Restoring a Backup
To restore a backup, navigate to the Backup & Restore menu, and under restore, enter your backup ID, and the password you chose. Your config file will be downloaded, decrypted and applied to local storage.
## Privacy & Security
Data is only ever sent to the cloud when the user actively triggers a backup. All transmitted data is first encrypted using [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard). Your selected password never leaves your device, and is hashed before being compared. It is only possible to restore a configuration if you have both the backup ID and decryption password.
Because the data is encrypted on the client-side (before being sent to the cloud), it is not possible for a man-in-the-middle, government entity, website owner, or even Cloudflare to be able read any of your data. The biggest risk to your data, would be a weak password, or a compromised system.
Having said that, although the code uses robust security libraries and is open source- it was never intended to be a security product, and has not been audited, and therefore cannot be considered totally secure - please keep that in mind.
## Fair Use Policy
Maximum of 24mb of storage per user. Please do not repeatedly hit the endpoint, as if the quota is exceeded the service may become less available to other users. Abuse may result in your IP being temporarily banned by Cloudflare.
---
## Self-Hosting the Backup Server
### Quick Start
- Install Wrangler CLI Tool: `npm i -g @cloudflare/wrangler`
- Log into Cloudflare account: `wrangler login`
- Create a new project: `wrangler generate my-project`
- Install dependencies: `cd my-project` && `npm i`
### Populate `wrangler.toml`
- Add your `account_id` (found on the right sidebar of the Workers or Overview Dashboard)
- Add your `zone_id` (found in the Overview tab of your desired domain on Cloudflare)
- Add your `route`, which should be a domain or host, supporting a wildcard
```toml
name = "dashy-worker"
type = "javascript"
workers_dev = true
route = "example.com/*"
zone_id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
account_id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
kv_namespaces = [
{ binding = "DASHY_CLOUD_BACKUP", id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
]
```
### Complete `index.js`
- Write code to handle your requests, and interact with any other data sources in this file
- Generally, this is done within an event listener for 'fetch', and returns a promise
- For Example:
```javascript
addEventListener('fetch', event => {
event.respondWith(handleRequest(event.request))
})
async function handleRequest(request) {
return new Response('Hello World!', {
headers: { 'content-type': 'text/plain' },
})
}
```
- For the code used for Dashy's cloud service, see [here](https://gist.github.com/Lissy93/d19b43d50f30e02fa25f349cf5cb5ed8#file-index-js)
### Commands
- `wrangler dev` - To start the wrangler development server
- `wrangler publish` - To publish to your cloudflare account (first run `wrangler login`)
## API
There are four endpoints, and to keep things simple, they all use the same base URL/ route.
- **`GET`** - Get config for a given user
- `backupId` - The ID of the desired encrypted object
- `subHash` - The latter half of the password hash, to verify ownership
- **`POST`** - Save a new config object, and returns `backupId`
- `userData` - The encrypted, compressed and stringified user config
- `subHash` - The latter half of the password hash, to verify ownership
- **`PUT`** - Update an existing config object
- `backupId` - The ID of the object to update
- `subHash` - Part of the hash, to verify ownership of said object
- `userData` - The new data to store
- **`DELETE`** - Delete a specified config object
- `backupId` - The ID of the object to be deleted
- `subHash` - Part of the password hash, to verify ownership of the object
For more info, see the [API Docs](https://documenter.getpostman.com/view/2142819/TzXumzce).
If you are using Postman, you may find this pre-made [collection](https://www.getpostman.com/collections/58f79ddb150223f67b35) helpful in getting things setup.

379
docs/configuring.md Normal file
View File

@ -0,0 +1,379 @@
# Configuring
All app configuration is specified in [`/public/conf.yml`](https://github.com/Lissy93/dashy/blob/master/public/conf.yml) which is in [YAML Format](https://yaml.org/) format. If you're using Docker, this file can be passed in as a volume. Changes can either be made directly to this file, or done [through the UI](#editing-config-through-the-ui). From the UI you can also export, backup, reset, validate and download your configuration file.
## There are three ways to edit the config
- **Directly in the YAML file** _(5/5 reliability, 3/5 usability)_
- Write changes directly to the conf.yml file, optionally using one of the templates provided. This can be done in your favorite editor and uploading to your server, or directly editing the file via SSH, but the easiest method would be to use [Code Server](https://github.com/coder/code-server)
- **UI JSON Editor** _(4/5 reliability, 4/5 usability)_
- From the UI, under the config menu there is a JSON editor, with built-in validation, documentation and advanced options
- **UI Visual Editor** _(3/5 reliability, 5/5 usability)_
- From the UI, enter the Interactive Edit Mode, then click any part of the page to edit. Changes are previewed live, and then saved to disk
- **REST API** _(Coming soon)_
- Programmatically edit config either through the command line, using a script or a third-party application
## Tips
- You may find it helpful to look at some sample config files to get you started, a collection of which can be found [here](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10)
- You can check that your config file fits the schema, by running `yarn validate-config`
- After modifying your config, the app needs to be recompiled, by running `yarn build` - this happens automatically if you're using Docker
- It is recommended to keep a backup of your config file. You can download it under Config menu, or use the [Cloud Backup](./docs/backup-restore.md) feature.
- You can make use of YAML features, like anchors, comments, multi-line strings, etc to reuse attributes and keep your config file readable
- Once you have finished configuring your dashboard, you can choose to [disable UI config](#preventing-changes) if you wish
- All fields are optional, unless otherwise stated.
The following file provides a reference of all supported configuration options.
## Contents
- [**`pageInfo`**](#pageinfo) - Header text, footer, title, navigation, etc
- [`navLinks`](#pageinfonavlinks-optional) - Links to display in the navigation bar
- [**`pages`**](#pages-optional) - List of additional config files, for multi-page dashboards
- [**`appConfig`**](#appconfig-optional) - Main application settings
- [`webSearch`](#appconfigwebsearch-optional) - Configure web search engine options
- [`hideComponents`](#appconfighidecomponents-optional) - Show/ hide page components
- [`auth`](#appconfigauth-optional) - Built-in authentication setup
- [`users`](#appconfigauthusers-optional) - List or users (for simple auth)
- [`keycloak`](#appconfigauthkeycloak-optional) - Auth config for Keycloak
- [**`sections`**](#section) - List of sections
- [`displayData`](#sectiondisplaydata-optional) - Section display settings
- [`show/hideForKeycloakUsers`](#sectiondisplaydatahideforkeycloakusers-sectiondisplaydatashowforkeycloakusers-itemdisplaydatahideforkeycloakusers-and-itemdisplaydatashowforkeycloakusers) - Set user controls
- [`icon`](#sectionicon-and-sectionitemicon) - Icon for a section
- [`items`](#sectionitem) - List of items
- [`icon`](#sectionicon-and-sectionitemicon) - Icon for an item
- [`displayData`](#itemdisplaydata-optional) - Item display settings
- [`show/hideForKeycloakUsers`](#sectiondisplaydatahideforkeycloakusers-sectiondisplaydatashowforkeycloakusers-itemdisplaydatahideforkeycloakusers-and-itemdisplaydatashowforkeycloakusers) - Set user controls
- [`widgets`](#sectionwidget-optional) - List of widgets
- [**Notes**](#notes)
- [Editing Config through the UI](#editing-config-through-the-ui)
- [About YAML](#about-yaml)
- [Config Saving Methods](#config-saving-methods)
- [Preventing Changes](#preventing-changes)
- [Example](#example)
---
## Top-Level Fields
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
**`pageInfo`** | `object` | Required | Basic meta data like title, description, nav bar links, footer text. See [`pageInfo`](#pageinfo)
**`appConfig`** | `object` | _Optional_ | Settings related to how the app functions, including API keys and global styles. See [`appConfig`](#appconfig-optional)
**`sections`** | `array` | Required | An array of sections, each containing an array of items, which will be displayed as links. See [`section`](#section)
**`pages`** | `array` | _Optional_ | An array additional config files, used for multi-page dashboards. See [`pages`](#pages-optional)
**[⬆️ Back to Top](#configuring)**
## `PageInfo`
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
**`title`** | `string` | Required | Your dashboard title, displayed in the header and browser tab
**`description`** | `string` | _Optional_ | Description of your dashboard, also displayed as a subtitle
**`navLinks`** | `array` | _Optional_ | Optional list of a maximum of 6 links, which will be displayed in the navigation bar. See [`navLinks`](#pageinfonavlinks-optional)
**`footerText`** | `string` | _Optional_ | Text to display in the footer (note that this will override the default footer content). This can also include HTML and inline CSS
**`logo`** | `string` | _Optional_ | The path to an image to display in the header (to the right of the title). This can be either local, where `/` is the root of `./public`, or any remote image, such as `https://i.ibb.co/yhbt6CY/dashy.png`. It's recommended to scale your image down, so that it doesn't impact load times
**[⬆️ Back to Top](#configuring)**
## `pageInfo.navLinks` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
**`title`** | `string` | Required | The text to display on the link button
**`path`** | `string` | Required | The URL to navigate to when clicked. Can be relative (e.g. `/about`) or absolute (e.g. `https://example.com` or `http://192.168.1.1`)
**`target`** | `string` | _Optional_ | The opening method (external links only). Can be either `newtab`, `sametab`, `top` or `parent`. Defaults to `newtab`
**[⬆️ Back to Top](#configuring)**
## `pages[]` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
**`name`** | `string` | Required | A unique name for that page
**`path`** | `string` | Required | The path (local or remote) to the config file to use.<br>For files located within `/public`, you only need to specify filename, for externally hosted files you must include the full URL
**[⬆️ Back to Top](#configuring)**
## `appConfig` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
**`language`** | `string` | _Optional_ | The 2 (or 4-digit) [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for your language, e.g. `en` or `en-GB`. This must be a language that the app has already been [translated](https://github.com/Lissy93/dashy/tree/master/src/assets/locales) into. If your language is unavailable, Dashy will fallback to English. By default Dashy will attempt to auto-detect your language, although this may not work on some privacy browsers.
**`startingView`** | `enum` | _Optional_ | Which page to load by default, and on the base page or domain root. You can still switch to different views from within the UI. Can be either `default`, `minimal` or `workspace`. Defaults to `default`
**`defaultOpeningMethod`** | `enum` | _Optional_ | The default opening method for items, if no `target` is specified for a given item. Can be either `newtab`, `sametab`, `modal`, `workspace`, `clipboard`, `top` or `parent`. Defaults to `newtab`
**`statusCheck`** | `boolean` | _Optional_ | When set to `true`, Dashy will ping each of your services and display their status as a dot next to each item. This can be overridden by setting `statusCheck` under each item. Defaults to `false`
**`statusCheckInterval`** | `boolean` | _Optional_ | The number of seconds between checks. If set to `0` then service will only be checked on initial page load, which is usually the desired functionality. If value is less than `10` you may experience a hit in performance. Defaults to `0`
**`webSearch`** | `object` | _Optional_ | Configuration options for the web search feature, set your default search engine, opening method or disable web search. See [`webSearch`](#appconfigwebsearch-optional)
**`backgroundImg`** | `string` | _Optional_ | Path to an optional full-screen app background image. This can be either remote (http) or local (/). Note that this will slow down initial load
**`enableFontAwesome`** | `boolean` | _Optional_ | If set to `true` font-awesome will be loaded, if set to `false` they will not be. if left blank font-awesome will be enabled only if required by 1 or more icons
**`enableMaterialDesignIcons`** | `boolean` | _Optional_ | If set to `true` mdi icons will be loaded, if set to `false` they will not be. Where `true` is enabled, if left blank material design icons will be enabled only if required by 1 or more icons
**`fontAwesomeKey`** | `string` | _Optional_ | If you have a font-awesome key, then you can use it here and make use of premium icons. It is a 10-digit alpha-numeric string from you're FA kit URL (e.g. `13014ae648`)
**`faviconApi`** | `enum` | _Optional_ | Only applicable if you are using favicons for item icons. Specifies which service to use to resolve favicons. Set to `local` to do this locally, without using an API. Services running locally will use this option always. Available options are: `local`, `faviconkit`, `iconhorse`, `google`, `clearbit`, `webmasterapi` and `allesedv`. Defaults to `faviconkit`. See [Icons](/docs/icons.md#favicons) for more info
**`auth`** | `object` | _Optional_ | All settings relating to user authentication. See [`auth`](#appconfigauth-optional)
**`defaultIcon`** | `string` | _Optional_ | An icon to be applied to any items, which don't already have an icon set. See [Icon Docs](/docs/icons.md#default-icon) for more info
**`layout`** | `enum` | _Optional_ | Layout for homepage, either `horizontal`, `vertical` or `auto`. Defaults to `auto`. This specifies the layout and direction of how sections are positioned on the home screen. This can also be modified and overridden from the UI.
**`iconSize`** | `enum` | _Optional_ | The size of link items / icons. Can be either `small`, `medium,` or `large`. Defaults to `medium`. This can also be set directly from the UI.
**`colCount`** | `number` | _Optional_ | The number of columns of sections displayed on the homepage, using the default view. Should be in integer between `1` and `8`. Note that by default this is applied responsively, based on current screen size, and specifying a value here will override this behavior, which may not be desirable.
**`theme`** | `string` | _Optional_ | The default theme for first load (you can change this later from the UI)
**`cssThemes`** | `string[]` | _Optional_ | An array of custom theme names which can be used in the theme switcher dropdown
**`customColors`** | `object`| _Optional_ | Enables you to apply a custom color palette to any given theme. Use the theme name (lowercase) as the key, for an object including key-value-pairs, with the color variable name as keys, and 6-digit hex code as value. See [Theming](/docs/theming.md#modifying-theme-colors) for more info
**`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)
**`routingMode`** | `string` | _Optional_ | Can be either `hash` or `history`. Determines the URL format for sub-pages, hash mode will look like `/#/home` whereas with history mode available you have nice clean URLs, like `/home`. For more info, see the [Vue docs](https://router.vuejs.org/guide/essentials/history-mode.html#example-server-configurations). If you're hosting Dashy with a custom BASE_URL, you will find that a bit of extra server config is necessary to get history mode working, so here you may want to instead use `hash` mode.Defaults to `history`.
**`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.
**`workspaceLandingUrl`** | `string` | _Optional_ | The URL or an app, service or website to launch when the workspace view is opened, before another service has been launched
**`preventWriteToDisk`** | `boolean` | _Optional_ | If set to `true`, users will be prevented from saving config changes to disk through the UI
**`preventLocalSave`** | `boolean` | _Optional_ | If set to `true`, users will be prevented from applying config changes to local storage
**`disableConfiguration`** | `boolean` | _Optional_ | If set to true, no users will be able to view or edit the config through the UI
**`disableConfigurationForNonAdmin`** | `boolean` | _Optional_ | If set to true, only admin users will be able to view or edit the config through the UI. disableConfiguration must not be set to true.
**`widgetsAlwaysUseProxy`** | `boolean` | _Optional_ | If set to `true`, requests made by widgets will always be proxied, same as setting `useProxy: true` on each widget. Note that this may break some widgets.
**`showSplashScreen`** | `boolean` | _Optional_ | If set to `true`, a loading screen will be shown. Defaults to `false`.
**`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.
**`disableSmartSort`** | `boolean` | _Optional_ | For the most-used and last-used app sort functions to work, a basic open-count is stored in local storage. If you do not want this to happen, then disable smart sort here, but you wil no longer be able to use these sort options. Defaults to `false`.
**`disableUpdateChecks`** | `boolean` | _Optional_ | If set to true, Dashy will not check for updates. Defaults to `false`.
**`enableServiceWorker`** | `boolean` | _Optional_ | Service workers cache web applications to improve load times and offer basic offline functionality, and are enabled by default in Dashy. The service worker can sometimes cause older content to be cached, requiring the app to be hard-refreshed. If you do not want SW functionality, or are having issues with caching, set this property to `false` to disable all service workers.
**`disableContextMenu`** | `boolean` | _Optional_ | If set to `true`, the custom right-click context menu will be disabled. Defaults to `false`.
**[⬆️ Back to Top](#configuring)**
## `appConfig.auth` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
**`users`** | `array` | _Optional_ | An array of objects containing usernames and hashed passwords. If this is not provided, then authentication will be off by default, and you will not need any credentials to access the app. See [`appConfig.auth.users`](#appconfigauthusers-optional). <br>**Note** this method of authentication is handled on the client side, so for security critical situations, it is recommended to use an [alternate authentication method](/docs/authentication.md#alternative-authentication-methods).
**`enableKeycloak`** | `boolean` | _Optional_ | If set to `true`, then authentication using Keycloak will be enabled. Note that you need to have an instance running, and have also configured `auth.keycloak`. Defaults to `false`
**`keycloak`** | `object` | _Optional_ | Config options to point Dashy to your Keycloak server. Requires `enableKeycloak: true`. See [`auth.keycloak`](#appconfigauthkeycloak-optional) for more info
**`enableGuestAccess`** | `boolean` | _Optional_ | When set to `true`, an unauthenticated user will be able to access the dashboard, with read-only access, without having to login. Requires `auth.users` to be configured. Defaults to `false`.
For more info, see the **[Authentication Docs](/docs/authentication.md)**
**[⬆️ Back to Top](#configuring)**
## `appConfig.auth.users` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
**`user`** | `string` | Required | Username to log in with
**`hash`** | `string` | Required | A SHA-256 hashed password
**`type`** | `string` | _Optional_ | The user type, either admin or normal
**[⬆️ Back to Top](#configuring)**
## `appConfig.auth.keycloak` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
**`serverUrl`** | `string` | Required | The URL (or URL/ IP + Port) where your keycloak server is running
**`realm`** | `string` | Required | The name of the realm (must already be created) that you want to use
**`clientId`** | `string` | Required | The Client ID of the client you created for use with Dashy
**`legacySupport`** | `boolean` | _Optional_ | If using Keycloak 17 or older, then set this to `true`
**[⬆️ Back to Top](#configuring)**
## `appConfig.webSearch` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
**`disableWebSearch`** | `string` | _Optional_ | Web search is enabled by default, but can be disabled by setting this property to `true`
**`searchEngine`** | `string` | _Optional_ | Set the key name for your search engine. Can also use a custom engine by setting this property to `custom`. Currently supported: `duckduckgo`, `google`, `whoogle`, `qwant`, `startpage`, `searx-bar` and `searx-info`. Defaults to `duckduckgo`
**`customSearchEngine`** | `string` | _Optional_ | You can also use a custom search engine, or your own self-hosted instance. This requires `searchEngine: custom` to be set. Then add the URL of your service, with GET query string included here
**`openingMethod`** | `string` | _Optional_ | Set your preferred opening method for search results: `newtab`, `sametab`, `workspace`. Defaults to `newtab`
**`searchBangs`** | `object` | _Optional_ | A key-value-pair set of custom search _bangs_ for redirecting query to a specific app or search engine. The key of each should be the bang you will type (typically starting with `/`, `!` or `:`), and value is the destination, either as a search engine key (e.g. `reddit`) or a URL with search parameters (e.g. `https://en.wikipedia.org/w/?search=`)
**[⬆️ Back to Top](#configuring)**
## `appConfig.hideComponents` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
**`hideHeading`** | `boolean` | _Optional_ | If set to `true`, the page title & sub-title will not be visible. Defaults to `false`
**`hideNav`** | `boolean` | _Optional_ | If set to `true`, the navigation menu will not be visible. Defaults to `false`
**`hideSearch`** | `boolean` | _Optional_ | If set to `true`, the search bar will not be visible. Defaults to `false`
**`hideSettings`** | `boolean` | _Optional_ | If set to `true`, the settings menu will be initially collapsed. Defaults to `false`
**`hideFooter`** | `boolean` | _Optional_ | If set to `true`, the footer will not be visible. Defaults to `false`
**[⬆️ Back to Top](#configuring)**
## `section`
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
**`name`** | `string` | Required | The title for the section
**`icon`** | `string` | _Optional_ | An single icon to be displayed next to the title. See [`section.icon`](#sectionicon-and-sectionitemicon)
**`items`** | `array` | _Optional_ | An array of items to be displayed within the section. See [`item`](#sectionitem). Sections must include either 1 or more items, or 1 or more widgets.
**`widgets`** | `array` | _Optional_ | An array of widgets to be displayed within the section. See [`widget`](#sectionwidget-optional)
**`displayData`** | `object` | _Optional_ | Meta-data to optionally override display settings for a given section. See [`displayData`](#sectiondisplaydata-optional)
**[⬆️ Back to Top](#configuring)**
## `section.item`
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
**`title`** | `string` | Required | The text to display/ title of a given item. Max length `18`
**`description`** | `string` | _Optional_ | Additional info about an item, which is shown in the tooltip on hover, or visible on large tiles
**`url`** | `string` | Required | The URL / location of web address for when the item is clicked
**`icon`** | `string` | _Optional_ | The icon for a given item. Can be a font-awesome icon, favicon, remote URL or local URL. See [`item.icon`](#sectionicon-and-sectionitemicon)
**`target`** | `string` | _Optional_ | The opening method for when the item is clicked, either `newtab`, `sametab`, `modal`, `workspace`, `clipboard`, `top` or `parent`. Where `newtab` will open the link in a new tab, `sametab` will open it in the current tab, and `modal` will open a pop-up modal, `workspace` will open in the Workspace view and `clipboard` will copy the URL to system clipboard (but not launch app). Defaults to `newtab`
**`hotkey`** | `number` | _Optional_ | Give frequently opened applications a numeric hotkey, between `0 - 9`. You can then just press that key to launch that application.
**`tags`** | `string[]` | _Optional_ | A list of tags, which can be used for improved search
**`statusCheck`** | `boolean` | _Optional_ | When set to `true`, Dashy will ping the URL associated with the current service, and display its status as a dot next to the item. The value here will override `appConfig.statusCheck` so you can turn off or on checks for a given service. Defaults to `appConfig.statusCheck`, falls back to `false`
**`statusCheckUrl`** | `string` | _Optional_ | If you've enabled `statusCheck`, and want to use a different URL to what is defined under the item, then specify it here
**`statusCheckHeaders`** | `object` | _Optional_ | If you're endpoint requires any specific headers for the status checking, then define them here
**`statusCheckAllowInsecure`** | `boolean` | _Optional_ | By default, any request to insecure content will be blocked. Setting this option to `true` will disable the `rejectUnauthorized` option, enabling you to ping non-HTTPS services for the current item. Defaults to `false`
**`statusCheckAcceptCodes`** | `string` | _Optional_ | If your service's response code is anything other than 2xx, then you can opt to specify an alternative success code. E.g. if you expect your server to return 403, but still want the status indicator to be green, set this value to `403`
**`statusCheckMaxRedirects`** | `number` | _Optional_ | If your service redirects to another page, and you would like status checks to follow redirects, then specify the maximum number of redirects here. Defaults to `0` / will not follow redirects
**`color`** | `string` | _Optional_ | An optional color for the text and font-awesome icon to be displayed in. Note that this will override the current theme and so may not display well
**`backgroundColor`** | `string` | _Optional_ | An optional background fill color for the that given item. Again, this will override the current theme and so might not display well against the background
**`provider`** | `string` | _Optional_ | The name of the provider for a given service, useful for when including hosted apps. In some themes, this is visible under the item name
**`displayData`** | `object` | _Optional_ | Meta-data to optionally override display settings for a given item. See [`displayData`](#itemdisplaydata-optional)
**[⬆️ Back to Top](#configuring)**
## `item.displayData` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
**`hideForUsers`** | `string[]` | _Optional_ | Current item will be visible to all users, except for those specified in this list
**`showForUsers`** | `string[]` | _Optional_ | Current item will be hidden from all users, except for those specified in this list
**`hideForGuests`** | `boolean` | _Optional_ | Current item will be visible for logged in users, but not for guests (see `appConfig.enableGuestAccess`). Defaults to `false`
**`hideForKeycloakUsers`** | `object` | _Optional_ | Current item will be visible to all keycloak users, except for those configured via these groups and roles. See `hideForKeycloakUsers`
**`showForKeycloakUsers`** | `object` | _Optional_ | Current item will be hidden from all keycloak users, except for those configured via these groups and roles. See `showForKeycloakUsers`
**[⬆️ Back to Top](#configuring)**
## `section.widget` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
**`type`** | `string` | Required | The widget type. See [Widget Docs](/docs/widgets.md) for full list of supported widgets
**`options`** | `object` | _Optional_ | Some widgets accept either optional or required additional options. Again, see the [Widget Docs](/docs/widgets.md) for full list of options
**`updateInterval`** | `number` | _Optional_ | You can keep a widget constantly updated by specifying an update interval, in seconds. See [Continuous Updates Docs](/docs/widgets.md#continuous-updates) for more info
**`useProxy`** | `boolean` | _Optional_ | Some widgets make API requests to services that are not CORS-enabled. For these instances, you will need to route requests through a proxy, Dashy has a built in CORS-proxy, which you can use by setting this option to `true`. Defaults to `false`. See the [Proxying Requests Docs](/docs/widgets.md#proxying-requests) for more info
**`timeout`** | `number` | _Optional_ | Request timeout in milliseconds, defaults to ½ a second (`500`)
**`ignoreErrors`** | `boolean` | _Optional_ | Prevent an error message being displayed, if a network request or something else fails. Useful for false-positives
**`label`** | `string` | _Optional_ | Add custom label to a given widget. Useful for identification, if there are multiple of the same type of widget in a single section
**[⬆️ Back to Top](#configuring)**
## `section.displayData` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
**`sortBy`** | `string` | _Optional_ | The sort order for items within the current section. By default items are displayed in the order in which they are listed in within the config. The following sort options are supported: `most-used` (most opened apps first), `last-used` (the most recently used apps), `alphabetical`, `reverse-alphabetical`, `random` and `default`
**`collapsed`** | `boolean` | _Optional_ | If true, the section will be collapsed initially, and will need to be clicked to open. Useful for less regularly used, or very long sections. Defaults to `false`
**`cutToHeight`** | `boolean` | _Optional_ | By default, sections will fill available space. Set this option to true to match section height with content height
**`rows`** | `number` | _Optional_ | Height of the section, specified as the number of rows it should span vertically, e.g. `2`. Defaults to `1`. Max is `5`.
**`cols`** | `number` | _Optional_ | Width of the section, specified as the number of columns the section should span horizontally, e.g. `2`. Defaults to `1`. Max is `5`.
**`itemSize`** | `string` | _Optional_ | Specify the size for items within this group, either `small`, `medium` or `large`. Note that this will override any settings specified through the UI
**`color`** | `string` | _Optional_ | A custom accent color for the section, as a hex code or HTML color (e.g. `#fff`)
**`customStyles`** | `string` | _Optional_ | Custom CSS properties that should be applied to that section, e.g. `border: 2px dashed #ff0000;`
**`sectionLayout`** | `string` | _Optional_ | Specify which CSS layout will be used to responsively place items. Can be either `auto` (which uses flex layout), or `grid`. If `grid` is selected, then `itemCountX` and `itemCountY` may also be set. Defaults to `auto`
**`itemCountX`** | `number` | _Optional_ | The number of items to display per row / horizontally. If not set, it will be calculated automatically based on available space. Can only be set if `sectionLayout` is set to `grid`. Must be a whole number between `1` and `12`
**`itemCountY`** | `number` | _Optional_ | The number of items to display per column / vertically. If not set, it will be calculated automatically based on available space. If `itemCountX` is set, then `itemCountY` can be calculated automatically. Can only be set if `sectionLayout` is set to `grid`. Must be a whole number between `1` and `12`
**`hideForUsers`** | `string[]` | _Optional_ | Current section will be visible to all users, except for those specified in this list
**`showForUsers`** | `string[]` | _Optional_ | Current section will be hidden from all users, except for those specified in this list
**`hideForGuests`** | `boolean` | _Optional_ | Current section will be visible for logged in users, but not for guests (see `appConfig.enableGuestAccess`). Defaults to `false`
**`hideForKeycloakUsers`** | `object` | _Optional_ | Current section will be visible to all keycloak users, except for those configured via these groups and roles. See `hideForKeycloakUsers`
**`showForKeycloakUsers`** | `object` | _Optional_ | Current section will be hidden from all keycloak users, except for those configured via these groups and roles. See `showForKeycloakUsers`
**[⬆️ Back to Top](#configuring)**
## `section.icon` and `section.item.icon`
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
**`icon`** | `string` | _Optional_ | The icon for a given item or section. <br>See [Icon Docs](/docs/icons.md) for all available supported icon types, including: auto-fetched favicons, generative icons, emoji icons, home-lab service logos, font-awesome, simple-icons, material icons, and icons specified by URL
**[⬆️ Back to Top](#configuring)**
## `section.displayData.hideForKeycloakUsers`, `section.displayData.showForKeycloakUsers`, `item.displayData.hideForKeycloakUsers` and `item.displayData.showForKeycloakUsers`
**Field** | **Type** | **Required**| **Description**
--- |------------| --- | ---
**`groups`** | `string[]` | _Optional_ | Current Section or Item will be hidden or shown based on the user having any of the groups in this list
**`roles`** | `string[]` | _Optional_ | Current Section or Item will be hidden or shown based on the user having any of the roles in this list
**[⬆️ Back to Top](#configuring)**
---
## Notes
### Editing Config through the UI
Config can be modified directly through the UI, and then written to disk, or applied locally. This can be done wither with the raw config editor (introduced in V 0.6.5 / [#3](https://github.com/Lissy93/dashy/pull/3)), or the interactive editor (introduced in V 1.8.9 / [#298](https://github.com/Lissy93/dashy/pull/298)).
<p align="center">
<a href="https://ibb.co/CzkyMNb">
<b>Interactive Editor</b><br>
<img alt="Interactive Editor demo" src="https://user-images.githubusercontent.com/1862727/139543020-b0576d28-0830-476f-afc8-a815d4de6def.gif" width="600" />
</a>
<br>
<a href="https://ibb.co/zRv542H">
<b>JSON Editor</b><br>
<img alt="Config Editor demo" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/config-editor-demo.gif" width="600" />
</a>
</p>
### About YAML
If you're new to YAML, it's pretty straight-forward. The format is exactly the same as that of JSON, but instead of using curly braces, structure is denoted using whitespace. This [quick guide](https://linuxhandbook.com/yaml-basics/) should get you up to speed in a few minutes, for more advanced topics take a look at this [Wikipedia article](https://en.wikipedia.org/wiki/YAML).
### Config Saving Methods
When updating the config through the JSON editor in the UI, you have two save options: **Local** or **Write to Disk**.
- Changes saved locally will only be applied to the current user through the browser, and will not apply to other instances - you either need to use the cloud sync feature, or manually update the conf.yml file.
- On the other-hand, if you choose to write changes to disk, then your main `conf.yml` file will be updated, and changes will be applied to all users, and visible across all devices. For this functionality to work, you must be running Dashy with using the Docker container, or the Node server. A backup of your current configuration will also be saved in the same directory.
### Preventing Changes
If you have authentication set up, then any user who is not an admin (with `type: admin`) will not be able to write changes to disk.
You can also prevent changes from any user being written to disk, using `preventWriteToDisk`. Or prevent any changes from being saved locally in browser storage, using `preventLocalSave`.
To disable all UI config features, set `disableConfiguration`. Alternatively you can disable UI config features for all non Admin users by setting `disableConfigurationForNonAdmin` to true.
### Example
```yaml
---
pageInfo:
title: Home Lab
sections: # An array of sections
- name: Section 1 - Getting Started
items: # An array of items
- title: GitHub
description: Source code and documentation on GitHub
icon: fab fa-github
url: https://github.com/Lissy93/dashy
- title: Issues
description: View currently open issues, or raise a new one
icon: fas fa-bug
url: https://github.com/Lissy93/dashy/issues
- title: Demo
description: A live demo
icon: far fa-rocket
url: https://dashy-demo-1.netlify.app
- name: Section 2 - 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/
```
For more example config files, see: [this gist](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10)
If you need any help, feel free to [Raise an Issue](https://github.com/Lissy93/dashy/issues/new?assignees=Lissy93&labels=%F0%9F%A4%B7%E2%80%8D%E2%99%82%EF%B8%8F+Question&template=question.md&title=%5BQUESTION%5D) or [Start a Discussion](https://github.com/Lissy93/dashy/discussions)
Happy Configuring 🤓🔧
**[⬆️ Back to Top](#configuring)**

137
docs/contributing.md Normal file
View File

@ -0,0 +1,137 @@
# Contributing
First off, thank you for considering contributing towards Dashy! 🙌
There are several ways that you can help out, and any contributions, however small will always be very much appreciated.
You will be appropriately credited in the readme - huge thank you to [everyone who has helped](/docs/credits.md) so far 💞
## 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 :)
[![Take the Survey](https://img.shields.io/badge/Take_the-Survey-%231a86fd?style=for-the-badge&logo=buddy)](https://survey.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 (and I really love seeing how people are using Dashy). To [submit your dashboard](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md#submitting-your-dashboard), either open a PR or raise an issue.
[![Add your Dashboard to the Showcase](https://img.shields.io/badge/Add_your_Dashboard-Showcase-%238616ee?style=for-the-badge&logo=feathub&logoColor=8616ee)](https://github.com/Lissy93/dashy/issues/new?assignees=&labels=%F0%9F%92%AF+Showcase&template=showcase-addition.yml&title=%5BSHOWCASE%5D+%3Ctitle%3E)
## Make a small donation
Donations help to cover server costs, development time and caffeine ;)
Don't feel any pressure to donate anything, as Dashy and my other projects will always be 100% free, for everyone, for ever.
[![Sponsor Lissy93 on GitHub](https://img.shields.io/badge/Sponsor_on_GitHub-Lissy93-%23ff4dda?style=for-the-badge&logo=githubsponsors&logoColor=ff4dda)](https://github.com/sponsors/Lissy93)
Sponsoring will give you several perks - for $1 / £0.75 per month, you'll get a sponsor badge on your profile, be credited on the Dashy's readme, with a link to your website/ profile/ socials, get priority support, have your feature ideas implemented, plus lots more. For more info, see [@Lissy93's Sponsor Page](https://github.com/sponsors/Lissy93).
<details>
<summary>You can also send a one-off small contribution using crypto</summary>
<p>
[![Donate with BTC](https://en.cryptobadges.io/badge/big/3853bSxupMjvxEYfwGDGAaLZhTKxB2vEVC)](https://en.cryptobadges.io/donate/3853bSxupMjvxEYfwGDGAaLZhTKxB2vEVC)[![Donate with Ethereum](https://en.cryptobadges.io/badge/big/0x0fc98cBf8bea932B4470C46C0FbE1ed1f6765017)](https://en.cryptobadges.io/donate/0x0fc98cBf8bea932B4470C46C0FbE1ed1f6765017)
- **BTC**: `3853bSxupMjvxEYfwGDGAaLZhTKxB2vEVC`
- **ETH**: `0x0fc98cBf8bea932B4470C46C0FbE1ed1f6765017` / `aliciasykes.eth`
- **XMR**: `471KZdxb6N63aABR4WYwMRjTVkc1p1x7wGsUTEF7AMYzL8L94A5pCuYWkosgJQ5Ze8Y2PscVCGZFJa3hDPg6MaDq47GUm8r`
- **LTC**: `MAuck6Ea1qaNihwKfXutkR1R6BorMth86H`
- **ZEC**: `t1bw1SefijsXRDQVxC9w64XsRK8hBhtQohQ`
</p>
</details>
## Enable Anonymous Bug Reports
Bug reports 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. [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).
To enable error reporting:
```yaml
appConfig:
enableErrorReporting: true
```
All reporting is **disabled** by default, and no data will ever be sent to any external endpoint without your explicit consent. All statistics are anonymized and stored securely. For more about privacy and security, see the [Sentry Security Docs](https://sentry.io/security/).
## Add Translations
If you speak another language, then adding translations will help make Dashy available to non-native English speakers. 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).
## Submit a PR
Contributing to the code or docs is super helpful. You can fix a bug, add a new feature or improve an existing one. If you've built your own custom widget, theme or view, consider sharing it in a PR. I've written [several guides](/docs/development-guides.md) to help you get started, and the steps for setting up the development environment are outlined in the [Development Docs](/docs/developing.md). Feel free to ask if you have any questions.
## 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.
[![Raise a Bug](https://img.shields.io/badge/Raise_a-Bug-%23dc2d76?style=for-the-badge&logo=dependabot)](https://github.com/Lissy93/dashy/issues/new?assignees=lissy93&labels=%F0%9F%90%9B+Bug&template=bug.yml&title=%5BBUG%5D+%3Ctitle%3E)
## 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.
[![Join the Discussion on GitHub](https://img.shields.io/badge/Join_the-Discussion-%23ffd000?style=for-the-badge&logo=livechat)](https://github.com/Lissy93/dashy/discussions)
## 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.
[![Request a Feature on BountySource](https://img.shields.io/badge/BountySource-Dashy-%23F67909?style=for-the-badge&logo=openbugbounty)](https://www.bountysource.com/teams/dashy)
## 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 with your friends or on social platforms.
[![Share Dashy on Mastodon](https://img.shields.io/badge/Share-Mastodon-%232b90d9?style=flat-square&logo=mastodon)](https://mastodon.social/?text=Check%20out%20Dashy%2C%20the%20privacy-friendly%2C%20self-hosted%20startpage%20for%20organizing%20your%20life%3A%20https%3A%2F%2Fgithub.com%2FLissy93%2Fdashy%20-%20By%20%40lissy93%40mastodon.social)
[![Share Dashy on Reddit](https://img.shields.io/badge/Share-Reddit-%23FF5700?style=flat-square&logo=reddit)](http://www.reddit.com/submit?url=https://github.com/Lissy93/dashy&title=Dashy%20-%20The%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80)
[![Share Dashy on Twitter](https://img.shields.io/badge/Share-Twitter-%231DA1F2?style=flat-square&logo=twitter)](https://twitter.com/intent/tweet?url=https://github.com/lissy93/dashy&text=Check%20out%20Dashy%20by%20@Lissy_Sykes,%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80)
[![Share Dashy on Facebook](https://img.shields.io/badge/Share-Facebook-%234267B2?style=flat-square&logo=facebook)](https://www.facebook.com/sharer/sharer.php?u=https://github.com/lissy93/dashy)
[![Share Dashy on LinkedIn](https://img.shields.io/badge/Share-LinkedIn-%230077b5?style=flat-square&logo=linkedin)](https://www.linkedin.com/shareArticle?mini=true&url=https://github.com/lissy93/dashy)
[![Share Dashy on Pinterest](https://img.shields.io/badge/Share-Pinterest-%23E60023?style=flat-square&logo=pinterest)](https://pinterest.com/pin/create/button/?url=https://github.com/lissy93/dashy&media=https://raw.githubusercontent.com/Lissy93/dashy/master/docs/showcase/1-home-lab-material.png&description=Check%20out%20Dashy,%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80)
[![Share Dashy on VK](https://img.shields.io/badge/Share-VK-%234C75A3?style=flat-square&logo=vk)](https://vk.com/share.php?url=https%3A%2F%2Fgithub.com%2Flissy93%2Fdashy%2F&title=Check%20out%20Dashy%20-%20The%20Self-Hosted%20Dashboard%20for%20your%20Homelab%20%F0%9F%9A%80)
[![Share Dashy via Viber](https://img.shields.io/badge/Share-Viber-%238176d6?style=flat-square&logo=viber)](viber://forward?text=https%3A%2F%2Fgithub.com%2Flissy93%2Fdashy%0ACheck%20out%20Dashy%2C%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80)
[![Share Dashy via Telegram](https://img.shields.io/badge/Share-Telegram-%230088cc?style=flat-square&logo=telegram)](https://t.me/share/url?url=https%3A%2F%2Fgithub.com%2Flissy93%2Fdashy&text=Check%20out%20Dashy%2C%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80)
[![Share Dashy via Email](https://img.shields.io/badge/Share-Email-%238A90C7?style=flat-square&logo=protonmail)](mailto:info@example.com?&subject=Check%20out%20Dashy%20-%20The%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80&cc=&bcc=&body=https://github.com/lissy93/dashy)
## Star, Upvote or Leave a Review
Dashy is on the following platforms, and if you could spare a few seconds to give it an upvote or review, this will also help new users discover Dashy
[![ProductHunt](https://img.shields.io/badge/Review-ProductHunt-%23b74424?style=flat-square&logo=producthunt)](https://www.producthunt.com/posts/dashy)
[![AlternativeTo](https://img.shields.io/badge/Review-AlternativeTo-%235581a6?style=flat-square&logo=abletonlive)](https://alternativeto.net/software/dashy/about/)
[![Slant](https://img.shields.io/badge/Review-Slant-%2346a1df?style=flat-square&logo=capacitor)](https://www.slant.co/improve/topics/27783/viewpoints/1/~self-hosted-homelab-startpage~dashy)
[![Star on GitHub](https://img.shields.io/github/stars/Lissy93/Dashy?color=ba96d6&label=Star%20-%20GitHub&logo=github&style=flat-square)](https://github.com/Lissy93/dashy/stargazers)
[![Star on DockerHub](https://img.shields.io/docker/stars/lissy93/dashy?color=4cb6e0&label=Star%20-%20Docker&logo=docker&style=flat-square)](https://hub.docker.com/r/lissy93/dashy)
## Follow for More
If you've enjoyed Dashy, you can follow the me to get updates about other projects that I am working on.
[![Alicia Sykes on Twitter](https://img.shields.io/twitter/follow/Lissy_Sykes?style=social&logo=twitter)](https://twitter.com/Lissy_Sykes)
[![Alicia Sykes on GitHub](https://img.shields.io/github/followers/lissy93?label=Lissy93&style=social)](https://github.com/Lissy93)
[![Alicia Sykes on Mastodon](https://img.shields.io/mastodon/follow/1032965?domain=https%3A%2F%2Fmastodon.social)](https://mastodon.social/web/accounts/1032965)
[![Alicia Sykes on Keybase](https://img.shields.io/badge/aliciasykes--lightgrey?style=social&logo=Keybase)](https://keybase.io/aliciasykes)
[![Alicia Sykes's Website](https://img.shields.io/badge/aliciasykes.com--lightgrey?style=social&logo=Tencent%20QQ)](https://aliciasykes.com)
[![Alicia Sykes's Blog](https://img.shields.io/badge/Blog--lightgrey?style=social&logo=micro.blog)](https://notes.aliciasykes.com/)
[![Alicia Sykes's PGP](https://img.shields.io/badge/PGP--lightgrey?style=social&logo=Let%E2%80%99s%20Encrypt)](https://keybase.io/aliciasykes/pgp_keys.asc)
If you like, you could also consider [subscribing to my mailing list](https://notes.aliciasykes.com/subscribe) for occasional blog post updates.
---
### Contributors
For a full list of Dashy's contributors, see the [Credits Page](/docs/credits.md)
[![Auto-generated contributors](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/CONTRIBUTORS.svg)](/docs/credits.md)
### Star-Gazers Over Time
[![Stargazers](https://starchart.cc/Lissy93/dashy.svg)](https://seladb.github.io/StarTrack-js/#/preload?r=Lissy93,dashy)

1160
docs/credits.md Normal file
View File

File diff suppressed because it is too large Load Diff

361
docs/deployment.md Normal file
View File

@ -0,0 +1,361 @@
# Deployment
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](/docs/quick-start.md), then you can spin up a new instance of Dashy by running:
```bash
docker run -p 8080:80 lissy93/dashy
```
See [Management Docs](/docs/management.md) for info about securing, monitoring, updating, health checks, auto starting, web server configuration, etc
Once you've got Dashy up and running, you'll want to configure it with your own content, for this you can reference the [configuring docs](/docs/configuring.md).
## Deployment Methods
- [Deployment](#deployment)
- [Quick Start](#quick-start)
- [Deployment Methods](#deployment-methods)
- [Deploy with Docker](#deploy-with-docker)
- [Using Docker Compose](#using-docker-compose)
- [Unraid](#unraid)
- [Synology NAS](#synology-nas)
- [Build from Source](#build-from-source)
- [Deploy to cloud service](#deploy-to-cloud-service)
- [Netlify](#netlify)
- [Heroku](#heroku)
- [Vercel](#vercel)
- [DigitalOcean](#digitalocean)
- [Google Cloud Platform](#google-cloud-platform)
- [Platform.sh](#platformsh)
- [Render](#render)
- [Scalingo](#scalingo)
- [Play-with-Docker](#play-with-docker)
- [Surge.sh](#surgesh)
- [Easypanel](#easypanel)
- [Hosting with CDN](#hosting-with-cdn)
- [Requirements](#requirements)
- [System Requirements](#system-requirements)
- [Docker](#docker)
- [Bare Metal](#bare-metal)
- [CDN / Cloud Deploy](#cdn--cloud-deploy)
- [Browser Support](#browser-support)
---
## Deploy with Docker
**Container Info**: [
![Docker Supported Architecture](https://img.shields.io/badge/Architectures-amd64%20|%20arm32v7%20|%20arm64v8-6ba6e5)
![Docker Base Image](https://img.shields.io/badge/Base_Image-Alpine_3.14-6ba6e5)
![Docker Hosted on](https://img.shields.io/badge/Hosted_on-DockerHub-6ba6e5)
](https://hub.docker.com/r/lissy93/dashy)<br>
**Status**: [
![Docker Build Status](https://img.shields.io/docker/cloud/build/lissy93/dashy?label=Docker%20Build)
![Docker Pulls](https://img.shields.io/docker/pulls/lissy93/dashy?color=ecb2f7)
![Docker Stars](https://img.shields.io/docker/stars/lissy93/dashy?color=f7f754&label=Docker%20Stars)
![Docker Image Size](https://img.shields.io/docker/image-size/lissy93/dashy/latest?color=1eea76)
![Docker Cloud Build](https://img.shields.io/docker/cloud/automated/lissy93/dashy?color=f4a966&label=Docker%20Build)
](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.
```bash
docker run -d \
-p 8080:80 \
-v /root/my-local-conf.yml:/app/public/conf.yml \
--name my-dashboard \
--restart=always \
lissy93/dashy:latest
```
Explanation of the above options:
- `-d` Detached mode (not running in the foreground of your terminal)
- `-p` The port that should be exposed, and the port it should be mapped to in your host system `[host-port][container-port]`, leave the container port as is
- `-v` Specify volumes, to pass data from your host system to the container, in the format of `[host-path]:[container-path]`, you can use this to pass your config file, directory of assets (like icons), custom CSS or web assets (like favicon.ico, manifest.json etc)
- `--name` Give your container a human-readable name
- `--restart=always` Spin up the container when the daemon starts, or after it has been stopped
- `lissy93/dashy:latest` This last option is the image the container should be built from, you can also use a specific version or architecture type, by replacing `:latest` with one of the [tags](https://hub.docker.com/r/lissy93/dashy/tags)
For all available options, and to learn more, see the [Docker Run Docs](https://docs.docker.com/engine/reference/commandline/run/)
Dashy is also available through GHCR: `docker pull ghcr.io/lissy93/dashy:latest`
If you're deploying Dashy on a modern ARM-based board, such as a Raspberry Pi (2+), then you'll need to use one of Dashy's ARM images. Set the base image + tag to either `lissy93/dashy:arm64v8` or `lissy93/dashy:arm32v7`, depending on your system architecture. You can also use the `multi-arch` image, which should work on all system architectures.
The image defaults to `:latest`, but you can instead specify a specific version, e.g. `docker pull lissy93/dashy:release-1.5.0`
---
## Using Docker Compose
Using Docker Compose can be useful for saving your specific config in files, without having to type out a long run command each time. Save compose config as a YAML file, and then run `docker compose up -d` (optionally use the `-f` flag to specify file location, if it isn't located at `./docker-compose.yml`), `-d` is detached mode (not running in the foreground of your terminal). Compose is also useful if you are using clusters, as the format is very similar to stack files, used with Docker Swarm.
The following is a complete example of a [`docker-compose.yml`](https://github.com/Lissy93/dashy/blob/master/docker-compose.yml) for Dashy. Run it as is, or uncomment the additional options you need.
```yaml
---
version: "3.8"
services:
dashy:
# To build from source, replace 'image: lissy93/dashy' with 'build: .'
# build: .
image: lissy93/dashy
container_name: Dashy
# Pass in your config file below, by specifying the path on your host machine
# volumes:
# - /root/my-config.yml:/app/public/conf.yml
ports:
- 4000:80
# Set any environmental variables
environment:
- NODE_ENV=production
# Specify your user ID and group ID. You can find this by running `id -u` and `id -g`
# - UID=1000
# - GID=1000
# Specify restart policy
restart: unless-stopped
# Configure healthchecks
healthcheck:
test: ['CMD', 'node', '/app/services/healthcheck']
interval: 1m30s
timeout: 10s
retries: 3
start_period: 40s
```
You can use a different tag, by for example setting `image: lissy93/dashy:arm64v8`, or pull from GHCR instead by setting `image: ghcr.io/lissy93/dashy`.
If you are building from source, and would like to use one of the [other Dockerfiles](https://github.com/Lissy93/dashy/tree/master/docker), then under `services.dashy` first set `context: .`, then specify the the path to the dockerfile, e.g. `dockerfile: ./docker/Dockerfile-arm32v7`
---
## Unraid
// TODO
---
## Synology NAS
Installing dashy is really simply and fast:
1. Install Docker via Synology ```Package Center```.
2. Go to ```File Station``` and open the ```docker``` folder. Inside the docker folder, create one new folder and name it ```dashy```.
> Note: Be careful to enter only lowercase, not uppercase letters.
3. Go to Control Panel / Task Scheduler / Create / Scheduled Task / User-defined script.
4. Once you click on ```User-defined``` script a new window will open.
5. Follow the instructions below:
6. General: In the Task field type in Install dashy. Uncheck "Enabled" option. Select root User.
7. Schedule: Select Run on the following date then select "Do not repeat".
8. Task Settings: Check "Send run details by email", add your email then copy paste the code below in the Run command area. After that click OK.
```bash
docker run -d \
-p 4000:80 \
-v /volume1/docker/dashy/my-local-conf.yml:/app/public/conf.yml \
--name dashy \
--restart=always \
lissy93/dashy:latest
```
dashy should be up within 1-2min after you've started the install task procedure
---
## Build from Source
If you do not want to use Docker, you can run Dashy directly on your host system. For this, you will need both [git](https://git-scm.com/downloads) and the latest or LTS version of [Node.js](https://nodejs.org/) installed, and optionally [yarn](https://yarnpkg.com/)
1. Get Code: `git clone https://github.com/Lissy93/dashy.git` and `cd dashy`
2. Configuration: Fill in you're settings in `./public/conf.yml`
3. Install dependencies: `yarn`
4. Build: `yarn build`
5. Run: `yarn start`
---
## Deploy to cloud service
If you don't have a home server, then fear not - Dashy can be deployed to pretty much any cloud provider. The above Docker and NPM guides will work exactly the same on a VPS, but I've also setup some 1-Click deploy links for 10+ of the most common cloud providers, to make things easier. Note that if your instance is exposed to the internet, it will be your responsibility to adequately secure it.
Some hosting providers required a bit of extra configuration, which was why I've made separate branches for deploying to those services (named: [`deploy_cloudflare`](https://github.com/Lissy93/dashy/tree/deploy_cloudflare), [`deploy_digital-ocean`](https://github.com/Lissy93/dashy/tree/deploy_digital-ocean), [`deploy_platform-sh`](https://github.com/Lissy93/dashy/tree/deploy_platform-sh) and [`deploy_render`](https://github.com/Lissy93/dashy/tree/deploy_render)). If there's another cloud service which you'd like 1-click deployment to be supported for, feel free to raise an issue.
**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 available. This is because these features need endpoints provided by Dashy's local Node server. Everything else should work just the same though.
### Netlify
[![Deploy to Netlify](https://i.ibb.co/GtKMysT/deploy-netlify-button.png)](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.
To deploy Dashy to Netlify, use the following link
```text
https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy
```
### Heroku
[![Deploy to Heroku](https://i.ibb.co/GdMFzBP/deploy-heroku-button.png)](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 costs a minimum of $5 for 1,000 dyno hours per month (there are around 720 hours in a month), 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
To deploy Dashy to Heroku, use the following link
```text
https://heroku.com/deploy?template=https://github.com/Lissy93/dashy
```
### Vercel
[![Deploy with Vercel](https://i.ibb.co/mJF3R7m/deploy-vercel-button.png)](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 analyzing application performance and other metrics. Vercel is free for personal use, allows for custom domains and has very reasonable limits.
To deploy Dashy to Vercel, use the following link
```text
https://vercel.com/new/project?template=https://github.com/lissy93/dashy
```
### DigitalOcean
[![Deploy to DO](https://i.ibb.co/PFt0PkB/deploy-digital-ocean-button.png)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean&refcode=3838338e7f79)
[DigitalOcean](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.
```text
https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean
```
### Google Cloud Platform
[![Run on Google Cloud](https://i.ibb.co/LkvHttd/deploy-google-cloud-button.png)](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.
To deploy Dashy to GCP, use the following link
```text
https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git
```
### Platform.sh
[![Deploy to Platform.sh](https://i.ibb.co/nPnJgJP/deploy-platform-sh-button.png)](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
To deploy Dashy to Platform.sh, use the following link
```text
https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy
```
### Render
[![Deploy to Render](https://i.ibb.co/QXNCbxT/deploy-render-button.png)](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)
To deploy Dashy to Render, use the following link
```text
https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render
```
### Scalingo
[![Deploy on Scalingo](https://i.ibb.co/nj0KxyH/deploy-scalingo-button.png)](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.
To deploy Dashy to Scalingo, use the following link
```text
https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master
```
### Play-with-Docker
[![Try in PWD](https://i.ibb.co/SfbH7Zy/deploy-pwd-button.png)](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.
To run Dashy in PWD, use the following URL:
```text
https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml
```
### Surge.sh
![Follow instructions below](https://i.ibb.co/XkcKzKz/deploy-surge-button.png)
[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
```bash
yarn add -g surge
yarn build
surge ./dist
```
### Easypanel
[![Deploy to Easypanel](https://i.ibb.co/ZNPwQX3/deploy-easypanel-button.png)](https://easypanel.io/docs/templates/dashy)
[Easypanel](https://easypanel.io) it's a modern server control panel. You can use it to deploy Dashy on your own server.
To deploy Dashy to Easypanel, use the following link
```text
https://easypanel.io/docs/templates/dashy
```
---
## Hosting with CDN
Once Dashy has been built, it is effectively just a static web app. This means that it can be served up with pretty much any static host, CDN or web server. To host Dashy through a CDN, the steps are very similar to building from source: clone the project, cd into it, install dependencies, write your config file and build the app. Once build is complete you will have a `./dist` directory within Dashy's root, and this is the build application which is ready to be served up.
However without Dashy's node server, there are a couple of features that will be unavailable to you, including: Writing config changes to disk through the UI, triggering a rebuild through the UI and application status checks. Everything else will work fine.
---
## Requirements
### System Requirements
Dashy works well on a Raspberry Pi (tested on Pi 3 and later), but should also run well on any system.
### Docker
Initial app build causes a spike in resource usage, but once the built app is running it is fairly steady. For this reason, Dashy works best with a minimum of 1GB of memory, and 1GB of disk space.
### Bare Metal
Minimum 526mb mem, 2GB disk space.
### CDN / Cloud Deploy
No specific requirements. The built application alone (without the Node server) is very light-weight, and can be handled smoothly by pretty much any CDN or cloud deployment service (see [this list](/docs/deployment.md#deploy-to-cloud-service) or natively supported cloud providers).
If you're using your own icons, or other assets, additional disk space will be required for those resources.
### Browser Support
JavaScript is required to run Dashy.
In terms of browser support, pretty much any browser released since 2018 should render content just fine. However, for Internet Explorer, only IE11+ is supported, yet performance here is still not optimal. The recommended browser is either a Chromium-based / Webkit browser (Chrome, Brave, Vivaldi, Edge, Yandex, etc), or Firefox or one of it's forks (FF-ESR, Tor, LibreWolf, etc). Recent versions of Safari and Opera are also supported, but with limited continuous testing.
<p align="center"><img width="500" src="https://i.ibb.co/pjnmbw9/browser-compatibility.png" /></p>

380
docs/developing.md Normal file
View File

@ -0,0 +1,380 @@
# Developing
This article outlines how to get Dashy running in a development environment, and outlines the basics of the architecture.
If you're adding new features, you may want to check out the [Development Guides](./docs/development-guides.md) docs, for tutorials covering basic tasks.
- [Setting up the Development Environment](#setting-up-the-dev-environment)
- [Prerequisites](#prerequisites)
- [Running the App](#running-the-project)
- [Project Commands](#project-commands)
- [Environmental Variables](#environmental-variables)
- [Git Strategy](#git-strategy)
- [Flow](#git-flow)
- [Branches](#git-branch-naming)
- [Commit emojis](#commit-emojis)
- [PR Guidelines](#pr-guidelines)
- [Resources for Beginners](#resources-for-beginners)
- [App Info](#app-info)
- [Code Style Guide](#style-guide)
- [Application Structure](#application-structure)
- [Development Tools](#development-tools)
- [Misc / Notes](#notes)
## Setting up the Dev Environment
### Prerequisites
You will need either the latest or LTS version of **[Node.js](https://nodejs.org/)** to build and serve the application and **[Git](https://git-scm.com/downloads)** to easily fetch the code, and push any changes. If you plan on running or deploying the container, you'll also need **[Docker](https://docs.docker.com/get-docker/)**. To avoid any unexpected issues, ensure you've got at least **[NPM](https://www.npmjs.com/get-npm)** V 7.5 or **[Yarn](https://classic.yarnpkg.com/en/docs/install/#windows-stable)** 1.22 (you may find [NVM](https://github.com/nvm-sh/nvm) helpful for switching/ managing versions).
### Running the Project
1. Get Code: `git clone https://github.com/Lissy93/dashy.git`
2. Navigate into the directory: `cd dashy`
3. Install dependencies: `yarn`
4. Start dev server: `yarn dev`
Dashy should now be being served on <http://localhost:8080/>. Hot reload is enabled, so making changes to any of the files will trigger them to be rebuilt and the page refreshed.
### Project Commands
#### Basics
- **`yarn build`** - In the interest of speed, the application is pre-compiled, this means that the config file is read during build-time, and therefore the app needs to rebuilt for any new changes to take effect. Luckily this is very straight forward. Just run `yarn build` or `docker exec -it [container-id] yarn build`
- **`yarn start`** - Starts a web server, and serves up the production site from `./dist` (must run build command first)
#### Development
- **`yarn dev`** - Starts the development server with hot reloading
- **`yarn lint`** - Lints code to ensure it follows a consistent, neat style
- **`yarn test`** - Runs tests, and outputs results
#### Utils and Checks
- **`yarn validate-config`** - If you have quite a long configuration file, you may wish to check that it's all good to go, before deploying the app. This can be done with `yarn validate-config` or `docker exec -it [container-id] yarn validate-config`. Your config file needs to be in `/public/conf.yml` (or within your Docker container at `/app/public/conf.yml`). This will first check that your YAML is valid, and then validates it against Dashy's [schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js).
- **`yarn health-check`** - Checks that the application is up and running on it's specified port, and outputs current status and response times. Useful for integrating into your monitoring service, if you need to maintain high system availability
#### Alternate Start Commands
- **`yarn build-and-start`** - Builds the app, runs checks and starts the production server. Commands are run in parallel, and so is faster than running them in independently. Uses the `yarn build` and `yarn start` commands
- **`yarn build-watch`** - If you find yourself making frequent changes to your configuration, and do not want to have to keep manually rebuilding, then this option is for you. It will watch for changes to any files within the projects root, and then trigger a rebuild. Note that if you are developing new features, then `yarn dev` would be more appropriate, as it's significantly faster at recompiling (under 1 second), and has hot reloading, linting and testing integrated
- **`yarn pm2-start`** - Starts the Node server using [PM2](https://pm2.keymetrics.io/), a process manager for Node.js applications, that helps them stay alive. PM2 has some built-in basic monitoring features, and an optional [management solution](https://pm2.io/). If you are running the app on bare metal, it is recommended to use this start command
#### Notes
- If you are using NPM, replace `yarn` with `npm run`
- If you are using Docker, precede each command with `docker exec -it [container-id]`. Container ID can be found by running `docker ps`
- You can manage the app using the [Vue-CLI Service](https://cli.vuejs.org/guide/cli-service.html), with `npx vue-cli-service [command]`. Or to start the Vue Management UI, run `npx vue ui`, and open `http://localhost:8000`
### Environmental Variables
All environmental variables are optional. Currently there are not many environmental variables used, as most of the user preferences are stored under `appConfig` in the `conf.yml` file.
You can set variables either in your environment, or using the [`.env`](https://github.com/Lissy93/dashy/blob/master/.env) file.
- `NODE_ENV` - Current environment, can be either development, production or test
- `PORT` - The port to expose the running application on
- `HOST` - The host that Dashy is running on, domain or IP
- `BASE_URL` - The default base path for serving up static assets
- `VUE_APP_DOMAIN` - Usually the same as BASE_URL, but accessible in frontend
- `INTEGRITY` - Should enable SRI for build script and link resources
- `IS_DOCKER` - Computed automatically on build. Indicates if running in container
- `VUE_APP_VERSION` - Again, set automatically using package.json during build time
- `BACKUP_DIR` - Directory for conf.yml backups
### Environment Modes
You can set the environment using the `NODE_ENV` variable. By default, the correct environment should be selected based on the script you run to start the app. The following environments are supported: `production`, `development` and `test`. For more info, see [Vue CLI Environment Modes](https://cli.vuejs.org/guide/mode-and-env.html#modes).
---
## Git Strategy
### Git Flow
Like most Git repos, we are following the [Github Flow](https://guides.github.com/introduction/flow) standard.
1. Create a branch (or fork if you don'd have write access)
2. Code some awesome stuff 🧑‍💻
3. Add, commit and push your changes to your branch/ fork
4. Head over to GitHub and create a Pull Request
5. Fill in the required sections in the template, and hit submit
6. Follow up with any reviews on your code
7. Merge 🎉
### Git Branch Naming
The format of your branch name should be something similar to: `[TYPE]/[TICKET]_[TITLE]`
For example, `FEATURE/420_Awesome-feature` or `FIX/690_login-server-error`
### Commit Emojis
Using a single emoji at the start of each commit message, to indicate the type task, makes the commit ledger easier to understand, plus it looks cool.
- 🎨 `:art:` - Improve structure / format of the code.
- ⚡️ `:zap:` - Improve performance.
- 🔥 `:fire:` - Remove code or files.
- 🐛 `:bug:` - Fix a bug.
- 🚑️ `:ambulance:` - Critical hotfix
- ✨ `:sparkles:` - Introduce new features.
- 📝 `:memo:` - Add or update documentation.
- 🚀 `:rocket:` - Deploy stuff.
- 💄 `:lipstick:` - Add or update the UI and style files.
- 🎉 `:tada:` - Begin a project.
- ✅ `:white_check_mark:` - Add, update, or pass tests.
- 🔒️ `:lock:` - Fix security issues.
- 🔖 `:bookmark:` - Make a Release or Version tag.
- 🚨 `:rotating_light:` - Fix compiler / linter warnings.
- 🚧 `:construction:` - Work in progress.
- ⬆️ `:arrow_up:` - Upgrade dependencies.
- 👷 `:construction_worker:` - Add or update CI build system.
- ♻️ `:recycle:` - Refactor code.
- 🩹 `:adhesive_bandage:` - Simple fix for a non-critical issue.
- 🔧 `:wrench:` - Add or update configuration files.
- 🍱 `:bento:` - Add or update assets.
- 🗃️ `:card_file_box:` - Perform database schema related changes.
- ✏️ `:pencil2:` - Fix typos.
- 🌐 `:globe_with_meridians:` - Internationalization and translations.
For a full list of options, see [gitmoji.dev](https://gitmoji.dev/)
### PR Guidelines
Once you've made your changes, and pushed them to your fork or branch, you're ready to open a pull request!
For a pull request to be merged, it must:
- Must be backwards compatible
- The build, lint and tests (run by GH actions) must pass
- There must not be any merge conflicts
When you submit your PR, include the required info, by filling out the PR template. Including:
- A brief description of your changes
- The issue, ticket or discussion number (if applicable)
- For UI relate updates include a screenshot
- If any dependencies were added, explain why it was needed, state the cost associated, and confirm it does not introduce any security issues
- Finally, check the checkboxes, to confirm that the standards are met, and hit submit!
---
## Resources for Beginners
New to Web Development? Glad you're here! Dashy is a pretty simple app, so it should make a good candidate for your first PR. Presuming that you already have a basic knowledge of JavaScript, the following articles should point you in the right direction for getting up to speed with the technologies used in this project:
- [Open Source for Beginners](https://opensource.guide/how-to-contribute/)
- [Introduction to Vue.js](https://v3.vuejs.org/guide/introduction.html)
- [Vue.js Walkthrough](https://www.taniarascia.com/getting-started-with-vue/)
- [ES6 Features](https://github.com/lukehoban/es6features)
- [Definitive guide to SCSS](https://blog.logrocket.com/the-definitive-guide-to-scss/)
- [Complete beginners guide to Docker](https://docker-curriculum.com/)
- [Docker Classroom - Interactive Tutorials](https://training.play-with-docker.com/)
- [Quick start TypeScript guide](https://www.freecodecamp.org/news/learn-typescript-in-5-minutes-13eda868daeb/)
- [Complete TypeScript tutorial series](https://www.typescripttutorial.net/)
- [Using TypeScript with Vue.js](https://blog.logrocket.com/vue-typescript-tutorial-examples/)
- [Git cheat sheet](http://git-cheatsheet.com/)
- [Basics of using NPM](https://www.freecodecamp.org/news/what-is-npm-a-node-package-manager-tutorial-for-beginners/)
As well as Node, Git and Docker- you'll also need an IDE (e.g. [VS Code](https://code.visualstudio.com/) or [Vim](https://www.vim.org/)) and a terminal (Windows users may find [WSL](https://docs.microsoft.com/en-us/windows/wsl/) more convenient).
---
## App Info
### Style Guide
Linting is done using [ESLint](https://eslint.org/), and using the [Vue.js Styleguide](https://github.com/vuejs/eslint-config-standard), which is very similar to the [AirBnB Styleguide](https://github.com/airbnb/javascript). You can run `yarn lint` to report and fix issues. While the dev server is running, issues will be reported to the console automatically, and any lint errors will trigger the build to fail. Note that all lint checks must pass before any PR can be merged. Linting is also run as a git pre-commit hook
The most significant things to note are:
- Indentation should be done with two spaces
- Strings should use single quotes
- All statements must end in a semi-colon
- The final element in all objects must be preceded with a comma
- Maximum line length is 100
- There must be exactly one blank line between sections, before function names, and at the end of the file
- With conditionals, put else on the same line as your if block's closing brace
- All multiline blocks must use braces
- Avoid console statements in the frontend
Styleguides:
- Vue: [Vue styleguide](https://vuejs.org/v2/style-guide/)
- JavaScript: [github.com/airbnb/javascript](https://github.com/airbnb/javascript)
---
### Application Structure
#### Files in the Root: `./`
```text
╮
├── package.json # Project meta-data, dependencies and paths to scripts
├── src/ # Project front-end source code
├── server.js # A Node.js server to serve up the /dist directory
├── services/ # All server-side endpoints and utilities
├── vue.config.js # Vue.js configuration
├── Dockerfile # The blueprint for building the Docker container
├── docker-compose.yml # A Docker run command
├── .env # Location for any environmental variables
├── yarn.lock # Auto-generated list of current packages and version numbers
├── docs/ # Markdown documentation
├── README.md # Readme, basic info for getting started
├── LICENSE.md # License for use
╯
```
#### Frontend Source: `./src/`
```text
./src
├── App.vue # Vue.js starting file
├── assets # Static non-compiled assets
│ ├── fonts # .ttf font files
│ ├── locales # All app text, each language in a separate JSON file
│ ╰── interface-icons # SVG icons used in the app
├── components # All front-end Vue web components
│ ├── Charts # Charting components for dynamically displaying widget data
│ │ ├── Gauge.vue # A speed-dial style chart for showing 0 - 100 values
│ │ ╰── PercentageChart.vue # A horizontal bar for showing percentage breakdowns
│ ├── Configuration # Components relating to the user config pop-up
│ │ ├── AppInfoModal.vue # A modal showing core app info, like version, language, etc
│ │ ├── AppVersion.vue # Shows current version from package.json, compares with GitHub
│ │ ├── CloudBackupRestore.vue # Form where the user manages cloud sync options
│ │ ├── ConfigContainer.vue # Main container, wrapping all other config components
│ │ ├── CustomCss.vue # Form where the user can input custom CSS
│ │ ├── EditSiteMeta.vue # Form where the user can edit site meta data
│ │ ├── JsonEditor.vue # JSON editor, where the user can modify the main config file
│ │ ╰── RebuildApp.vue # A component allowing user to trigger a rebuild through the UI
│ ├── FormElements # Basic form elements used throughout the app
│ │ ├── Button.vue # Standard button component
│ │ ├── Radio.vue # Standard radio button input
│ │ ├── Select.vue # Standard dropdown input selector
│ │ ├── Input.vue # Standard text field input component
│ │ ╰── Toggle.vue # Standard on / off toggle switch
│ ├── InteractiveEditor # Components for the interactive UI config editor
│ │ ├── AddNewSectionLauncher # Button that launches the EditSection form, used for adding new section
│ │ ├── EditAppConfig.vue # Form for editing appConfig
│ │ ├── EditPageInfo.vue # Form for editing pageInfo
│ │ ├── EditSection.vue # Form for adding / editing sections
│ │ ├── EditItem.vue # Form for adding or editing items
│ │ ├── EditModeSaveMenu.vue # The bar at the bottom of screen in edit mode, containing save buttons
│ │ ├── EditModeTopBanner.vue # The bar at the top of screen in edit mode
│ │ ├── ExportConfigMenu.vue # Modal for viewing / exporting edited config
│ │ ├── MoveItemTo.vue # Form for moving / copying items to other sections
│ │ ╰── SaveCancelButtons.vue # Buttons visible in all the edit menus, to save or cancel changes
│ ├── LinkItems # Components for Sections and Link Items
│ │ ├── Collapsable.vue # The collapsible functionality of sections
│ │ ├── IframeModal.vue # Pop-up iframe modal, for viewing websites within the app
│ │ ├── Item.vue # Main link item, which is displayed within an item group
│ │ ├── ItemGroup.vue # Item group is a section containing icons
│ │ ├── ItemIcon.vue # The icon used by both items and sections
│ │ ├── ItemOpenMethodIcon.vue # A small icon, visible on hover, indicating opening method
│ │ ├── ItemContextMenu.vue # The right-click menu, for showing Item opening methods and info
│ │ ├── SectionContextMenu.vue # The right-click menu, for showing Section edit/ open options
│ │ ╰── StatusIndicator.vue # Traffic light dot, showing if app is online or down
│ ├── Minimal View # Components used for the startpage / minimal alternative view
│ │ ├── MinimalHeading.vue # Title part of minimal view
│ │ ├── MinimalSearch.vue # Search bar for minimal view
│ │ ╰── MinimalSection.vue # Tabbed-Item section for minimal view
│ ├── PageStrcture # Components relating the main structure of the page
│ │ ├── Footer.vue # Footer, visible at the bottom of all pages
│ │ ├── Header.vue # Header, visible at the top of pages, and includes title and nav
│ │ ├── LoadingScreen.vue # Splash screen shown on first load
│ │ ├── Nav.vue # Navigation bar, includes a list of links
│ │ ╰── PageTitle.vue # Page title and sub-title, visible within the Header
│ ├── Workspace # Components used for the multi-tasking/ Workspace view
│ │ ├── MultiTaskingWeb.vue # When multi-tasking enabled, generates new iframe
│ │ ├── SideBar.vue # The left sidebar for the workspace view
│ │ ├── SideBarItem.vue # App item for the sidebar view
│ │ ├── SideBarSection.vue # Collapsible collection of items within workspace sidebar
│ │ ├── WebContent.vue # Workspace iframe view, displays content of current app
│ │ ╰── WidgetView.vue # Workspace container for displaying widgets in main content
│ ├── Widgets # Directory contains all custom widget components
│ │ ╰── .... # Too many to list, see widget docs instead
│ ╰── Settings # Components relating to the quick-settings, in the top-right
│ ├── AuthButtons.vue # Logout button and other app info
│ ├── ConfigLauncher.vue # Icon that when clicked will launch the Configuration component
│ ├── CustomThemeMaker.vue # Color pickers for letting user build their own theme
│ ├── ItemSizeSelector.vue # Set of buttons used to set and save item size
│ ├── KeyboardShortcutInfo.vue# Small pop-up displaying the available keyboard shortcuts
│ ├── LanguageSwitcher.vue # Dropdown in a modal for changing app language
│ ├── LayoutSelector.vue # Set of buttons, letting the user select their desired layout
│ ├── SearchBar.vue # The input field in the header, used for searching the app
│ ├── SettingsContainer.vue # Container that wraps all the quick-settings components
│ ╰── ThemeSelector.vue # Drop-down menu enabling the user to select and change themes
├── main.js # Main front-end entry point
├── registerServiceWorker.js # Registers and manages service workers, for PWA apps
├── router.js # Defines all available application routes
├── styles # Directory of all globally used common SCSS styles
│ ├── color-palette.scss # All color variable names and default values
│ ├── color-themes.scss # All variable values for built-in themes
│ ├── dimensions.scss # Dimensions and sizes as variables
│ ├── global-styles.scss # Basics and style resets used globally
│ ├── media-queries.scss # Screen sizes and media queries
│ ├── style-helpers.scss # SCSS functions used for modifying values
│ ├── typography.scss # Font and text styles used globally
│ ╰── user-defined-themes.scss # Empty, put any custom styles or themes here
├── mixins # Reusable component bases, extended by other views / components
│ ├── ChartingMixin.js # Functions for rendering charts in widget components
│ ├── GlancesMixin.js # Functions for fetching system info from Glances for widgets
│ ├── HomeMixin.js # Functions for homepage, used by default, minimal and workspace views
│ ╰── WidgetMixin.js # Functions for all widgets, like data fetching, updating and error handling
├── utils # Directory of re-used helper functions
│ ├── ArrowKeyNavigation.js # Functionality for arrow-key navigation
│ ├── Auth.js # Handles all authentication related actions
│ ├── CheckSectionVisibility.js # Checks which parts of the page should be visible/ hidden based on config
│ ├── ClickOutside.js # A directive for detecting click, used to hide dropdown, modal or context menu
│ ├── ConfigHelpers.js # Helper functions for managing configuration
│ ├── CloudBackup.js # Functionality for encrypting, processing and network calls
│ ├── ConfigSchema.json # The schema, used to validate the users conf.yml file
│ ├── ConfigAccumulator.js # Central place for managing and combining config
│ ├── ConfigHelpers.json # Collection of helper functions to process config using accumulator
│ ├── ConfigValidator.js # A helper script that validates the config file against schema
│ ├── CoolConsole.js # Prints info, warning and error messages to browser console, with a cool style
│ ├── defaults.js # Global constants and their default values
│ ├── emojis.json # List of emojis with unicode and shortcode, used for emoji icon feature
│ ├── EmojiUnicodeRegex.js # Regular expression to validate emoji unicode format, for emoji icons
│ ├── ErrorHandler.js # Helper function called when an error is returned
│ ├── InitServiceWorker.js # Initializes and manages service worker, if enabled
│ ├── Search.js # Helper functions for searching/ filtering items in all views
│ ├── JsonToYaml.js # Function that parses and converts raw JSON into valid YAML
│ ├── KeycloakAuth.js # Singleton class to manage Keycloak authentication
│ ├── languages.js # Handles fetching, switching and validating languages
│ ╰── ThemeHelper.js # Function that handles the fetching and setting of user themes
╰── views # Directory of available pages, corresponding to available routes
├── Home.vue # The home page container
├── About.vue # About page
├── Login.vue # TAuthentication page
├── Minimal.vue # The minimal view
╰── Workspace.vue # The workspace view with apps in sidebar
```
#### Visualisation of Source Directory
![File Breakdown](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/repo-visualization.svg)
---
## Development Tools
### Performance - Lighthouse
The easiest method of checking performance is to use Chromium's build in auditing tool, Lighthouse. To run the test, open Developer Tools (usually F12) --> Lighthouse and click on the 'Generate Report' button at the bottom.
### Dependencies - BundlePhobia
[BundlePhobia](https://bundlephobia.com/) is a really useful app that lets you analyze the cost of adding any particular dependency to an application
---
## Notes
### Known Warnings
When running the build command, several warnings appear. These are not errors, and do not affect the security or performance of the application. They will be addressed in a future update
`WARN A new version of sass-loader is available. Please upgrade for best experience.` - Currently we're using an older version of SASS loader, since the more recent releases do not seem to be compatible with the Vue CLI's webpack configuration.
`WARN asset size limit: The following asset(s) exceed the recommended size limit (244 KiB).` - For the PWA to support Windows 10, a splash screen asset is required, and is quite large. This throws a warning, however PWA assets are not loaded until needed, so shouldn't have any impact on application performance. A similar warning is thrown for the Raleway font, and that is looking to be addressed.

473
docs/development-guides.md Normal file
View File

@ -0,0 +1,473 @@
# Development Guides
A series of short tutorials, to guide you through the most common development tasks.
Sections:
- [Creating a new theme](#creating-a-new-theme)
- [Writing Translations](#writing-translations)
- [Adding a new option in the config file](#adding-a-new-option-in-the-config-file)
- [Updating Dependencies](#updating-dependencies)
- [Writing Netlify Cloud Functions](#developing-netlify-cloud-functions)
- [Hiding Page Furniture](#hiding-page-furniture-on-certain-routes)
- [Adding / Using Environmental Variables](#adding--using-environmental-variables)
- [Building a Widget](#building-a-widget)
- [Respecting Config Permissions](#respecting-config-permissions)
## Creating a new theme
Adding a new theme is really easy. There're two things you need to do: Pass the theme name to Dashy, so that it can be added to the theme selector dropdown menu, and then write some styles!
### 1. Add Theme Name
Choose a snappy name for your theme, and add it to the `builtInThemes` array inside [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js#L27).
### 2. Write some Styles
Put your theme styles inside [`color-themes.scss`](https://github.com/Lissy93/dashy/blob/master/src/styles/color-themes.scss).
Create a new block, and make sure that `data-theme` matches the theme name you chose above. For example:
```css
html[data-theme='tiger'] {
--primary: #f58233;
--background: #0b1021;
}
```
Then you can go ahead and write your own custom CSS. Although all CSS is supported here, the best way to define your theme is by setting the CSS variables. You can find a [list of all CSS variables, here](https://github.com/Lissy93/dashy/blob/master/docs/theming.md#css-variables).
For a full guide on styling, see [Theming Docs](./theming.md).
Note that if your theme is just for yourself, and you're not submitting a PR, then you can instead just pass it under `appConfig.cssThemes` inside your config file. And then put your theme in your own stylesheet, and pass it into the Docker container - [see how](https://github.com/Lissy93/dashy/blob/master/docs/theming.md#adding-your-own-theme).
## Writing Translations
For full docs about Dashy's multi-language support, see [Multi-Language Support](./multi-language-support.md)
Dashy is using [vue-i18n](https://vue-i18n.intlify.dev/guide/) to manage multi-language support.
Adding a new language is pretty straightforward, with just three steps:
### 1. Create a new Language File
Create a new JSON file in `./src/assets/locales` name is a 2-digit [ISO-639 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for your language, E.g. for German `de.json`, French `fr.json` or Spanish `es.json` - You can find a list of all ISO codes at [iso.org](https://www.iso.org/obp/ui).
### 2. Translate
Using [`en.json`](https://github.com/Lissy93/dashy/tree/master/src/assets/locales/en.json) as an example, translate the JSON values to your language, while leaving the keys as they are. It's fine to leave out certain items, as if they're missing they will fall-back to English. If you see any attribute which include curly braces (`{xxx}`), then leave the inner value of these braces as is, as this is for variables.
```json
{
"theme-maker": {
"export-button": "Benutzerdefinierte Variablen exportieren",
"reset-button": "Stile zurücksetzen für",
"show-all-button": "Alle Variablen anzeigen",
"save-button": "Speichern",
"cancel-button": "Abbrechen",
"saved-toast": "{theme} Erfolgreich aktualisiert",
"reset-toast": "Benutzerdefinierte Farben für {theme} entfernt"
},
}
```
### 3. Add your file to the app
In [`./src/utils/languages.js`](https://github.com/Lissy93/dashy/tree/master/src/utils/languages.js), you need to do 2 small things:
First import your new translation file, do this at the top of the page.
E.g. `import de from '@/assets/locales/de.json';`
Second, add it to the array of languages, e.g:
```javascript
export const languages = [
{
name: 'English',
code: 'en',
locale: en,
flag: '🇬🇧',
},
{
name: 'German', // The name of your language
code: 'de', // The ISO code of your language
locale: de, // The name of the file you imported (no quotes)
flag: '🇩🇪', // An optional flag emoji
},
];
```
You can also add your new language to the readme file, under the [Language Switching](https://github.com/Lissy93/dashy#language-switching-) section, and optionally include your name/ username if you'd like to be credited for your work. Done!
If you are not comfortable with making pull requests, or do not want to modify the code, then feel free to instead send the translated file to me, and I can add it into the application. I will be sure to credit you appropriately.
## Adding a new option in the config file
This section is for, adding a new setting to the config file.
All of the users config is specified in `./public/conf.yml` - see [Configuring Docs](./configuring.md) for info.
It's important to first ensure that there isn't a similar option already available, the new option is definitely necessary, and most importantly that it is fully backwards compatible.
Next choose the appropriate section to place it under
- Application settings should be located under `appConfig`
- Page info (such as text and metadata) should be under `pageInfo`
- Data relating to specific sections should be under `section[n].displayData`
- Settings applied to specific items or widgets, should be under `item[n]` or `widget[n]`
For example, if your option is added under `appConfig`, you can access it within your component using the `$store`, this is typically placed in a computed property, e.g:
```javascript
computed: {
appConfig() {
return this.$store.getters.appConfig;
},
...
},
```
Then, where you want to get the users value within your component, use something like: `this.appConfig.myProperty`. If the user hasn't specified the value, Don't forget to have a fallback or default for it.
If you have a default fallback value, then this would typically be specified in the [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js) file.
You will now need to add the definition of your new attribute into the [ConfigSchema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js). This will make it available in the UI config editor, and also ensure that the config validation check doesn't fail.
For example:
```json
"fontAwesomeKey": {
"type": "string",
"pattern": "^[a-z0-9]{10}$",
"description": "API key for font-awesome",
"example": "0821c65656"
}
```
or
```json
"iconSize": {
"enum": [ "small", "medium", "large" ],
"default": "medium",
"description": "The size of each link item / icon"
}
```
Finally, add your new property to the [`configuring.md`](./configuring.md) API docs. Put it under the relevant section, and be sure to include field name, data type, a description and mention that it is optional. If your new feature needs more explanation, then you can also document it under the relevant section elsewhere in the documentation.
Checklist:
- [ ] Ensure the new attribute is actually necessary, and nothing similar already exists
- [ ] Update the [Schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js) with the parameters for your new option
- [ ] If required, set a default or fallback value (usually in [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js))
- [ ] Document the new value in [`configuring.md`](./configuring.md), and if required under the relevant section in the docs
- [ ] Ensure your changes are backwards compatible, and that nothing breaks if the attribute isn't specified
---
## Updating Dependencies
Running `yarn upgrade` will updated all dependencies based on the ranges specified in the `package.json`. The `yarn.lock` file will be updated, as will the contents of `./node_modules`, for more info, see the [yarn upgrade documentation](https://classic.yarnpkg.com/en/docs/cli/upgrade/). [`npm-check-updates`](https://github.com/raineorshine/npm-check-updates) is a useful tool to help with this.
It is important to thoroughly test after any big dependency updates.
---
## Developing Netlify Cloud Functions
When Dashy is deployed to Netlify, it is effectively running as a static app, and therefore the server-side code for the Node.js endpoints is not available. However Netlify now supports serverless cloud lambda functions, which can be used to replace most functionality.
### 1. Run Netlify Dev Server
First off all, install the Netlify CLI: `npm install netlify-cli -g`
Then, from within the root of Dashy's directory, start the server, by running: `netlify dev`
### 2. Create a lambda function
This should be saved in the [`./services/serverless-functions`](https://github.com/Lissy93/dashy/tree/master/services/serverless-functions) directory
```javascript
exports.handler = async () => ({
statusCode: 200,
body: 'Return some data here...',
});
```
### 3. Redirect the Node endpoint to the function
In the [`netlify.toml`](https://github.com/Lissy93/dashy/blob/FEATURE/serverless-functions/netlify.toml) file, add a 301 redirect, with the path to the original Node.js endpoint, and the name of your cloud function
```toml
[[redirects]]
from = "/status-check"
to = "/.netlify/functions/cloud-status-check"
status = 301
force = true
```
---
## Hiding Page Furniture on Certain Routes
For some pages (such as the login page, the minimal start page, etc) the basic page furniture, (like header, footer, nav, etc) is not needed. This section explains how you can hide furniture on a new view (step 1), or add a component that should be hidden on certain views (step 2).
### 1. Add the route name to the should hide array
In [`./src/utils/defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js), there's an array called `hideFurnitureOn`. Append the name of the route (the same as it appears in [`router.js`](https://github.com/Lissy93/dashy/blob/master/src/router.js)) here.
### 2. Add the conditional to the structural component to hide
First, import the helper function:
```javascript
import { shouldBeVisible } from '@/utils/SectionHelpers';
```
Then you can create a computed value, that calls this function, passing in the route name:
```javascript
export default {
...
computed: {
...
isVisible() {
return shouldBeVisible(this.$route.name);
},
},
};
```
Finally, in the markup of your component, just add a `v-if` statement, referencing your computed value
```vue
<header v-if="isVisible">
...
</header>
```
---
## Adding / Using Environmental Variables
All environmental variables are optional. Currently there are not many environmental variables used, as most of the user preferences are stored under `appConfig` in the `conf.yml` file.
You can set variables either in your environment, or using the [`.env`](https://github.com/Lissy93/dashy/blob/master/.env) file.
Any environmental variables used by the frontend are preceded with `VUE_APP_`. Vue will merge the contents of your `.env` file into the app in a similar way to the ['dotenv'](https://github.com/motdotla/dotenv) package, where any variables that you set on your system will always take preference over the contents of any `.env` file.
If add any new variables, ensure that there is always a fallback (define it in [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js)), so as to not cause breaking changes. Don't commit the contents of your `.env` file to git, but instead take a few moments to document what you've added under the appropriate section. Try and follow the concepts outlined in the [12 factor app](https://12factor.net/config).
---
## Building a Widget
### Step 0 - Prerequisites
If this is your first time working on Dashy, then the [Developing Docs](https://github.com/Lissy93/dashy/blob/master/docs/developing.md) instructions for project setup and running. In short, you just need to clone the project, cd into it, install dependencies (`yarn`) and then start the development server (`yarn dev`).
To build a widget, you'll also need some basic knowledge of Vue.js. The [official Vue docs](https://vuejs.org/v2/guide/) provides a good starting point, as does [this guide](https://www.taniarascia.com/getting-started-with-vue/) by Tania Rascia
If you just want to jump straight in, then [here](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e) is a complete implementation of a new example widget, or take a look at the [`XkcdComic.vue`](https://github.com/Lissy93/dashy/blob/master/src/components/Widgets/XkcdComic.vue) widget, which is pretty simple.
### Step 1 - Create Widget
Firstly, create a new `.vue` file under [`./src/components/Widgets`](https://github.com/Lissy93/dashy/tree/master/src/components/Widgets).
```vue
<template>
<div class="example-wrapper">
</div>
</template>
<script>
import axios from 'axios';
import WidgetMixin from '@/mixins/WidgetMixin';
import { widgetApiEndpoints } from '@/utils/defaults';
export default {
mixins: [WidgetMixin],
data() {
return {
results: null,
};
},
computed: {
endpoint() {
return `${widgetApiEndpoints.myApi}/something`;
},
},
methods: {
fetchData() {
this.makeRequest(this.endpoint).then(this.processData);
},
processData(data) {
// Do processing any here, and set component data
this.results = data;
},
},
};
</script>
<style scoped lang="scss">
</style>
```
All widgets extend from the [Widget](https://github.com/Lissy93/dashy/blob/master/src/mixins/WidgetMixin.js) mixin. This provides some basic functionality that is shared by all widgets. The mixin includes the following `options`, `startLoading()`, `finishLoading()`, `error()` and `update()`.
- **Getting user options: `options`**
- Any user-specific config can be accessed with `this.options.something` (where something is the data key you're accessing)
- **Loading state: `startLoading()` and `finishLoading()`**
- You can show the loader with `this.startLoading()`, then when your data request completes, hide it again with `this.finishLoading()`
- **Error handling: `error()`**
- If something goes wrong (such as API error, or missing user parameters), then call `this.error()` to show message to user
- **Updating data: `update()`**
- When the user clicks the update button, or if continuous updates are enabled, then the `update()` method within your widget will be called
### Step 2 - Adding Functionality
#### **Accessing User Options**
If your widget is going to accept any parameters from the user, then we can access these with `this.options.[parmName]`. It's best to put these as computed properties, which will enable us to check it exists, is valid, and if needed format it. For example, if we have an optional property called `count` (to determine number of results), we can do the following, and then reference it within our component with `this.count`
```javascript
computed: {
count() {
if (!this.options.count) {
return 5;
}
return this.options.count;
},
...
},
```
#### **Adding an API Endpoint**
If your widget makes a data request, then add the URL for the API endpoint to the `widgetApiEndpoints` array in [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js#L207)
```javascript
widgetApiEndpoints: {
...
exampleEndpoint: 'https://hub.dummyapis.com/ImagesList',
},
```
Then in your widget file:
```javascript
import { widgetApiEndpoints } from '@/utils/defaults';
```
For GET requests, you may need to add some parameters onto the end of the URL. We can use another computed property for this, for example:
```javascript
endpoint() {
return `${widgetApiEndpoints.exampleEndpoint}?count=${this.count}`;
},
```
#### **Making an API Request**
Axios is used for making data requests, so import it into your component: `import axios from 'axios';`
Under the `methods` block, we'll create a function called `fetchData`, here we can use Axios to make a call to our endpoint.
```javascript
fetchData() {
this.makeRequest(this.endpoint, this.headers).then(this.processData);
},
```
There are three things happening here:
- If the response completes successfully, we'll pass the results to another function that will handle them
- If there's an error, then we call `this.error()`, which will show a message to the user
- Whatever the result, once the request has completed, we call `this.finishLoading()`, which will hide the loader
#### **Processing Response**
In the above example, we call the `processData()` method with the result from the API, so we need to create that under the `methods` section. How you handle this data will vary depending on what's returned by the API, and what you want to render to the user. But however you do it, you will likely need to create a data variable to store the response, so that it can be easily displayed in the HTML.
```javascript
data() {
return {
myResults: null,
};
},
```
And then, inside your `processData()` method, you can set the value of this, with:
```javascript
`this.myResults = 'whatever'`
```
#### **Rendering Response**
Now that the results are in the correct format, and stored as data variables, we can use them within the `<template>` to render results to the user. Again, how you do this will depend on the structure of your data, and what you want to display, but at it's simplest, it might look something like this:
```vue
<p class="results">{{ myResults }}</p>
```
#### **Styling**
Styles can be written for your widget within the `<style>` block.
There are several color variables used by widgets, which extend from the base palette. Using these enables users to override colors to theme their dashboard, if they wish. The variables are: `--widget-text-color`, `--widget-background-color` and `--widget-accent-color`
```vue
<style scoped lang="scss">
p.results {
color: var(--widget-text-color);
}
</style>
```
For examples of finished widget components, see the [Widgets](https://github.com/Lissy93/dashy/tree/master/src/components/Widgets) directory. Specifically, the [`XkcdComic.vue`](https://github.com/Lissy93/dashy/blob/master/src/components/Widgets/XkcdComic.vue) widget is quite minimal, so would make a good example, as will [this example implementation](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e).
### Step 3 - Register
Next, register your new widget in [`WidgetBase.vue`](https://github.com/Lissy93/dashy/blob/master/src/components/Widgets/WidgetBase.vue). In this file, you'll need to add the following:
```javascript
const COMPAT = {
...
'example-widget': 'ExampleWidget',
};
```
Here, the `example-widget` property name will be used to identify the widget when parsing the `type` property in a configuration file. The `ExampleWidget` string is used to dynamically import the widget, and therefore must match the widget's filename as it exists in the `components/widgets` folder.
### Step 4 - Docs
Finally, add some documentation for your widget in the [Widget Docs](https://github.com/Lissy93/dashy/blob/master/docs/widgets.md), so that others know how to use it. Include the following information: Title, short description, screenshot, config options and some example YAML.
**Summary**: For a complete example of everything discussed here, see: [`3da76ce`](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e)
---
## Respecting Config Permissions
Any screen that displays part or all of the users config, must not be shown when the user has disabled viewing config.
This can be done by checking the `allowViewConfig` attribute of the `permissions` getter, in the store.
First create a new `computed` property, like:
```javascript
allowViewConfig() {
return this.$store.getters.permissions.allowViewConfig;
},
```
Then wrap the part of your UI which displays config with: `v-if="allowViewConfig"`
If required, add a message showing that the component isn't available, using the `AccessError` component. E.g.
```javascript
import AccessError from '@/components/Configuration/AccessError';
```
```vue
<AccessError v-else />
```
The `$store.getters.permissions` object also returns options for when and where config can be saved, using: `allowWriteToDisk`, and `allowSaveLocally` - both are booleans.

Some files were not shown because too many files have changed in this diff Show More