diff --git a/.github/AUTHORS.txt b/.github/AUTHORS.txt index a2df5d75..85da72a9 100644 --- a/.github/AUTHORS.txt +++ b/.github/AUTHORS.txt @@ -1,80 +1,129 @@ 0n1cOn3 <0n1cOn3@gmx.ch> - 1 commits +Alberto <3170731+albcp@users.noreply.github.com> - 1 commits Alicia - 1 commits +Artyom <32810520+AaronPorts@users.noreply.github.com> - 1 commits BRAVO68WEB - 1 commits Begin - 1 commits +Bjorn Lammers - 1 commits +Bumsoo Kim - 1 commits +BySempron - 1 commits David - 1 commits -DeepSource - 1 commits -Devin - 1 commits -Doug - 1 commits -Erwan - 1 commits +Dawid Pietrykowski - 1 commits +DeepSource Bot - 1 commits +Desmond Kyeremeh - 1 commits +Devin Buhl - 1 commits +Doug Lock - 1 commits +Dylan-Bs <35694107+Dylan-Bs@users.noreply.github.com> - 1 commits +Erwan Miran - 1 commits FormatToday <616099456@qq.com> - 1 commits -Iaroslav - 1 commits -Ishan - 1 commits -Jemy - 1 commits -Jeremy - 1 commits -Kieren - 1 commits -Leonardo - 1 commits -M - 1 commits -Markus - 1 commits +Garrett Brown - 1 commits +Ian Neal - 1 commits +Iaroslav Dronskii - 1 commits +Ishan Jain - 1 commits +Jemy SCHNEPP - 1 commits +Jeremy Chauvin - 1 commits +Kieran Eglin - 1 commits +Kieren Connell - 1 commits +Leonardo Colman Lopes - 1 commits +Luis Pabon - 1 commits +M Asenov - 1 commits +Markus Krause - 1 commits +Maxime Moreillon - 1 commits +Mert Sefa AKGUN - 1 commits +Michael - 1 commits PlusaN <61884717+PlusaN@users.noreply.github.com> - 1 commits -Prince - 1 commits -Rune - 1 commits -Ryan - 1 commits -Shreya - 1 commits +Prince Carl Velasco - 1 commits +Rune Bjørnerås - 1 commits +Ryan Turner - 1 commits +Rúben Silva - 1 commits +Sergio <15928132+BySempron@users.noreply.github.com> - 1 commits +Shreya Roy - 1 commits Singebob - 1 commits -Steffen - 1 commits -Steven - 1 commits +Smexhy - 1 commits +Steffen Schmidt - 1 commits +Steven Kast - 1 commits Xert - 1 commits +baifengheixi <98794233+baifengheixi@users.noreply.github.com> - 1 commits deepsource-io[bot] - 1 commits dr460nf1r3 - 1 commits flechaig - 1 commits +huangshaohuai - 1 commits icy-comet <50461557+icy-comet@users.noreply.github.com> - 1 commits +imlonghao - 1 commits jnach <33467747+jnach@users.noreply.github.com> - 1 commits +jrobles98 - 1 commits +kxenox - 1 commits +laker j.v - 1 commits pablomalo - 1 commits +poisonadder7 - 1 commits +rtm516 - 1 commits +soaibsafi - 1 commits +ssrangisetti <46807508+ssrangisetti@users.noreply.github.com> - 1 commits +ssrangisetti - 1 commits +sur1v - 1 commits tazboyz16 - 1 commits zcq100 - 1 commits -Alejandro - 2 commits -Alessandro - 2 commits +zcq100 - 1 commits +Ángel Fernández Sánchez - 1 commits +Alejandro Pinar Ruiz <37040888+pinarruiz@users.noreply.github.com> - 2 commits +Alessandro Del Prete - 2 commits +Alexander Mnich <56564725+a-mnich@users.noreply.github.com> - 2 commits BOZG - 2 commits -Brendan <'Lear> - 2 commits -CHAIYEON - 2 commits -Dan - 2 commits -Ruben - 2 commits +Brendan O'Leary - 2 commits +CHAIYEON CHO - 2 commits +Dan Gilbert - 2 commits +Ruben Silva - 2 commits +Thomas Dissert - 2 commits +cauterize - 2 commits +hockeymikey - 2 commits +itsmejoeeey <9375730+itsmejoeeey@users.noreply.github.com> - 2 commits k073l <21180271+k073l@users.noreply.github.com> - 2 commits liss-bot <87835202+liss-bot@users.noreply.github.com> - 2 commits patrickheeney - 2 commits -ᗪєνιη <υн> - 2 commits +root - 2 commits +rtm516 - 2 commits +ᗪєνιη ᗷυнʟ - 2 commits Alucarddelta - 3 commits +Tuzi555 - 3 commits Walkx <71191962+walkxcode@users.noreply.github.com> - 3 commits aterox - 3 commits bogyeong - 3 commits stanly0726 <37040069+stanly0726@users.noreply.github.com> - 3 commits +Andreas Violaris <48277853+aviolaris@users.noreply.github.com> - 4 commits +David Alasow - 4 commits +DimitriDR - 4 commits Lissy93 - 4 commits -Niklas - 4 commits -Rémy - 4 commits +Niklas Zabel - 4 commits +Rémy GRANDIN - 4 commits +Totto16 - 4 commits Walkx - 4 commits +Alberto Caravaca <3170731+albcp@users.noreply.github.com> - 5 commits Alicie - 5 commits -Benjamin - 5 commits +Benjamin Montgomery - 5 commits +Chris Nielsen - 5 commits UrekD - 5 commits -Erik - 6 commits +Erik Vroon - 6 commits Jammo2k5 - 6 commits -Leonardo - 6 commits +Leonardo Covarrubias - 6 commits +Magnus Sundström - 6 commits +kristian - 6 commits liss-bot - 6 commits -Kashif - 9 commits -Alejandro - 14 commits -Alicia - 16 commits +Kashif Sohail - 9 commits +Alejandro Pinar Ruiz - 14 commits +Alicia Sykes <=> - 16 commits github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> - 16 commits snyk-bot - 18 commits +Matthias Bilger - 19 commits aterox - 19 commits -EVOTk <45015615+EVOTk@users.noreply.github.com> - 22 commits -Marcell <ülö> - 24 commits -Alicia - 28 commits -repo-visualizer - 47 commits -snyk-bot - 48 commits +EVOTk <45015615+EVOTk@users.noreply.github.com> - 24 commits +Marcell Fülöp - 27 commits +Alicia Sykes - 28 commits Lissy93 - 78 commits -Alicia - 92 commits -liss-bot - 103 commits -Alicia - 188 commits -Lissy93 - 208 commits -Alicia - 440 commits -Alicia - 1488 commits \ No newline at end of file +snyk-bot - 79 commits +repo-visualizer - 90 commits +Alicia Bot <87835202+liss-bot@users.noreply.github.com> - 168 commits +liss-bot - 173 commits +Lissy93 - 210 commits +Alicia Sykes - 317 commits +Alicia Sykes - 440 commits +Alicia Sykes - 1488 commits diff --git a/.github/workflows/close-stale-issues.yml b/.github/workflows/close-stale-issues.yml index 24c9545f..2566872b 100644 --- a/.github/workflows/close-stale-issues.yml +++ b/.github/workflows/close-stale-issues.yml @@ -13,13 +13,13 @@ jobs: uses: actions/stale@v4 with: repo-token: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }} - days-before-stale: 30 + days-before-stale: 90 days-before-close: 5 operations-per-run: 30 remove-stale-when-updated: true enable-statistics: true stale-issue-message: > - This issue has gone 6 weeks without an update. To keep the ticket open, please indicate that it is still relevant in a comment below. + 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, @@ -76,4 +76,4 @@ jobs: close-issue-label: '🕸️ Inactive' close-pr-label: '🕸️ Inactive' exempt-issue-labels: '📌 Keep Open' - exempt-pr-labels: '📌 Keep Open' \ No newline at end of file + exempt-pr-labels: '📌 Keep Open' diff --git a/.github/workflows/docker-build-publish.yml b/.github/workflows/docker-build-publish.yml index 287aa910..1ab5af98 100644 --- a/.github/workflows/docker-build-publish.yml +++ b/.github/workflows/docker-build-publish.yml @@ -43,7 +43,7 @@ jobs: images: | ${{ env.DH_IMAGE }} ghcr.io/${{ env.GH_IMAGE }} - ${{ secrets.ACR_SERVER }}/${{ secrets.ACR_USERNAME }} +# ${{ 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 }} @@ -74,12 +74,12 @@ jobs: 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: 🔑 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 diff --git a/.github/workflows/generate-credits.yml b/.github/workflows/generate-credits.yml index ebb86f79..4746b732 100644 --- a/.github/workflows/generate-credits.yml +++ b/.github/workflows/generate-credits.yml @@ -42,8 +42,8 @@ jobs: runs-on: ubuntu-latest name: Inserts contributors into credits.md steps: - - name: Contribute List - Credits Page - uses: akhilmhdh/contributors-readme-action@v2.2 + - name: Contributer List - Credits Page + uses: akhilmhdh/contributors-readme-action@v2.3.6 env: GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }} with: @@ -51,6 +51,7 @@ jobs: 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 @@ -72,7 +73,7 @@ jobs: uses: actions/checkout@v2 with: fetch-depth: 0 - - uses: wow-actions/update-authors@v1 + - uses: wow-actions/update-authors@v1.1.4 with: GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN || secrets.GITHUB_TOKEN }} sort: commits diff --git a/.github/workflows/mirror.yml b/.github/workflows/mirror.yml new file mode 100644 index 00000000..3918b8a9 --- /dev/null +++ b/.github/workflows/mirror.yml @@ -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 }} diff --git a/Dockerfile b/Dockerfile index 8d7b15ed..57186aea 100644 --- a/Dockerfile +++ b/Dockerfile @@ -22,7 +22,7 @@ RUN yarn install --frozen-lockfile --network-timeout 1000000 COPY . ./ # Build initial app for production -RUN yarn build +RUN yarn build --mode production # Production stage FROM node:16.13.2-alpine @@ -35,8 +35,8 @@ ENV PORT=80 \ # Create and set the working directory WORKDIR ${DIRECTORY} -# Install tini for initialization and tzdata for setting timezone -RUN apk add --no-cache tzdata tini +# Update tzdata for setting timezone +RUN apk add --no-cache tzdata # Copy built application from build phase COPY --from=BUILD_IMAGE /app ./ @@ -44,11 +44,10 @@ COPY --from=BUILD_IMAGE /app ./ RUN rm dist/conf.yml # Finally, run start command to serve up the built application -ENTRYPOINT [ "/sbin/tini", "--" ] -CMD [ "yarn", "build-and-start" ] +CMD [ "yarn", "start" ] # Expose the port EXPOSE ${PORT} # Run simple healthchecks every 5 mins, to check that everythings still great -HEALTHCHECK --interval=5m --timeout=2s --start-period=30s CMD yarn health-check \ No newline at end of file +HEALTHCHECK --interval=5m --timeout=5s --start-period=30s CMD yarn health-check diff --git a/README.md b/README.md index 51376526..b77fce26 100644 --- a/README.md +++ b/README.md @@ -214,7 +214,7 @@ The following icon types are supported: [font-awesome]: https://fontawesome.com/icons [simple-icons]: https://simpleicons.org/ [material icons]: https://github.com/Templarian/MaterialDesign -[dashboard-icons]: https://github.com/WalkxHub/dashboard-icons +[dashboard-icons]: https://github.com/WalkxCode/dashboard-icons

