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

Improves documentation, github templates and readme

This commit is contained in:
Alicia Sykes 2021-06-09 14:03:56 +01:00
parent 089ceb3e56
commit 1e8e54b1f9
7 changed files with 452 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/pull_request_template.md vendored
View File

@ -9,7 +9,7 @@
**Issue Number** (if applicable):
**Briefley outline your changes**:
**Briefly outline your changes**:
**Before submitting, please ensure that**:
- [ ] Must be backwards compatible

65
README.md
View File

@ -10,6 +10,7 @@
<img width="220" src="https://i.ibb.co/yhbt6CY/dashy.png" />
</p>
## Features 🌈
- Instant search by name, domain and tags - just start typing
@ -38,7 +39,7 @@
---
## Running the App 🏃‍♂️
## Getting Started 🛫
> For full setup instructions, see: [**Getting Started**](./docs/getting-started.md)
#### Deploying from Docker Hub 🐳
@ -118,22 +119,70 @@ Hot reload is enabled, so changes will be detected automatically, triggering the
If you are new to Vue.js or web development and want to learn more, [here are some resources](docs/developing.md#resources-for-beginners) to help get you started. Dashy is a pretty straight-forward application, so would make an ideal candidate for your first PR!
---
## Notes ✏
## Contributing 😇
> For full contributing guide, see: [**Contributing**](/docs/contributing.md)
Pull requests are welcome, and would by much appreciated!
Some ideas for PRs include: bug fixes, improve the docs, add new themes, implement a new widget, add or improve the display options, improve or refactor the code, or implement a new feature.
Before you submit your pull request, please ensure the following:
- Must be backwards compatible
- All lint checks and tests must pass
- If a new option in the the config file is added, it needs to be added into the schema, and documented in the configuring guide
- If a new dependency is required, it must be essential, and it must be thoroughly checked out for security or efficiency issues
- Your pull request will need to be up-to-date with master, and the PR template must be filled in
---
## Support 🙋‍♀️
If you've found a bug, or something that isn't working as you'd expect, please raise an issue, so that it can be resolved. Similarly, if you're having trouble getting things up and running, feel free to ask a question. Feature requests and feedback are also welcome, as it helps Dashy improve.
- [Raise a Bug 🐛](https://github.com/Lissy93/dashy/issues/new?assignees=Lissy93&labels=%F0%9F%90%9B+Bug&template=bug-report---.md&title=%5BBUG%5D)
- [Submit a Feature Request 🦄](https://github.com/Lissy93/dashy/issues/new?assignees=Lissy93&labels=%F0%9F%A6%84+Feature+Request&template=feature-request---.md&title=%5BFEATURE_REQUEST%5D)
- [Ask a Question 🤷‍♀️](https://github.com/Lissy93/dashy/issues/new?assignees=Lissy93&labels=%F0%9F%A4%B7%E2%80%8D%E2%99%82%EF%B8%8F+Question&template=question------.md&title=%5BQUESTION%5D)
- [Share Feedback 🌈](https://github.com/Lissy93/dashy/issues/new?assignees=&labels=%F0%9F%8C%88+Feedback&template=share-feedback---.md&title=%5BFEEDBACK%5D)
For general questions about any of the technologies used, you should search the [web](https://duckduckgo.com), or open a question on [StackOverflow](https://stackoverflow.com/questions/)
If you need to get in touch securely with the author me, you can send any messages to me at:
- **Email**: `alicia at omg dot lol`
- **Public Key** [`0688 F8D3 4587 D954 E9E5 1FB8 FEDB 68F5 5C02 83A7`](https://keybase.io/aliciasykes/pgp_keys.asc?fingerprint=0688f8d34587d954e9e51fb8fedb68f55c0283a7)
---
## Documentation 📘
- [Getting Started](/docs/getting-started.md)
- [Configuring](/docs/configuring.md)
- [Developing](/docs/developing.md)
- [Contributing](/docs/contributing.md)
- [User Guide](/docs/user-guide.md)
- [Troubleshooting](/docs/troubleshooting.md)
- [Backup & Restore](/docs/backup-restore.md)
- [Theming](/docs/theming.md)
---
## Credits 🏆
### Contributors 👥
![Auto-generated contributors](https://raw.githubusercontent.com/Lissy93/dashy/03fbaf35ff4653d16a622cfce00a1347c13d0192/docs/assets/CONTRIBUTORS.svg)
_(^^ The above is auto-generated, submit a PR to become listed as a contributor!)_
_(^^ It's lonely here all by myself - submit a PR to become listed as a contributor!)_
### Credits 🏆
### Dependencies 🔗
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.
#### Core
##### Core
At it's core, the application uses [Vue.js](https://github.com/vuejs/vue), as well as it's services. 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), the config is defined in [YAML](https://github.com/yaml/yaml), and there is a simple [Node.js](https://github.com/nodejs/node) server to serve up the static app.
#### 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`
@ -144,12 +193,12 @@ At it's core, the application uses [Vue.js](https://github.com/vuejs/vue), as we
- [`vue-prism-editor`](https://github.com/koca/vue-prism-editor) - Lightweight code editor by @koca `MIT`
- Forked from [`prism.js`](https://github.com/PrismJS/prism) `MIT`
#### 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`
#### Backup & Sync Server
##### Backup & Sync Server
Although the app is purely frontend, there is an optional cloud backup and restore feature. 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)
### Alternatives 🙌

129
docs/contributing.md Normal file
View File

@ -0,0 +1,129 @@
First off, thank you for considering contributing to Dashy! There are two main ways you can help out: [Submitting a Pull Request](#submitting-a-pr) or [Raising an Issue](#raising-an-issue).
### Submitting a PR
Pull requests are proposed code changes, that can then be directly merged into Dashy's master branch and deployed to users. Even a small PR would be a big help.
Not sure what to work on? Here are some ideas:
- Fix a bug, or solve an open issue
- Improve the docs
- Add a new theme
- Implement a new widget
- Add more display options
- Refactor or improve an area of the code
- Implement a new feature, or improve an existing one
Before you submit your pull request, please ensure the following:
- Must be backwards compatible
- All lint checks and tests must pass
- If a new option in the the config file is added, it needs to be added into the schema, and documented in the configuring guide
- If a new dependency is required, it must be essential, and it must be thoroughly checked out for security or efficiency issues
Please also include the following information in your PR:
- PR type (bug fix, feature, code style updates, documentation, etc)
- Issue number (if applicable)
- A brief description of your changes
- A note confirming that your code follows the checklist (above)
#### Getting Started
To set up your development environment, and get Dashy running locally, please see: [Developing Docs](/docs/developing.md)
#### For new Contributors
If you have never created a pull request before, welcome :tada: :smile: [Here is a great tutorial](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github)
on how to create a pull request..
1. [Fork](http://help.github.com/fork-a-repo/) the project, clone your fork,
and configure the remotes:
```bash
# Clone your fork of the repo into the current directory
git clone https://github.com/<your-username>/<repo-name>
# Navigate to the newly cloned directory
cd <repo-name>
# Assign the original repo to a remote called "upstream"
git remote add upstream https://github.com/hoodiehq/<repo-name>
```
2. If you cloned a while ago, get the latest changes from upstream:
```bash
git checkout master
git pull upstream master
```
3. Create a new topic branch (off the main project development branch) to
contain your feature, change, or fix:
```bash
git checkout -b <topic-branch-name>
```
4. Make sure to update, or add to the tests when appropriate. Patches and
features will not be accepted without tests. Run `yarn test` to check that
all tests pass after you've made changes.
5. If you added or changed a feature, make sure to document it accordingly in
the docs and if applicable, in the `README.md` file.
6. Push your topic branch up to your fork:
```bash
git push origin <topic-branch-name>
```
8. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/)
with a clear title and description.
#### Testing the Production App
For larger pull requests, please also check that it works as expected in a production environment.
Testing production app in development environment:
- Natively
- Build: `yarn build`
- Run: `yarn start`
- With Docker:
- Build: `docker build -t dashy .`
- Run: `docker run -p 8080:80 dashy`
Please also ensure that running the following scripts return no errors:
- `yarn lint`
- `yarn test`
- `yarn validate-config`
A good resource for testing the Docker image on a totally fresh system, is by using [Play with Docker](https://labs.play-with-docker.com/). This will let you clone or pull your image, and spin up a container. This is useful for checking that everything behaves as it should on an independent system, and should get around the _'works on my computer'_ issue.
#### Merging a PR
Only maintainers can merge a PR. A pull request can only be merged if:
- All CI checks are passing
- It has been approved by either the author, or at least two maintainers
- It has no requested changes
- It is up to date with current master
---
### Raising an Issue
If you've found a bug, or something that isn't working as you'd expect, please raise an issue, so that it can be resolved. If you're having trouble getting things up and running, feel free to ask a question. Feature requests and feedback are also welcome, as it helps Dashy improve.
Click one of the links below, to open an issue:
- [Raise a Bug 🐛](https://github.com/Lissy93/dashy/issues/new?assignees=Lissy93&labels=%F0%9F%90%9B+Bug&template=bug-report---.md&title=%5BBUG%5D) - Found a bug, or something not working as it should?
- [Submit a Feature Request 🦄](https://github.com/Lissy93/dashy/issues/new?assignees=Lissy93&labels=%F0%9F%A6%84+Feature+Request&template=feature-request---.md&title=%5BFEATURE_REQUEST%5D) - Is there a feature that you think is missing from Dashy?
- [Ask a Question 🤷‍♀️](https://github.com/Lissy93/dashy/issues/new?assignees=Lissy93&labels=%F0%9F%A4%B7%E2%80%8D%E2%99%82%EF%B8%8F+Question&template=question------.md&title=%5BQUESTION%5D) - Got a question about using, building or developing Dashy?
- [Share Feedback 🌈](https://github.com/Lissy93/dashy/issues/new?assignees=&labels=%F0%9F%8C%88+Feedback&template=share-feedback---.md&title=%5BFEEDBACK%5D) - Got any thoughts on the current or future development of Dashy?
---
### Contributors
![Auto-generated contributors](https://raw.githubusercontent.com/Lissy93/dashy/03fbaf35ff4653d16a622cfce00a1347c13d0192/docs/assets/CONTRIBUTORS.svg)
### Star-Gazers Over Time
![Stargazers](https://starchart.cc/Lissy93/dashy.svg)

13
docs/readme.md
View File

@ -2,8 +2,11 @@
## Contents
- [Getting Started](./getting-started.md)
- [Configuring](./backup-restore.md)
- [Backup & Restore](./backup-restore.md)
- [Theming](./backup-restore.md)
- [Developing](./developing.md)
- [Getting Started](/docs/getting-started.md)
- [Configuring](/docs/configuring.md)
- [Developing](/docs/developing.md)
- [Contributing](/docs/contributing.md)
- [User Guide](/docs/user-guide.md)
- [Troubleshooting](/docs/troubleshooting.md)
- [Backup & Restore](/docs/backup-restore.md)
- [Theming](/docs/theming.md)

2
docs/troubleshooting.md Normal file
View File

@ -0,0 +1,2 @@
Coming Soon...

94
docs/user-guide.md Normal file
View File

@ -0,0 +1,94 @@
## User Guide
### Searching
A key requirement for any start page is being able to quickly and effectively find the item your looking for. For Dashy, a lot of thought was put into the most intuitive method to filter links.
To start searching, simply start typing. Your search term will show up in the filter field in the upper-left section, and results will be filtered accordingly.
The following properties are used to filter items by:
- Title / Item name
- Provider - The optional field, indicating the provider of a given app or service
- URL - Only the base URL is searched, the protocol and parameters are omitted
- Description
### Keyboard Shortcuts
Many people find using the keyboard significantly more efficient than having to reach for the mouse. And so Dashy has a series of keybindings and shortcuts to enable you to navigate through items quickly.
Once you've searched for a given item, you can then tab through the list (or Shift + Tab to go backwards) until you've found the item you're looking for. You can also use the arrow keys to navigate up, down, left and right through the grid. To launch an item, just hit enter. You can also open an item in a new tab with Ctrl + Enter, or open the item in a pop-up modal with Alt + Enter. To close an open popup item, or any open menus, just hit Esc.
### Theme Switching
You can change the current theme using the dropdown menu in the upper-right-hand quadrant. Your selected theme will be stored in local storage, and applied next time you load the page. For more information on customizing the look and feel of Dashy, see [Themeing Docs](/docs/theming.md)
### Visual Options
There are several pre-built layout options to choose from depending on your requirements. Like the theme these options will be remembered in browser storage and applied on load.
The first is Layout. This determines how sections are organised on the screen. This can be set to either grid (auto), horizontal or vertical. Vertical layout will cause each section to take up the full width of the screen, and minimum height. Horizontal is the opposite, where every section is on the same row, and spans the full height of the screen.
Next there's icon size. This changes the size of the item and it's icon. It can be useful to use a smaller size when there are a lot of items, or a larger size if you commonly access Dashy from a touch screen tablet.
![layout-options](https://i.ibb.co/NnzF82t/available-layout-options.png)
### Opening Items
There are three methods of opening items. Clicking (or hitting Enter on a selected item) will use the default method, specified in the config file, under `item.target`. You can use Ctrl + Click or Ctrl + Enter to open and item in a new tab.
You can also use Alt + Click or Alt + Enter, to open an item in a popup window. You can use drag the tab in the bottom-right corner of the pop-up to resize it. To close an item opened in a pop-up, click the close button, use the Esc key, or click anywhere outside the popup.
![Example of a pop-up opened item](https://i.ibb.co/zSnznFF/dashy-popup.png)
### Sections and Items
The main content in Dashy is split into sections, which contain icons. You can have as many sections as you need, and each section can have an unlimited amount of icons. Visually, the grid layout works better when sections have a similar number of icons.
Sections are collapsible, which is useful for those sections which contain less used applications, or are particularly long. The collapse state of a given section is remembered (stored in local storage), and applied on load.
Sections also have several optional properties, which are specified under `section.displayData`, and let you set certain display settings. A full list of options can be found in the [configuring docs](/docs/configuring.md).
```
┌─────────────────────────────────────────────────────┐
│ Title │
│ Sub-Title/ Description Link 1 Link 2 │
├──────────────┬─────────────────┬────────────────────┤
│ Search │ │ Display Options │
├──────────────┘ └────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Section 1 │ │ Section 2 │ │ Section 3 │ │
│ ├──────────────┤ ├──────────────┤ ├──────────────┤ │
│ │ ┌───┐ ┌───┐ │ │ ┌───┐ ┌───┐ │ │ ┌───┐ ┌───┐ │ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
│ │ └───┘ └───┘ │ │ └───┘ └───┘ │ │ └───┘ └───┘ │ │
│ │ ┌───┐ ┌───┐ │ │ ┌───┐ ┌───┐ │ │ ┌───┐ ┌───┐ │ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
│ │ └───┘ └───┘ │ │ └───┘ └───┘ │ │ └───┘ └───┘ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
├─────────────────────────────────────────────────────┤
└─────────────────────────────────────────────────────┘
```
### Icons
Both sections and items can have an icon associated with them. There are several options for specifying icons. You can let the icon be automatically resolved and fetched from the items associated URL, by just setting the icon to `favicon`. You can use a font-awesome icon, by specifying it's name and category. Or you can pass in a URL, either to a locally hosted or remote image. For local images, you can put them in `./public/item-icons/` and then reference them just by the file name.
### Metadata
Basic site information, displayed in the header and footer can be set from the UI. This includes: title, sub-title, footer text, and nav-bar links. Click the wrench icon in the upper-right corner, then go to the Site Metadata tab. Fill in your new data, and hit save. The page will be refreshed, and your changes will appear. These settings are stored under `pageInfo` in the config, and if set through the UI, will only be applied locally.
### Editing Config
The config file can be edited from the UI, but take note that changes are only applied locally. You will need to either export this data into your conf.yml, or use the cloud backup and sync feature.
To make changes to the config file, click the wrench icon in the upper-left hand corner. Then go to the Config tab. Here you'll find a JSON editor. You can switch from tree mode to plain-text mode if you find that easier. And parsing or validation issues will be displayed at the bottom of the screen.
### Managing Config Data
You can download, backup or reset local config data directly from the UI. To apply config to Dashy on other devices, you will need to either download the config file, or use the cloud backup and sync feature. To download config, click the Wrench icon, in the upper-right hand corner, and then go to Download. Similarly, for cloud backup, click the Cloud icon in the upper right corner, and fill in the required fields. For detailed instructions, and technical information about backup and sync, please see the [Cloud Backup Documentation](/docs/backup-restore.md). You can also Reset all local settings from the config menu. This will not effect any data saved in your systems `conf.yml` file.

190
public/conf.yml
View File

@ -1,33 +1,165 @@
---
pageInfo:
title: Dashy
navLinks:
- title: Home
path: /
- title: About
path: /about
- title: Source Code
path: https://github.com/Lissy93/dashy
appConfig:
theme: colorful
fontAwesomeKey: 0821c65656
title: Networking Services
sections:
- name: Getting Started
- name: Firewall
items:
- title: Source
description: Source code and documentation on GitHub
icon: fab fa-github
url: https://github.com/Lissy93/dashy
- title: Issues
description: View currently open issues, or raise a new one
icon: fas fa-bug
url: https://github.com/Lissy93/dashy/issues
- title: Demo 1
description: 'Live Demo #1'
icon: far fa-rocket
url: https://dashy-demo-1.netlify.app
- title: Demo 2
description: 'Live Demo #2'
icon: fad fa-planet-ringed
url: https://dashy-demo-2.netlify.app
- title: OPNsense
description: Firewall Central Management
icon: networking/opnsense.png
target: iframe
url: https://192.168.1.1
- title: NetData
description: System resource usage on firewall
icon: networking/netdata.png
url: http://192.168.1.1:19999/
- title: MalTrail
description: Malicious traffic detection system
icon: networking/maltrail.png
url: http://192.168.1.1:8338
- title: Ntopng
description: Network traffic probe and network use monitor
icon: networking/ntop.png
url: http://192.168.1.1:3001
- title: Sensei
description: Additional data features
icon: networking/sensei.png
url: https://192.168.1.1/ui/sensei/
- title: Monit
description: Status of firewall system alerts
icon: networking/monit.png
url: https://192.168.1.1/ui/monit/status
- title: Firewall Logs
description: Real-time view of firewall data and logs
icon: networking/logs.png
url: https://192.168.1.1/ui/diagnostics/firewall/log
- title: WireGuard
description: Manage WireGuard client and server on firewall
icon: networking/wireguard.png
url: https://192.168.1.1/ui/wireguard/general
- name: DNS Device
displayData:
collapsed: false
rows: 2
items:
- title: Pi-Hole
description: DNS settings for ad & tracker blocking
icon: networking/pihole.png
url: http://192.168.130.2/admin
- title: PiAlert
description: Presence monitoring and ARP scanning
icon: networking/pialert.png
url: http://192.168.130.2/pialert/
- title: SmokePing
description: Network latency monitoring
icon: networking/smokeping.png
url: http://192.168.130.2:8086/
- title: StatPing
description: Up-time monitoring for local service
icon: networking/statping.png
url: http://192.168.130.2:8083/
- title: LibreSpeed
description: Local network speed and latency test
icon: networking/librespeed.png
url: http://192.168.130.2:49154/
- title: NetData
description: Real-time system resource usage
icon: networking/netdata.png
url: http://192.168.130.2:19999
- title: Portainer
description: Docker container management
icon: networking/portainer.png
url: http://192.168.130.2:9000/
- title: cAdvisor
description: Container monitoring
icon: networking/cadvisor.png
url: http://192.168.130.2:8084/
- title: Glances
description: Simple resource usage
icon: networking/glances.png
url: http://192.168.130.2:61208
- title: Dozzle
description: Docker container web log viewer
icon: networking/dozzle.png
url: http://192.168.130.2:8093
- title: Prometheus
description: System Statistics Aggregation with PromQL
icon: networking/prometheus.png
url: http://192.168.130.2:8090/
- title: Grafana
description: Data visualised on dashboards
icon: networking/grafana.png
url: http://192.168.130.2:8091/
- name: External Services
items:
- title: DuckDNS
description: Dynamic DNS for fixed public IP
icon: networking/duckdns.png
url: https://www.duckdns.org/
- title: BorgBase
description: Off-site system Borg backups
icon: networking/borgbase.png
url: https://www.borgbase.com/repositories
- title: Mullvad
description: Hosted VPN provider
icon: networking/mullvad.png
url: https://mullvad.net/en/account/
- title: ZeroTier
description: Secure networks between devices
icon: networking/zeroteir.png
url: https://my.zerotier.com/
- title: HealthChecks
description: Cron Job Monitoring
icon: networking/healthchecks.png
url: https://healthchecks.io/checks/
- title: ISP - Vodafone
description: Broadband internet provider
icon: networking/vodafone.png
url: https://myaccount.vodafone.co.uk/
- title: Digital Ocean
description: Cloud Hosting
icon: networking/digital-ocean.png
url: https://cloud.digitalocean.com/
- title: CloudFlare
description: Domain and DNS Management
icon: networking/cloudflare.png
url: https://dash.cloudflare.com/
- name: Other Devices
items:
- title: Modem
description: ISP Router Modem Combo
icon: ''
url: http://192.168.1.5
- title: Wireless Access Point
description: View clients connected to WiFi
icon: ''
url: http://192.168.1.109/info.php
- title: Fing
description: Monitor connectivity issues, ISP quality, health checks and troubleshooting
provider: Fing
icon: ''
url: https://app.fing.com/
- title: Switch
description: Manage VLANs on Ubiquity Ethernet switch
icon: ''
url: "#"
- name: External Utilities
displayData:
collapsed: true
items:
- title: Public IP
description: Check public IP and associated data
icon: ''
url: https://www.whatismyip.com/
- title: Who Is Lookup
description: Check ICAN info for a given IP address or domain
icon: ''
url: https://whois.domaintools.com/
- title: Speed Test
description: Upload + download speeds and latency
icon: ''
url: https://speed.cloudflare.com/
- title: Mullvad Check
description: Confirms a secure connection to Mullvad's WireGuard servers
icon: ''
url: https://mullvad.net/check