diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index a140b00e..98f2ab52 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -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 diff --git a/README.md b/README.md index 27ca47d4..e58ed420 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@

+ ## 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 🙌 diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000..3b46d0aa --- /dev/null +++ b/docs/contributing.md @@ -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// + # Navigate to the newly cloned directory + cd + # Assign the original repo to a remote called "upstream" + git remote add upstream https://github.com/hoodiehq/ + ``` + +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 + ``` + +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 + ``` + +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) + diff --git a/docs/readme.md b/docs/readme.md index 13007485..1f9607fc 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -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) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..ea81a751 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,2 @@ + +Coming Soon... \ No newline at end of file diff --git a/docs/user-guide.md b/docs/user-guide.md new file mode 100644 index 00000000..9c4ae7f5 --- /dev/null +++ b/docs/user-guide.md @@ -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. + + diff --git a/public/conf.yml b/public/conf.yml index 99c1cd80..bfd2ea04 100644 --- a/public/conf.yml +++ b/public/conf.yml @@ -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