26 KiB
Dashy
Dashy helps you organize your self-hosted services, by making them all accessible from a single place
Features 🌈
- Instant search by name, domain and tags - just start typing
- Full keyboard shortcuts for navigation, searching and launching
- Multiple color themes, with easy method for adding more
- Easy to customize every part of your dashboard, layout, icon sizes and colors etc
- Many options for icons, including full Font-Awesome support and the ability to auto-fetch icon from URLs favicon
- Option to show service status for each of your apps / links, for basic availability and uptime monitoring
- Multiple ways of opening apps, either in your browser, a pop-up modal or workspace view
- Option for full-screen background image, custom nav-bar links, html footer, title, and more
- Encrypted cloud backup and restore feature available
- Optional authentication, requiring user to log in
- Easy single-file YAML-based configuration
- Small bundle size, fully responsive UI and PWA makes the app easy to use on any device
- Plus lots more...
Demo ⚡
For more examples of Dashy in action, see: The Showcase
Live Demos
Spin up your own Demo
- 1-Click Deploy:
- Or on your own machine:
docker run -p 8080:80 lissy93/dashy
Recording
User Showcase
Are using Dashy? Want to share your dashboard here too - Submit your Screenshots to the Showcase!
Getting Started 🛫
For full setup instructions, see: Deployment
Deploying from Docker Hub 🐳
You will need Docker installed on your system
docker run -p 8080:80 lissy93/dashy
Or
docker run -d \
-p 4000:80 \
-v /root/my-local-conf.yml:/app/public/conf.yml \
--name my-dashboard \
--restart=always \
lissy93/dashy:latest
You can also build the Docker container from source, by cloning the repo, cd'ing into it and running docker build . and docker compose up.
Deploying from Source 🚀
You will need both git and the latest or LTS version of Node.js installed on your system
- Get Code:
git clone git@github.com:Lissy93/dashy.gitandcd dashy - Configuration: Fill in you're settings in
./public/conf.yml - Install dependencies:
yarn - Build:
yarn build - Run:
yarn start
Deploy to the Cloud
Dashy supports 1-Click deployments on several popular cloud platforms. To get started, just click a link below:
Basic Commands
The following commands can be run on Dashy.
yarn build- Builds the project for production, and outputs it into./distyarn start- Starts a web server, and serves up the production site from./distyarn validate-config- Parses and validates yourconf.ymlagainst Dashy's schemayarn health-check- Checks the health and status of Dashy's Node serveryarn pm2-start- Starts the app using the PM2 process manageryarn dev- Starts the development server with hot reloading, linting, testing and verbose messagingyarn lint- Lints code to ensure it follows a consistent neat styleyarn test- Runs tests, and outputs resultsyarn install- Install all dependencies
If you are using Docker, than precede each command with docker exec -it [container-id], where container id can be found by running docker ps, e.g. docker exec -it 92490c12baff yarn build.
If you prefer NPM, then just replace yarn with npm run in the following commands.
In Docker, healthchecks are pre-configured to monitor the uptime and response times of Dashy, and the status of which will show in your Docker monitoring app, or the docker ps command, or the container logs, using: docker inspect --format "{{json .State.Health }}" [container-id].
Configuring 🔧
For full configuration documentation, see: Configuring
Dashy is configured with a single YAML file, located at ./public/conf.yml (or ./app/public/conf.yml for Docker). Any other optional user-customizable assets are also located in the ./public/ directory, e.g. favicon.ico, manifest.json, robots.txt and web-icons/*. If you are using Docker, the easiest way to method is to mount a Docker volume (e.g. -v /root/my-local-conf.yml:/app/public/conf.yml)
In the production environment, the app needs to be rebuilt in order for changes to take effect. This should happen automatically, but can also be triggered by running yarn build, or docker exec -it [container-id] yarn build if you are using Docker (where container ID can be found by running docker ps).
You can check that your config matches Dashy's schema before deploying, by running yarn validate-config.
It is now possible also possible to update Dashy's config directly through the UI, and have changes written to disk. You can disable this feature by setting: appConfig.allowConfigEdit: false. If you are using users within Dashy, then you need to be logged in to a user of type: admin in order to modify the configuration globally. You can also trigger a rebuild of the app through the UI (Settings --> Rebuild).
You may find these example config helpful for getting you started
Theming 🎨
For full theming documentation, see: Theming
The app comes with a number of built-in themes, but it's also easy to write you're own. All colors, and most other CSS properties make use of CSS variables, which makes customizing the look and feel of Dashy very easy.
You can also apply custom CSS overrides directly through the UI (Under Config menu --> Custom CSS), or specify it in your config file under appConfig.customCss. If you have a lot of custom styles, you can pass in the path to a stylesheet, in appConfig.externalStyleSheet.
Icons 🧸
For full iconography documentation, see: Icons
Both sections and items can have an icon associated with them, and defined under the icon attribute. There are many options for icons, including Font Awesome support, automatic fetching from favicon, programmatically generated icons and direct local or remote URLs.
- Favicon: Set
icon: faviconto fetch a services icon automatically from the URL of the corresponding application - Font-Awesome: To use any font-awesome icon, specify the category, followed by the icon name, e.g.
fas fa-rocketorfab fa-monero. You can also use Pro icons if you have a license key, just set it underappConfig.fontAwesomeKey - Generative: Setting
icon: generative, will generate a unique for a given service, based on it's URL or IP - Emoji: Use an emoji as a tile icon, by putting the emoji's code as the icon attribute. Emojis can be specified either as emojis (
🚀), unicode ('U+1F680') or shortcode (':rocket:'). - URL: You can also pass in a URL to an icon asset, hosted either locally or using any CDN service. E.g.
icon: https://i.ibb.co/710B3Yc/space-invader-x256.png. - Local Image: To use a local image, store it in
./public/item-icons/(or create a volume in Docker:-v /local/image/directory:/app/public/item-icons/) , and reference it by name and extension - e.g. seticon: image.pngto use./public/item-icon/image.png. You can also use sub-folders here if you have a lot of icons, to keep them organized.
Cloud Backup & Sync ☁
For full backup documentation, see: Cloud Backup & Sync
Dashy has an optional built-in feature for securely backing up your config to a hosted cloud service, and then restoring it on another instance. This feature is totally optional, and if you do not enable it, then Dashy will not make any external network requests.
This is useful not only for backing up your configuration off-site, but it also enables Dashy to be used without having write a YAML config file, and makes it possible to use a public hosted instance, without the need to self-host.
All data is encrypted before being sent to the backend. In Dashy, this is done in CloudBackup.js, using crypto.js's AES method, using the users chosen password as the key. The data is then sent to a Cloudflare worker (a platform for running serverless functions), and stored in a KV data store.
Authentication 💂
For full authentication documentation, see: Authentication
Dashy has a built-in login feature, which can be used for basic access control. To enable this feature, add an auth attribute under appConfig, containing an array of users, each with a username, SHA-256 hashed password and optional user type.
appConfig:
auth:
- user: alicia
hash: 4D1E58C90B3B94BCAD9848ECCACD6D2A8C9FBC5CA913304BBA5CDEAB36FEEFA3
At present, access control is handled on the frontend, and therefore in security-critical situations, it is recommended to use an alternate method for authentication, such as Authelia, a VPN or web server and firewall rules.
Status Indicators 🚦
For full monitoring documentation, see: Status Indicators
Dashy has an optional feature that can display a small icon next to each of your running services, indicating it's current status. This is useful if you are using Dashy as your homelab's start page, as it gives you an overview of the health of each of your running services. Hovering over the indicator will show additional information, including average response time and an error message for services which are down.
By default, this feature is off, but you can enable it globally by setting appConfig.statusCheck: true, or enable/ disable it for an individual item, with item[n].statusCheck. You can also specify an time interval in seconds under appConfig.statusCheckInterval, which will determine how often to recheck services, if this value is 0, then status is only checked on initial page load, this is default behavior.
Opening Methods 🖱️
One of the primary purposes of Dashy is to make launching commonly used apps and services as quick as possible. To aid in this, there are several different options on how items can be opened. You can configure your preference by setting the target property of any item, to one of the following values:
sametab- The app will be launched in the current tabnewtab- The app will be launched in a new tabmodal- Launch app in a resizable/ movable popup modal on the current pageworkspace- Changes to Workspace view, and launches app
Even if the target is not set (or is set to sametab), you can still launch any given app in an alternative method: Alt + Click will open the modal, and Ctrl + Click will open in a new tab. You can also right-click on any item to see all options (as seen in the screenshot below). This custom context menu can be disabled by setting appConfig.disableContextMenu: true.
The modal and workspace views work by rendering the target application in an iframe. For this to work, the HTTP response header X-Frame-Options for a given application needs to be set to ALLOW. If you are getting a Refused to Connect error then this header is set to DENY (or SAMEORIGIN and it's on a different host).
Here's a quick demo of the workspace view:
Config Editor ⚙️
From the Settings Menu in Dashy, you can download, backup, edit and rest your config. An interactive editor makes editing the config file easy, it will tell you if you've got any errors. After making your changes, you can either apply them locally, or export into your main config file. After saving to the config file to the disk, the app will need to be rebuilt. This will happen automatically, but may take a few minutes. You can also manually trigger a rebuild from the Settings Menu. A full list of available config options can be found here. It's recommend to make a backup of your configuration, as you can then restore it into a new instance of Dashy, without having to set it up again. json2yaml is very useful for converting between YAML to JSON and visa versa.
Developing 🧱
For full development documentation, see: Developing
- Get Code:
git clone git@github.com:Lissy93/dashy.gitandcd dashy - Install dependencies:
yarn - Start dev server:
yarn dev
Hot reload is enabled, so changes will be detected automatically, triggering the app to be rebuilt and refreshed. Ensure that all lint checks and tests are passing before pushing an code or deploying the app.
If you are new to Vue.js or web development and want to learn more, here are some resources to help get you started. Dashy is a pretty straight-forward application, so would make an ideal candidate for your first PR!
Contributing 😇
For full contributing guide, see: Contributing
Pull requests are welcome, and would by much appreciated!
Some ideas for PRs include: bug fixes, improve the docs, submit a screenshot of your dashboard to the showcase, 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
Repo Status
Support 🙋♀️
For general discussions, the Discussions Board is now active!
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.
For more general questions about any of the technologies used, StackOverflow may be more helpful first port of info
If you need to get in touch securely with the author (me, Alicia Sykes), drop me a message at:
- Email:
alicia at omg dot lol - Public Key
0688 F8D3 4587 D954 E9E5 1FB8 FEDB 68F5 5C02 83A7
Documentation 📘
- Deployment
- Configuring
- Developing
- Contributing
- User Guide
- Troubleshooting
- Backup & Restore
- Status Indicators
- Theming
- Icons
- Authentication
- Showcase
Credits 🏆
Contributors 👥
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
At it's core, the application uses Vue.js, as well as it's services. Styling is done with SCSS, JavaScript is currently Babel, (but I am in the process of converting to TypeScript), linting is done with ESLint, the config is defined in YAML, and there is a simple Node.js server to serve up the static app.
Frontend Components
vue-select- Dropdown component by @sagalbotMITvue-js-modal- Modal component by @euvlMITv-tooltip- Tooltip component by @AkryumMITvue-material-tabs- Tab view component by @jairoblattMITVJsoneditor- Interactive JSON editor component by @yansenleiMIT- Forked from
JsonEditorby @josdejongApache-2.0 License
- Forked from
vue-toasted- Toast notification component by @shakee93MITvue-prism-editor- Lightweight code editor by @kocaMIT- Forked from
prism.jsMIT
- Forked from
Utilities
crypto-js- Encryption implementations by @evanvosberg and communityMITaxios- Promise based HTTP client by @mzabriskie and communityMITajv- JSON schema Validator by @epoberezkin and communityMIT
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 using KV and web crypto
External Services
The 1-Click deploy demo uses Play-with-Docker Labs. Code is hosted on GitHub, Docker image is hosted on DockerHub, and the demos are hosted on Netlify.
Alternatives 🙌
There are a few self-hosted web apps, that serve a similar purpose to Dashy. If you're looking for a dashboard, and Dashy doesn't meet your needs, I highly recommend you check these projects out!
HomeDash2, Homer (Apache License 2.0), Organizr (GPL-3.0 License) and Heimdall (MIT License)
License 📜
Copyright © 2021 Alicia Sykes <https://aliciasykes.com>
Permission is hereby granted, free of charge, to any person obtaining a copy of this
software and associated documentation files (the “Software”), to deal in the Software
without restriction, including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWAREOR THE USE
OR OTHER DEALINGS IN THE SOFTWARE.
TDLR; You can do whatever you like with Dashy: use it in private or commercial settings, redistribute and modify it. But you must display this license and credit the author. There is no warranty that this app will work as expected, and the author cannot be held liable for anything that goes wrong. For more info, see TLDR Legal's Explanation of MIT
