Quick Start

Welcome to Dashy! So glad you're here 😊 In a couple of minutes, you'll have your new dashboard up and running 🚀

TDLR; Run docker run -p 8080:80 lissy93/dashy, then open http://localhost:8080

1. Prerequisites

The quickest and easiest method of running Dashy is using Docker (or another container engine). You can find installation instructions for your system in the Docker Documentation. If you don't want to use Docker, then you can use one of Dashy's other supported installation methods instead, all of which are outlined in the Deployment Docs.

2. Installation

To pull the latest image, and build and start the app run:

docker run -d \
  -p 8080:80 \
  -v ~/my-conf.yml:/app/public/conf.yml \
  --name my-dashboard \
  --restart=always \
  lissy93/dashy:latest

Either replace the -v path to point to your config file, or leave it out. For a full list of available options, then see Dashy with Docker Docs. If you'd prefer to use Docker Compose, then see Dashy with Docker Compose Docs.

Your dashboard should now be up and running at http://localhost:8080 (or your servers IP address/ domain, and the port that you chose). The first time you build, it may take a few minutes.

3. Configure

Now that you've got Dashy running, you are going to want to set it up with your own content. Config is written in YAML Format, and saved in /public/conf.yml. The format on the config file is pretty straight forward. There are three root attributes:

pageInfo - Dashboard meta data, like title, description, nav bar links and footer text
appConfig - Dashboard settings, like themes, authentication, language and customization
sections - An array of sections, each including an array of items

You can view a full list of all available config options in the Configuring Docs.

pageInfo:
  title: Home Lab
sections: # An array of sections
- name: Example Section
  icon: far fa-rocket
  items:
  - title: GitHub
    description: Dashy source code and docs
    icon: fab fa-github
    url: https://github.com/Lissy93/dashy
  - title: Issues
    description: View open issues, or raise a new one
    icon: fas fa-bug
    url: https://github.com/Lissy93/dashy/issues
- name: Local Services
  items:
  - title: Firewall
    icon: favicon
    url: http://192.168.1.1/
  - title: Game Server
    icon: https://i.ibb.co/710B3Yc/space-invader-x256.png
    url: http://192.168.130.1/

Notes:

You can use a Docker volume to pass a config file from your host system to the container
- E.g. -v ./host-system/my-local-conf.yml:/app/public/conf.yml
It's also possible to edit your config directly through the UI, and changes will be saved in this file
Check your config against Dashy's schema, with docker exec -it [container-id] yarn validate-config
You might find it helpful to look at some examples, a collection of which can be found here
After editing your config, the app will rebuild in the background, which may take a minute

4. Further Customisation

Once you've got Dashy setup, you'll want to ensure the container is properly healthy, secured, backed up and kept up-to-date. All this is covered in the Management Docs.

You might also want to check out the docs for specific features you'd like to use:

Authentication - Setting up authentication to protect your dashboard
Backup & Restore - Guide to Dashy's cloud sync feature
Icons - Outline of all available icon types for sections and items
Localisation - How to change language, or add your own
Status Indicators - Using Dashy to monitor uptime and status of your apps
Theming - Complete guide to applying, writing and modifying themes and styles

5. Final Note

If you're enjoying Dashy, and have a few minutes to spare, please do take a moment to look at the Contributing Page. There are a few things that we really need some help with, and whatever your skill set, there are ways you can help out. Any contributions, however small would be greatly appreciated. Thank you to everyone who is already doing so, without developing and maintaining Dashy would not have been so possible.

You can also consider sharing your dashboard in the Showcase, to help provide inspiration for others.

For more info, check out the Documentation. If you've got any questions feel free to ask in the Discussion, and if you think you've found a bug you can raise an issue to get it fixed.

Enjoy your dashboard :)

Alternative Deployment Method 1 - From Source

You can also easily run the app on your system without Docker. For this Git, Node.js, and Yarn are required.

git clone https://github.com/Lissy93/dashy.git && cd dashy
yarn # Install dependencies
yarn build # Build the app
yarn start # Start the app

Then edit ./public/conf.yml and rebuild the app with yarn build

Alternative Deployment Method 2 - Netlify

Don't have a server? No problem! You can run Dashy for free on Netlify (as well as many other cloud providers). All you need it a GitHub account.

Fork Dashy's repository on GitHub
Log in to Netlify with GitHub
Click "New site from Git" and select your forked repo, then click Deploy!
You can then edit the config in ./public/conf.yml in your repo, and Netlify will rebuild the app

6.6 KiB Raw Blame History