@@ -400,27 +400,35 @@ All data is fully E2E encrypted before being sent to the backend (done in [`Clou ## 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)). +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)** +- 🇫🇷 **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)** -- 🇪🇸 **Spanish**: `es` - Contributed by **[@lu4t](https://github.com/lu4t)** +- 🇷🇺 **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)** -- 🇷🇺 **Russian**: `ru` -- 🇦🇪 **Arabic**: `ar` -- 🇮🇳 **Hindi**: `hi` -- 🇯🇵 **Japanese**: `ja` -- 🇰🇷 **Korean**: `ko` - Contributed by **[@boggy-cs](https://github.com/boggy-cs)** +- 🇹🇷 **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. @@ -542,12 +550,34 @@ Huge thanks to the sponsors helping to support Dashy's development! Eddy Lazzarin + + + AnandChowdhary +
+ Anand Chowdhary + + + + + davidpaulyoung +
+ David Young + + k-rol
Carol Ouellet + + + + + bile0026 +
+ Zach Biles + @@ -556,21 +586,6 @@ Huge thanks to the sponsors helping to support Dashy's development! Ulises Gascón - - - BOZG -
- Stephen Rigney - - - - - - AdamXweb -
- Adam Kostarelas - - bmcgonag @@ -578,61 +593,25 @@ Huge thanks to the sponsors helping to support Dashy's development! Brian McGonagill - - - Robert-Ernst -
- Robert Ernst - - - vlad-timofeev + vlad-timofeev
Vlad Timofeev - - mDafox + + iJasonWade
- Manu Devos + Jason Ash - - Byolock + + DRXAquosus
- Byolock - - - - - - PAPAMICA -
- Mickael Asseline - - - - - hugalafutro -
- Hugalafutro - - - - - shadowking001 -
- LawrenceP. - - - - - KierenConnell -
- Kieren Connell + DRXAquosus @@ -641,13 +620,6 @@ Huge thanks to the sponsors helping to support Dashy's development!
Ratty222 - - - - undefined -
- Undefined - @@ -656,13 +628,6 @@ Huge thanks to the sponsors helping to support Dashy's development!
Jtfinley72 - - - - CynegeticIO -
- CynegeticIO - @@ -670,6 +635,9 @@ Huge thanks to the sponsors helping to support Dashy's development! #### 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)** --- diff --git a/docs/alternate-views.md b/docs/alternate-views.md index 12d30b6e..57f756c9 100644 --- a/docs/alternate-views.md +++ b/docs/alternate-views.md @@ -3,6 +3,7 @@ ## 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 @@ -10,6 +11,7 @@ Dashy has three different views: 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.

@@ -18,6 +20,7 @@ This is the main page that you will land on when you first launch the applicatio

### 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. @@ -30,6 +33,7 @@ You can also opt to keep previously opened websites/ apps open in the background

### 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).

@@ -49,7 +53,7 @@ Dashy supports several different ways to launch your apps. The primary opening m 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. +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.

diff --git a/docs/assets/CONTRIBUTORS.svg b/docs/assets/CONTRIBUTORS.svg index 0c6fc4dc..37e259a7 100644 --- a/docs/assets/CONTRIBUTORS.svg +++ b/docs/assets/CONTRIBUTORS.svg @@ -1,4 +1,4 @@ - + @@ -7,156 +7,276 @@ - + - + + + + - + - + - + - + - + + + + + + + + + + + + + - + + + + + + + + + + - + + + + - + - - + + + + + - - - - - - - - - - - - - - - - + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + - + - - + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + - + - \ No newline at end of file + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/repo-visualization.svg b/docs/assets/repo-visualization.svg index 51a33159..e12276e8 100644 --- a/docs/assets/repo-visualization.svg +++ b/docs/assets/repo-visualization.svg @@ -1 +1 @@ -viewsviewsutilsutilsstylesstylesmixinsmixinsdirectivesdirectivescomponentscomponentsassetsassetsWorkspaceWorkspaceWidgetsWidgetsSettingsSettingsPageStrcturePageStrctureMinimalViewMinimalViewLinkItemsLinkItemsInteractiveEditorInteractiveEditorFormElementsFormElementsConfigurationConfigurationChartsChartslocaleslocalesinterface-iconsinterface-iconsemojis.jsonemojis.jsonemojis.jsonConfigSch...ConfigSch...ConfigSch...color-the...color-the...color-the...store.jsstore.jsstore.jsAnonAddy...AnonAddy...AnonAddy...CustomTh...CustomTh...CustomTh...Section.vueSection.vueSection.vueItem.vueItem.vueItem.vueEditItem...EditItem...EditItem...ConfigCo...ConfigCo...ConfigCo...en.jsonen.jsonen.jsonde.jsonde.jsonde.jsonbg.jsonbg.jsonbg.jsonhi.jsonhi.jsonhi.jsonko.jsonko.jsonko.jsonpt.jsonpt.jsonpt.jsonit.jsonit.jsonit.jsonfr.jsonfr.jsonfr.jsonsv.jsonsv.jsonsv.jsonzh-CN.jsonzh-CN.jsonzh-CN.jsonru.jsonru.jsonru.jsonsl.jsonsl.jsonsl.json.js.json.scss.svg.vueeach dot sized by file size \ No newline at end of file +viewsviewsutilsutilsstylesstylesmixinsmixinscomponentscomponentsassetsassetsWorkspaceWorkspaceWidgetsWidgetsSettingsSettingsPageStrcturePageStrctureMinimalViewMinimalViewLinkItemsLinkItemsInteractiveEditorInteractiveEditorFormElementsFormElementsConfigurationConfigurationChartsChartslocaleslocalesinterface-iconsinterface-icons.js.json.scss.svg.vueeach dot sized by file size diff --git a/docs/authentication.md b/docs/authentication.md index 080d9b7d..535cc4ba 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -1,307 +1,350 @@ -# 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 it 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 it's 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 setup, 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 sections or items only visible to some users, or hide sections and items from guests. -- `hideForUsers` - Section or Item will be visible to all users, except for those specified in this list -- `showForUsers` - Section or Item will be hidden from all users, except for those specified in this list -- `hideForGuests` - Section or Item will be visible for logged in users, but not for guests - -For Example: - -```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`. - -### 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 [Keycloack](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. - -### 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: -``` -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: -``` -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 -``` -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: -``` -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: -``` -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: -``` -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: -``` -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 usersnames 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: -``` -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 straight forward. - -### 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)** +# 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 sections or items only visible to some users, or hide sections and items from guests. + +- `hideForUsers` - Section or Item will be visible to all users, except for those specified in this list +- `showForUsers` - Section or Item will be hidden from all users, except for those specified in this list +- `hideForGuests` - Section or Item will be visible for logged in users, but not for guests + +For Example: + +```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)** diff --git a/docs/backup-restore.md b/docs/backup-restore.md index 2c6b2158..856b6564 100644 --- a/docs/backup-restore.md +++ b/docs/backup-restore.md @@ -1,4 +1,4 @@ -### Cloud Backup and Restore +# 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. @@ -8,18 +8,19 @@ This is useful not only for backing up your configuration off-site, but it also

-### How it Works +## 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 -### 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. +## Restoring a Backup -### Privacy & Security +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. @@ -27,24 +28,23 @@ Because the data is encrypted on the client-side (before being sent to the cloud 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 +## 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 +## Self-Hosting the Backup Server +### Quick Start -#### 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` +- Create a new project: `wrangler generate my-project` - Install dependencies: `cd my-project` && `npm i` +### Populate `wrangler.toml` -#### 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 @@ -63,10 +63,11 @@ kv_namespaces = [ ] ``` -#### Complete `index.js` +### 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: + - For Example: ```javascript addEventListener('fetch', event => { @@ -82,28 +83,28 @@ async function handleRequest(request) { - For the code used for Dashy's cloud service, see [here](https://gist.github.com/Lissy93/d19b43d50f30e02fa25f349cf5cb5ed8#file-index-js) +### Commands -#### Commands - `wrangler dev` - To start the wrangler development server - `wrangler publish` - To publish to your cloudflare account (first run `wrangler login`) -### API +## 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 + - `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 + - `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 + - `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 + - `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). diff --git a/docs/configuring.md b/docs/configuring.md index 95c885b4..9f628b01 100644 --- a/docs/configuring.md +++ b/docs/configuring.md @@ -2,7 +2,8 @@ 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 +## 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)_ @@ -12,7 +13,8 @@ All app configuration is specified in [`/public/conf.yml`](https://github.com/Li - **REST API** _(Coming soon)_ - Programmatically edit config either through the command line, using a script or a third-party application -#### Tips +## 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 @@ -23,7 +25,7 @@ All app configuration is specified in [`/public/conf.yml`](https://github.com/Li The following file provides a reference of all supported configuration options. -#### Contents +## Contents - [**`pageInfo`**](#pageinfo) - Header text, footer, title, navigation, etc - [`navLinks`](#pageinfonavlinks-optional) - Links to display in the navigation bar @@ -52,7 +54,7 @@ The following file provides a reference of all supported configuration options. --- -### Top-Level Fields +## Top-Level Fields **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -63,7 +65,7 @@ The following file provides a reference of all supported configuration options. **[⬆️ Back to Top](#configuring)** -### `PageInfo` +## `PageInfo` **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -75,7 +77,7 @@ The following file provides a reference of all supported configuration options. **[⬆️ Back to Top](#configuring)** -### `pageInfo.navLinks` _(optional)_ +## `pageInfo.navLinks` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -85,7 +87,7 @@ The following file provides a reference of all supported configuration options. **[⬆️ Back to Top](#configuring)** -### `pages[]` _(optional)_ +## `pages[]` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -94,7 +96,7 @@ The following file provides a reference of all supported configuration options. **[⬆️ Back to Top](#configuring)** -### `appConfig` _(optional)_ +## `appConfig` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -110,6 +112,7 @@ The following file provides a reference of all supported configuration options. **`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. @@ -125,22 +128,24 @@ The following file provides a reference of all supported configuration options. **`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 `true` to disable all service workers. +**`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)_ +## `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).
**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 anabled. Note that you need to have an instance running, and have also configured `auth.keycloak`. Defaults to `false` +**`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`. @@ -148,7 +153,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** -### `appConfig.auth.users` _(optional)_ +## `appConfig.auth.users` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -158,7 +163,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** -### `appConfig.auth.keycloak` _(optional)_ +## `appConfig.auth.keycloak` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -169,7 +174,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** -### `appConfig.webSearch` _(optional)_ +## `appConfig.webSearch` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -179,10 +184,9 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **`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)_ +## `appConfig.hideComponents` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -194,7 +198,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** -### `section` +## `section` **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -202,11 +206,11 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **`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 overide display settings for a given section. See [`displayData`](#sectiondisplaydata-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` +## `section.item` **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -219,19 +223,18 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **`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 +**`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 overide display settings for a given item. See [`displayData`](#itemdisplaydata-optional) +**`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)_ +## `item.displayData` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -243,8 +246,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** - -### `section.widget` _(optional)_ +## `section.widget` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -254,12 +256,11 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **`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 +**`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)_ +## `section.displayData` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -268,10 +269,10 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **`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 overide any settings specified through the UI +**`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 responsivley 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` +**`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 @@ -282,7 +283,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** -### `section.icon` and `section.item.icon` +## `section.icon` and `section.item.icon` **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -290,7 +291,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** -### `section.displayData.hideForKeycloakUsers`, `section.displayData.showForKeycloakUsers`, `item.displayData.hideForKeycloakUsers` and `item.displayData.showForKeycloakUsers` +## `section.displayData.hideForKeycloakUsers`, `section.displayData.showForKeycloakUsers`, `item.displayData.hideForKeycloakUsers` and `item.displayData.showForKeycloakUsers` **Field** | **Type** | **Required**| **Description** --- |------------| --- | --- @@ -320,12 +321,15 @@ Config can be modified directly through the UI, and then written to disk, or app

### 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. +- 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 @@ -333,7 +337,7 @@ If you have authentication set up, then any user who is not an admin (with `type 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`. +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 @@ -355,7 +359,7 @@ sections: # An array of sections - title: Demo description: A live demo icon: far fa-rocket - url: https://dashy-demo-1.netlify.app + url: https://dashy-demo-1.netlify.app - name: Section 2 - Local Services items: - title: Firewall @@ -373,4 +377,3 @@ If you need any help, feel free to [Raise an Issue](https://github.com/Lissy93/d Happy Configuring 🤓🔧 **[⬆️ Back to Top](#configuring)** - diff --git a/docs/contributing.md b/docs/contributing.md index 8898cb08..b57cc415 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -5,11 +5,13 @@ There are several ways that you can help out, and any contributions, however sma 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) @@ -36,46 +38,55 @@ Sponsoring will give you several perks - for $1 / £0.75 per month, you'll get a - **ZEC**: `t1bw1SefijsXRDQVxC9w64XsRK8hBhtQohQ`

+ ## 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). +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 anonomized and stored securely. For more about privacy and security, see the [Sentry Security Docs](https://sentry.io/security/). +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) @@ -90,6 +101,7 @@ Dashy is still a relatively young project, and as such not many people know of i [![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) @@ -99,6 +111,7 @@ Dashy is on the following platforms, and if you could spare a few seconds to giv [![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) @@ -122,4 +135,3 @@ For a full list of Dashy's contributors, see the [Credits Page](/docs/credits.md ### Star-Gazers Over Time [![Stargazers](https://starchart.cc/Lissy93/dashy.svg)](https://seladb.github.io/StarTrack-js/#/preload?r=Lissy93,dashy) - diff --git a/docs/credits.md b/docs/credits.md index 3134b777..dc343bbe 100644 --- a/docs/credits.md +++ b/docs/credits.md @@ -1,6 +1,6 @@ # Credits -### Sponsors +## Sponsors @@ -25,6 +25,20 @@ Eddy Lazzarin + + - - - - - - - - -
+ + AnandChowdhary +
+ Anand Chowdhary + + 		+ + davidpaulyoung +
+ David Young + + 		k-rol @@ -33,25 +47,18 @@ - - UlisesGascon + + bile0026
- Ulises Gascón - - 		- - BOZG -
- Stephen Rigney + Zach Biles
- - AdamXweb + + UlisesGascon
- Adam Kostarelas + Ulises Gascón 		@@ -61,61 +68,25 @@ Brian McGonagill - - Robert-Ernst -
- Robert Ernst - - 		- vlad-timofeev + vlad-timofeev
Vlad Timofeev 		- - mDafox + + iJasonWade
- Manu Devos + Jason Ash 		- - Byolock + + DRXAquosus
- Byolock - -
- - PAPAMICA -
- Mickael Asseline - - 		- - hugalafutro -
- Hugalafutro - - 		- - shadowking001 -
- LawrenceP. - - 		- - KierenConnell -
- Kieren Connell + Null 		@@ -124,13 +95,6 @@
Ratty222 - 		- - undefined -
- Undefined -
@@ -139,18 +103,11 @@
Jtfinley72 - 		- - CynegeticIO -
- CynegeticIO -
-### Contributors +## Contributors @@ -182,21 +139,28 @@ EVOTk - + + + + + + + + + + + + + + + + + + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
- - Ateroz -
- Kenneth Church - - 		snyk-bot
Snyk Bot + 		+ + kenneth-church +
+ Kenneth Church +
+ + m42e +
+ Matthias Bilger + + 		pinarruiz @@ -231,6 +195,35 @@
Jammo2k5 +
+ + lordpansar +
+ Magnus Sundström + + 		+ + Cereal916 +
+ Kristian Brasel + + 		+ + albcp +
+ Alberto + + 		+ + altearius +
+ Chris Nielsen + 		@@ -238,8 +231,29 @@
UrekD + 		+ + aviolaris +
+ Andreas Violaris +
+ + Tracreed +
+ David Alasow + + 		+ + DimitriDR +
+ Dimitri + + 		remygrandin @@ -247,6 +261,13 @@ Remygrandin + + Totto16 +
+ Totto16 + + 		alucarddelta @@ -255,8 +276,16 @@ - - boggy-cs + + Tuzi555 +
+ Jakub Tuzar + +
+ + Bogyie
Bogyeong Kim @@ -268,6 +297,20 @@ Stanly0726 		+ + rubenandre +
+ Rúben Silva + + 		+ + rtm516 +
+ Rtm516 + + 		onedr0p @@ -283,6 +326,13 @@
+ + a-mnich +
+ Alexander Mnich + + 		BOZG @@ -305,17 +355,32 @@ - - rubenandre + + thomaswienecke
- Rúben Silva + Thomas Wienecke + + 		+ + hockeymikey +
+ Null + +
+ + itsmejoeeey +
+ Joey Miller 		k073l
- K073l + Null 		@@ -324,15 +389,29 @@
Patrick Heeney -
- - Singebob + + BySempron
- Jeremy Chauvin + Sergio 		+ + ssrangisetti +
+ Null + + 		+ + zcq100 +
+ Null + +
0n1cOn3 @@ -340,6 +419,13 @@ 0n1cOn3 + + AaronPorts +
+ Artyom + + 		BRAVO68WEB @@ -354,6 +440,13 @@ Begin + + bskim45 +
+ Bumsoo Kim + + 		skaarj1989 @@ -361,11 +454,347 @@ David
+ + DawidPietrykowski +
+ Null + + 		+ + deepsourcebot +
+ DeepSource Bot + + 		+ + dkyeremeh +
+ Desmond Kyeremeh + + 		+ + dougaldhub +
+ Doug Lock + + 		+ + Dylan-Bs +
+ Dylan Bersans + + 		+ + emiran-orange +
+ Null + +
+ + FormatToday +
+ FormatToday + + 		+ + gbrown09 +
+ Garrett Brown + + 		+ + nealian +
+ Ian Neal + + 		+ + Compunctus +
+ Iaroslav Dronskii + + 		+ + b1thunt3r +
+ Ishan Jain + + 		+ + Hellhium +
+ Jemy SCHNEPP + +
+ + Singebob +
+ Jeremy Chauvin + + 		+ + kieraneglin +
+ Kieran + + 		+ + KierenConnell +
+ Kieren Connell + + 		+ + LeoColman +
+ Leonardo Colman Lopes + + 		+ + luispabon +
+ Luis Pabon + + 		+ + asenov +
+ Мирослав Асенов + +
+ + markusdd +
+ Markus Krause + + 		+ + maximemoreillon +
+ Maxime Moreillon + + 		+ + imsakg +
+ Mert Sefa AKGUN + + 		+ + miclav +
+ Michael Lavaire + + 		+ + PlusaN +
+ Andrey + + 		+ + PrynsTag +
+ Prince Carl Velasco + +
+ + rubjo +
+ Null + + 		+ + turnrye +
+ Ryan Turner + + 		+ + royshreyaaa +
+ Shreya Roy + + 		+ + Smexhy +
+ Null + + 		+ + XenonR +
+ Steffen Schmidt + + 		+ + StevKast +
+ Steven Kast + +
+ + XertDev +
+ Xert + + 		+ + baifengheixi +
+ Null + + 		+ + dr460nf1r3 +
+ Nico + + 		+ + flechaig +
+ Null + + 		+ + huangshaohuai +
+ Null + + 		+ + icy-comet +
+ Aniket Teredesai + +
+ + imlonghao +
+ Imlonghao + + 		+ + jnach +
+ Jnach + + 		+ + jrobles98 +
+ Null + + 		+ + kxenoxx +
+ Kxenox + + 		+ + lxjv +
+ Laker Turner + + 		+ + pablomalo +
+ Null + +
+ + poisonadder7 +
+ Null + + 		+ + soaibsafi +
+ Soaibuzzaman + + 		+ + sur1v +
+ José Ignacio + + 		+ + tazboyz16 +
+ Null + + 		+ + AmadeusGraves +
+ Ángel Fernández Sánchez + +
- -### Helpful Users +## Helpful Users @@ -414,7 +843,7 @@
-### Bots +## Bots @@ -465,7 +894,7 @@ > The above section is auto-generated, using [contribute-list](https://github.com/marketplace/actions/contribute-list) by @akhilmhdh. -### Newest Stargazers +## Newest Stargazers [![Recent Star Gazers](https://reporoster.com/stars/dark/Lissy93/dashy)](https://github.com/Lissy93/dashy/stargazers) @@ -477,17 +906,20 @@ This app definitely wouldn't have been quite so possible without the making use of the following package and components. Full credit and big kudos to their respective authors, who've done an amazing job in building and maintaining them. For a full breakdown of dependency licenses, please see [Legal](https://github.com/Lissy93/dashy/blob/master/.github/LEGAL.md) -#### Core +### Core + At it's core, the application uses [**Vue.js**](https://github.com/vuejs/vue), as well as it's services with [**VueX**](https://vuex.vuejs.org/) for state management. Styling is done with [**SCSS**](https://github.com/sass/sass), JavaScript is currently [**Babel**](https://github.com/babel/babel), (but I am in the process of converting to [**TypeScript**](https://github.com/Microsoft/TypeScript)). Linting is done with [**ESLint**](https://github.com/eslint/eslint) and [**Prettier**](https://prettier.io/), both following the [**AirBnB Styleguide**](https://github.com/airbnb/javascript). The config is defined in [**YAML**](https://github.com/yaml/yaml), with a simple [**Node.js**](https://github.com/nodejs/node) server to serve up the static app and the optional API endpoints, and container deployment is done with [**Docker**](https://www.docker.com/). -#### Utilities +### Utilities + - [`crypto-js`](https://github.com/brix/crypto-js) - Encryption implementations by @evanvosberg and community `MIT` - [`axios`](https://github.com/axios/axios) - Promise based HTTP client by @mzabriskie and community `MIT` - [`ajv`](https://github.com/ajv-validator/ajv) - JSON schema Validator by @epoberezkin and community `MIT` - [`i18n`](https://github.com/kazupon/vue-i18n) - Internationalization plugin by @kazupon and community `MIT` - [`frappe-charts`](https://github.com/frappe/charts) - Lightweight charting library by @frappe `MIT` -#### Frontend Components +### Frontend Components + - [`vue-select`](https://github.com/sagalbot/vue-select) - Dropdown component by @sagalbot `MIT` - [`vue-js-modal`](https://github.com/euvl/vue-js-modal) - Modal component by @euvl `MIT` - [`v-tooltip`](https://github.com/Akryum/v-tooltip) - Tooltip component by @Akryum `MIT` @@ -497,13 +929,16 @@ At it's core, the application uses [**Vue.js**](https://github.com/vuejs/vue), a - [`vue-toasted`](https://github.com/shakee93/vue-toasted) - Toast notification component by @shakee93 `MIT` - [`vue-swatches`](https://github.com/saintplay/vue-swatches) - Color palete picker by @saintplay `MIT` -#### Backup & Sync Server +### Backup & Sync Server + Although the app is purely frontend, there is an optional cloud sync feature, for off-site backup and restore. This is built as a serverless function on [Cloudflare workers](https://workers.cloudflare.com/) using [KV](https://developers.cloudflare.com/workers/runtime-apis/kv) and [web crypto](https://developers.cloudflare.com/workers/runtime-apis/web-crypto) -#### External Services +### External Services + The 1-Click deploy demo uses [Play-with-Docker Labs](https://play-with-docker.com/). Code is hosted on [GitHub](https://github.com), Docker images are hosted on [DockerHub](https://hub.docker.com/), and the demos are hosted on [Netlify](https://www.netlify.com/). -#### Actions +### Actions + This repo makes heavy use of [GitHub actions](https://github.com/features/actions) to run automated workflows. The following base actions are totally awesome, and have been extremely useful. Full credit to their respective authors - [`action-autotag`](https://github.com/butlerlogic/action-autotag) by @butlerlogic - Tags new versions when app version changes @@ -525,5 +960,6 @@ This repo makes heavy use of [GitHub actions](https://github.com/features/action --- -## You! +## You + Would you like to be listed here? Whatever your skill set, Dashy needs people like you to help support future development. Check out the [Contributing Page](/docs/contributing.md) for ways that you can get involved. Huge thank you to everyone who has already contributed! 💖 diff --git a/docs/deployment.md b/docs/deployment.md index e9710e6a..cad56a2e 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -2,9 +2,11 @@ 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 +## 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 ``` @@ -44,8 +46,7 @@ Once you've got Dashy up and running, you'll want to configure it with your own 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. - -```docker +```bash docker run -d \ -p 8080:80 \ -v /root/my-local-conf.yml:/app/public/conf.yml \ @@ -55,6 +56,7 @@ docker run -d \ ``` 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) @@ -66,7 +68,7 @@ For all available options, and to learn more, see the [Docker Run Docs](https:// 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. +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` @@ -108,6 +110,7 @@ services: 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` @@ -126,15 +129,17 @@ 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. -``` + > 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 \ @@ -142,7 +147,9 @@ docker run -d \ --restart=always \ lissy93/dashy:latest ``` + dashy should be up within 1-2min after you've started the install task procedure + --- ## Build from Source @@ -157,121 +164,142 @@ If you do not want to use Docker, you can run Dashy directly on your host system --- -### Deploy to cloud service +## 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 availible. This is because these features need endpoints provided by Dashy's local Node server. Everything else should work just the same though. +**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 -#### 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 +### 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 is free to use for unlimited, non-commercial, single dyno apps, and supports custom domains. Heroku's single-dyno service is not as quite performant as some other providers, and the app will have a short wake-up time when not visited for a while +[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 ``` -#### Cloudflare Workers +### Cloudflare Workers + [![Deploy to Cloudflare Workers](https://i.ibb.co/jf9xVdm/deploy-cloudflare-button.png)](https://deploy.workers.cloudflare.com/?url=https://github.com/lissy93/dashy/tree/deploy_cloudflare) [Cloudflare Workers](https://workers.cloudflare.com/) is a simple yet powerful service for running cloud functions and hosting web content. It requires a Cloudflare account, but is completely free for smaller projects, and very reasonably priced ($0.15/million requests per month) for large applications. You can use your own domain, and applications are protected with Cloudflare's state of the art DDoS protection. For more info, see the docs on [Worker Sites](https://developers.cloudflare.com/workers/platform/sites) To deploy Dashy to Cloudflare, use the following link -``` + +```text https://deploy.workers.cloudflare.com/?url=https://github.com/lissy93/dashy/tree/deploy_cloudflare ``` -#### Vercel +### 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 anaylzing application performance and other metrics. Vercel is free for personal use, allows for custom domains and has very reasonable limits. +[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 +### 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 +### 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 +### 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 +### 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 +### 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 +[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 +### 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 +### 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 @@ -281,13 +309,12 @@ surge ./dist ## Hosting with CDN -Once Dashy has been built, it is effectivley 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. +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 unavailible 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. +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 @@ -295,13 +322,16 @@ However without Dashy's node server, there are a couple of features that will be 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. + +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, + +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). + +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. diff --git a/docs/developing.md b/docs/developing.md index edd98f5f..4571385a 100644 --- a/docs/developing.md +++ b/docs/developing.md @@ -24,6 +24,7 @@ If you're adding new features, you may want to check out the [Development Guides ## 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 @@ -33,34 +34,40 @@ You will need either the latest or LTS version of **[Node.js](https://nodejs.org 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. +Dashy should now be being served on . 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` +- 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. @@ -75,6 +82,7 @@ You can set variables either in your environment, or using the [`.env`](https:// - `VUE_APP_VERSION` - Again, set automatically using package.json during build time ### 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). --- @@ -82,6 +90,7 @@ You can set the environment using the `NODE_ENV` variable. By default, the corre ## 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) @@ -93,10 +102,12 @@ Like most Git repos, we are following the [Github Flow](https://guides.github.co 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. @@ -127,14 +138,17 @@ Using a single emoji at the start of each commit message, to indicate the type t 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 @@ -144,7 +158,9 @@ When you submit your PR, include the required info, by filling out the PR templa --- ## 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/) @@ -158,37 +174,40 @@ New to Web Development? Glad you're here! Dashy is a pretty simple app, so it sh - [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). +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 +### 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 Stylguide](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 +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 +- 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) +- JavaScript: [github.com/airbnb/javascript](https://github.com/airbnb/javascript) --- -## Application Structure +### Application Structure #### Files in the Root: `./` -``` + +```text ╮ ├── package.json # Project meta-data, dependencies and paths to scripts ├── src/ # Project front-end source code @@ -207,13 +226,13 @@ Styleguides: #### 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 +│ ╰── 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 @@ -250,7 +269,7 @@ Styleguides: │ │ ├── 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 +│ │ ├── 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 @@ -340,9 +359,11 @@ Styleguides: ## 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 --- @@ -356,4 +377,3 @@ When running the build command, several warnings appear. These are not errors, a `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. - diff --git a/docs/development-guides.md b/docs/development-guides.md index 4f2256c8..0d629412 100644 --- a/docs/development-guides.md +++ b/docs/development-guides.md @@ -1,8 +1,9 @@ # Development Guides -A series of short tutorials, to guide you through the most common development tasks. +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) @@ -17,11 +18,13 @@ Sections: Adding a new theme is really easy. There's 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 you're theme, and add it to the `builtInThemes` array inside [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js#L27). +### 1. Add Theme Name -##### 2. Write some Styles! -Put your theme's styles inside [`color-themes.scss`](https://github.com/Lissy93/dashy/blob/master/src/styles/color-themes.scss). +Choose a snappy name for you're 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's 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 @@ -45,10 +48,12 @@ Dashy is using [vue-i18n](https://vue-i18n.intlify.dev/guide/) to manage multi-l Adding a new language is pretty straightforward, with just three steps: -##### 1. Create a new Language File +### 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! +### 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 @@ -65,7 +70,7 @@ Using [`en.json`](https://github.com/Lissy93/dashy/tree/master/src/assets/locale } ``` -##### 3. Add your file to the app +### 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: @@ -73,6 +78,7 @@ 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 = [ { @@ -89,11 +95,12 @@ export const languages = [ }, ]; ``` + You can also add your new language to the readme, 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. +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 +## Adding a new option in the config file This section is for, adding a new setting to the config file. @@ -101,6 +108,7 @@ All of the users config is specified in `./public/conf.yml` - see [Configuring D 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` @@ -132,7 +140,9 @@ For example: "example": "0821c65656" } ``` + or + ```json "iconSize": { "enum": [ "small", "medium", "large" ], @@ -144,7 +154,8 @@ or 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 explaining, 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 + +- [ ] 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 @@ -163,12 +174,12 @@ It is important to thoroughly test after any big dependency updates. 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 +### 1. Run Netlify Dev Server First off, 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 +### 2. Create a lambda function This should be saved it in the [`./services/serverless-functions`](https://github.com/Lissy93/dashy/tree/master/services/serverless-functions) directory @@ -179,7 +190,7 @@ exports.handler = async () => ({ }); ``` -#### 3. Redirect the Node endpoint to the function +### 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 @@ -194,20 +205,23 @@ In the [`netlify.toml`](https://github.com/Lissy93/dashy/blob/FEATURE/serverless --- ## 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 +### 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 +### 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 { ... @@ -219,8 +233,9 @@ export default { }, }; ``` - + Finally, in the markup of your component, just add a `v-if` statement, referencing your computed value + ```vue
... @@ -230,6 +245,7 @@ Finally, in the markup of your component, just add a `v-if` statement, referenci --- ## 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. @@ -250,12 +266,10 @@ To build a widget, you'll also need some basic knowledge of Vue.js. The [officia 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 @@ -80,3 +86,8 @@ export default { } + diff --git a/src/components/Workspace/SideBar.vue b/src/components/Workspace/SideBar.vue index 2cb7ca1f..2c85a167 100644 --- a/src/components/Workspace/SideBar.vue +++ b/src/components/Workspace/SideBar.vue @@ -20,10 +20,10 @@
- + - +
diff --git a/src/components/Workspace/WebContent.vue b/src/components/Workspace/WebContent.vue index 69cc2832..63d5e535 100644 --- a/src/components/Workspace/WebContent.vue +++ b/src/components/Workspace/WebContent.vue @@ -1,6 +1,6 @@