From db59cad38eb6b278521a7ac41faae9fb5b39c3cb Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Sat, 23 May 2026 15:03:40 +0100 Subject: [PATCH 1/8] =?UTF-8?q?=F0=9F=93=9D=20Formatting=20for=20readme?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 67 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 36 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 9412040fd7..971acb004d 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,41 @@

Dashy

- Dashy helps you organize your self-hosted services by making them accessible from a single place + The most customizable dashboard for self-hosters
+ Dashy is the homepage for your homelab

User Showcase | Live Demo | Getting Started | Documentation | GitHub

---- - -

-Dashy is kindly sponsored by SSD Nodes - Affordable VPS hosting for self-hosters
- - SSD Nodes - -

- -

-
-Dashy is kindly sponsored by Umbrel - the personal home cloud and OS for self-hosting
- - - -

- -

-Dashy is kindly sponsored by TestMu AI - The worldโ€™s first full-stack Agentic AI Quality Engineering platform
- - LambdaTest - -

+

Kindly sponsored by

+ + + + + + + +
+ + SSD Nodes
+ SSD Nodes +
+ Affordable VPS hosting for self-hosters + 		+ + Umbrel
+ Umbrel +
+ Personal home cloud and OS for self-hosting + 		+ + TestMu AI
+ TestMu AI +
+ Full-stack Agentic AI Quality Engineering platform +
Table of Contents @@ -424,7 +429,7 @@ Dashy supports multiple languages and locales. When available, your language sho - ๐Ÿ‡ฆ๐Ÿ‡ช **Arabic**: `ar` - Contributed by **[@kayedspace](https://github.com/kayedspace)** - ๐Ÿ‡ง๐Ÿ‡ฉ **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)** +- ๐Ÿ‡จ๐Ÿ‡ณ **Chinese**: `zh-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)** @@ -440,11 +445,11 @@ Dashy supports multiple languages and locales. When available, your language sho - ๐Ÿ‡ณ๐Ÿ‡ด **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)** +- ๐Ÿ‡ท๐Ÿ‡ด **Romanian**: `ro` - Contributed by **[@z3r0l1nk](https://github.com/z3r0l1nk)** - ๐Ÿ›ฐ๏ธ **Galician**: `gl` - Contributed by **[@pvillaverde](https://github.com/pvillaverde)** -- ๐Ÿ‡ท๐Ÿ‡บ **Russian**: `ru` -Contributed by **[@sasetz](https://github.com/sasetz)** +- ๐Ÿ‡ท๐Ÿ‡บ **Russian**: `ru` - Contributed by **[@sasetz](https://github.com/sasetz)** - ๐Ÿ‡ธ๐Ÿ‡ฐ **Slovak**: `sk` - Contributed by **[@Smexhy](https://github.com/Smexhy)** - ๐Ÿ‡ธ๐Ÿ‡ฎ **Slovenian**: `sl` - Contributed by **[@UrekD](https://github.com/UrekD)** -- ๐Ÿ‡ฐ๐Ÿ‡ฌ **Kyrgyz**: `ky` - Contributed by **[@noblepower1337](https://github.com/noblepower1337)** - ๐Ÿ‡ช๐Ÿ‡ธ **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)** @@ -489,9 +494,9 @@ pages: ## System Requirements ๐Ÿ“Š -If running on bare metal, Dashy requires [Node](https://nodejs.org/en/) V 18.0.0 or later, LTS (20.x) is recommended. +If running on bare metal, Dashy requires [Node](https://nodejs.org/en/) V 20.0.0 or later, LTS (22.x) is recommended. -If running in Docker container, the recommended base image is Alpine (3.19) +If running in Docker container, the recommended base image is Alpine (3.21) The hardware requirements vary depending on where and how you are running Dashy. Generally speaking, on a bare-metal system or Docker container, 1GB of memory should be more than enough, and depending on whether you are using your own assets, then 1GB of disk space should be sufficient. @@ -658,7 +663,7 @@ A few self-hosted web apps serve a similar purpose to Dashy. If you're looking f Dashy is Licensed under [MIT X11](https://en.wikipedia.org/wiki/MIT_License) ``` -Copyright ยฉ 2021-2024 Alicia Sykes +Copyright ยฉ Alicia Sykes 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 @@ -695,7 +700,7 @@ For more info, see TLDR Legal's [Explanation of MIT](https://tldrlegal.com/licen

- ยฉ Alicia Sykes 2024
+ ยฉ Alicia Sykes 2019 - 2026
Licensed under MIT

Thanks for visiting :) From 6306fa6dea9168861c9a2257888d3ddaa133fada Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Sat, 23 May 2026 15:03:52 +0100 Subject: [PATCH 2/8] =?UTF-8?q?=F0=9F=93=9D=20Update=20page=20titles=20for?= =?UTF-8?q?=20auth=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/authentication/authelia-oidc.md | 2 +- docs/authentication/authentik.md | 2 +- docs/authentication/cloudflare-tunnel.md | 2 +- docs/authentication/keycloak.md | 2 +- docs/authentication/pocketid.md | 2 +- docs/authentication/tailscale.md | 2 +- docs/authentication/zitadel.md | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/authentication/authelia-oidc.md b/docs/authentication/authelia-oidc.md index 5cce307927..5cfa67459f 100644 --- a/docs/authentication/authelia-oidc.md +++ b/docs/authentication/authelia-oidc.md @@ -1,4 +1,4 @@ -# Authelia Authentication for Dashy +# Authelia OIDC Dashy supports using [Authelia](https://www.authelia.com/) as its OIDC provider. diff --git a/docs/authentication/authentik.md b/docs/authentication/authentik.md index 8d5cdaf4c8..d9d1111c9e 100644 --- a/docs/authentication/authentik.md +++ b/docs/authentication/authentik.md @@ -1,4 +1,4 @@ -# Authentik Authentication for Dashy +# Authentik OIDC Dashy supports using [Authentik](https://goauthentik.io/) as its OIDC provider. diff --git a/docs/authentication/cloudflare-tunnel.md b/docs/authentication/cloudflare-tunnel.md index 3a5986e99e..db79962cce 100644 --- a/docs/authentication/cloudflare-tunnel.md +++ b/docs/authentication/cloudflare-tunnel.md @@ -1,4 +1,4 @@ -# Cloudflare Tunnel + Access for Dashy +# Cloudflare Tunnel Dashy works well behind [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) with [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/policies/access/) doing auth at the edge. This is one of the most common ways to expose a homelab dashboard to the public internet without opening any inbound ports, without managing TLS, and without standing up your own identity provider. diff --git a/docs/authentication/keycloak.md b/docs/authentication/keycloak.md index 30bc0e240f..9a38722afe 100644 --- a/docs/authentication/keycloak.md +++ b/docs/authentication/keycloak.md @@ -1,4 +1,4 @@ -# Keycloak Authentication for Dashy +# Keycloak Dashy supports using a [Keycloak](https://www.keycloak.org/) (V17+) authentication server. diff --git a/docs/authentication/pocketid.md b/docs/authentication/pocketid.md index 7195043383..0ef9c828e6 100644 --- a/docs/authentication/pocketid.md +++ b/docs/authentication/pocketid.md @@ -1,4 +1,4 @@ -# Pocket ID Authentication for Dashy +# Pocket ID OIDC Dashy supports using [Pocket ID](https://pocket-id.org/) as its OIDC provider. diff --git a/docs/authentication/tailscale.md b/docs/authentication/tailscale.md index 772e95d198..8420e34011 100644 --- a/docs/authentication/tailscale.md +++ b/docs/authentication/tailscale.md @@ -1,4 +1,4 @@ -# Tailscale (and Headscale) for Dashy +# Tailscale [Tailscale](https://tailscale.com/) is a popular way to put Dashy on a private network you can reach from your phone, laptop, or any other device you've added to your tailnet, without exposing it to the public internet. With Tailscale Serve in front, requests reaching Dashy already carry the user's identity in HTTP headers, which plugs straight into Dashy's header auth for auto-login. diff --git a/docs/authentication/zitadel.md b/docs/authentication/zitadel.md index 061b146a83..54d14a80e2 100644 --- a/docs/authentication/zitadel.md +++ b/docs/authentication/zitadel.md @@ -1,4 +1,4 @@ -# Zitadel Authentication for Dashy +# Zitadel OIDC Dashy supports using [Zitadel](https://zitadel.com/) as its OIDC provider. From 876bc786fd673ea878051f3286d03e2c9b17951c Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Wed, 27 May 2026 22:54:11 +0100 Subject: [PATCH 3/8] =?UTF-8?q?=F0=9F=93=9D=20Updates=20links=20in=20readm?= =?UTF-8?q?e?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 37 +++++++++++++++---------------------- 1 file changed, 15 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 971acb004d..6bfe18f954 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,6 @@ - [๐Ÿ’– Supporting Dashy](#supporting-dashy-) - [๐Ÿ† Credits](#credits-) - [๐Ÿงฑ Developing](#developing-) - - [๐Ÿ—ž๏ธ Release Schedule](#release-schedule-) - [๐Ÿ“˜ Documentation](#documentation-) - [๐Ÿ›ฃ๏ธ Roadmap](#roadmap-) - [๐Ÿ™Œ Alternatives](#alternatives-) @@ -101,11 +100,11 @@ ## Demo โšก -**Live Instances**: [Demo 1](https://demo.dashy.to) (Live Demo) โ”† [Demo 2](https://live.dashy.to) (Dashy Links) โ”† [Demo 3](https://dev.dashy.to) (Dev Preview) +**Live Instances**: [Demo](https://demo.dashy.to) (Live Demo) โ”† [Dev Preview](https://dev.dashy.to) (Dev Preview) **Screenshots**: Checkout the [Showcase](./docs/showcase.md), to see example dashboards from the community -**Spin up your own demo**: [![One-Click Deploy with PWD](https://img.shields.io/badge/Play--with--Docker-Deploy-2496ed?style=flat-square&logo=docker)](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml) or [`docker run -p 8080:8080 lissy93/dashy`](./docs/quick-start.md) +**Try it yourself**: [`docker run -p 8080:8080 lissy93/dashy`](./docs/quick-start.md)

@@ -125,13 +124,13 @@ You will need [Docker](https://docs.docker.com/get-docker/) installed on your system -``` -docker run -p 8080:8080 lissy93/dashy +```bash +docker run -p 4000:8080 lissy93/dashy ``` Or -```docker +```bash docker run -d \ -p 4000:8080 \ -v /path/to/your/user-data:/app/user-data \ @@ -140,13 +139,13 @@ docker run -d \ lissy93/dashy:latest ``` -[![Dashy on Docker Hub](https://dockeri.co/image/lissy93/dashy)](https://hub.docker.com/r/lissy93/dashy) +To use with compose, see our sample [`docker-compose.yml`](https://github.com/lissy93/dashy/blob/master/docker-compose.yml). The mounted `/app/user-data` directory **must** contain at least a `conf.yml`. It can also hold sub-config files, item icons, fonts, custom CSS, or anything else you want served from the web root. -Dashy is also available via GHCR (`ghcr.io/lissy93/dashy`). -To use with compose, see our sample [`docker-compose.yml`](https://github.com/lissy93/dashy/blob/master/docker-compose.yml). +Dashy is distributed both on [DockerHub](https://hub.docker.com/r/lissy93/dashy) (`lissy93/dashy`) and [GHCR](https://github.com/lissy93/dashy/pkgs/container/dashy) (`ghcr.io/lissy93/dashy`). + You can either use `:latest` or pin to specific versions (like `4.0.0`). All images are multi-arch (works on amd64, arm64, and arm/v7). @@ -154,7 +153,7 @@ All images are multi-arch (works on amd64, arm64, and arm/v7). ### Deploying from Source ๐Ÿ”จ -You will need [git](https://git-scm.com/downloads), the latest or LTS version of [Node.js](https://nodejs.org/) and _(optionally)_ [Yarn](https://yarnpkg.com/) installed on your system. +You'll need Node (20+) installed, as well as git and `yarn` enabled. - Clone the Repo: `git clone https://github.com/Lissy93/dashy.git` and `cd dashy` - Configuration: Fill in your settings in `./user-data/conf.yml` @@ -162,15 +161,14 @@ You will need [git](https://git-scm.com/downloads), the latest or LTS version of - Build: `yarn build` - Run: `yarn start` -> See docs: [Full list of Dashy's commands](./docs/management.md#basic-commands) +> See docs: [Full list of Dashy's commands](./docs/management.md#running-commands) ### Deploy to the Cloud โ˜๏ธ Dashy supports **1-Click deployments** on several popular cloud platforms. To spin up a new instance, just click a link below: - [ Deploy to Netlify](https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy) -- [ Deploy to Heroku](https://heroku.com/deploy?template=https://github.com/Lissy93/dashy) - [ Deploy to Vercel](https://vercel.com/new/project?template=https://github.com/lissy93/dashy) -- [ Deploy to Render](https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render) +- [ Deploy to Render](https://render.com/deploy?repo=https://github.com/lissy93/dashy) - [ Deploy to Railway](https://railway.app/template/MtdjAQ?referralCode=app) - [ Deploy to GCP](https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git) - [ Deploy to PWD](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml) @@ -235,7 +233,7 @@ The following icon types are supported: [simple-icons]: https://simpleicons.org/ [material icons]: https://github.com/Templarian/MaterialDesign [selfh.st/icons]: https://selfh.st/icons -[dashboard-icons]: https://github.com/WalkxCode/dashboard-icons +[dashboard-icons]: https://github.com/homarr-labs/dashboard-icons

@@ -329,7 +327,7 @@ You can change the view from the UI, using the switch icon in the top-right corn > For full documentation on views and opening methods, see: [**Alternate Views**](./docs/alternate-views.md) -There are several different ways you can launch apps. You can specify the default opening method for any given item under the `target` attribute or set a site-wide default under `appConfig.defaultOpeningMethod`. Right-click on an item to item for all options. The following options are supported: +There are several different ways you can launch apps. You can specify the default opening method for any given item under the `target` attribute or set a site-wide default under `appConfig.defaultOpeningMethod`. Right-click on an item for all options. The following options are supported: - `sametab` - The app will be launched in the current tab - `newtab` - The app will be launched in a new tab (or use Ctrl + Click) - `modal` - Launch app in a resizable/ movable popup modal on the current page (or use Alt + Click) @@ -502,12 +500,7 @@ The hardware requirements vary depending on where and how you are running Dashy. If you are using one of the 1-click cloud deployment methods, serving the app through a CDN or using a static hosting provider, then there are no specific requirements, as the built app is just a series of static JS files, and so is very light-weight. -Dashy also wells run on low-powered ARM-based single board computers, such as a Raspberry Pi (tested on Pi 3) - -**Browser Support** -![Chrome](https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_48x48.png) | ![Firefox](https://raw.githubusercontent.com/alrra/browser-logos/master/src/firefox/firefox_48x48.png) | ![IE](https://raw.githubusercontent.com/alrra/browser-logos/master/src/edge/edge_48x48.png) | ![Opera](https://raw.githubusercontent.com/alrra/browser-logos/master/src/opera/opera_48x48.png) | ![Safari](https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_48x48.png) ---- | --- | --- | --- | --- | -Latest โœ” | Latest โœ” | 10+ โœ” | Latest โœ” | 6.1+ โŒ | +Dashy also runs well on low-powered ARM-based single board computers, such as a Raspberry Pi (tested on Pi 3) **[โฌ†๏ธ Back to Top](#dashy)** @@ -570,7 +563,7 @@ Huge thanks to the sponsors helping to support Dashy's development! > For full development documentation, see: [**Developing**](./docs/developing.md) -[![Open Project in VS Code](https://img.shields.io/badge/Open_in-VS_Code-863cfc?style=flat-square&logo=visualstudiocode)](https://open.vscode.dev/Lissy93/Dashy) +[![Open Project in VS Code](https://img.shields.io/badge/Open_in-VS_Code-863cfc?style=flat-square&logo=visualstudiocode)](https://vscode.dev/github/Lissy93/Dashy) [![Open in GitPod](https://img.shields.io/badge/Open_in-GitPod-ffae33?style=flat-square&logo=gitpod)](https://gitpod.io/#github.com/lissy93/dashy.git) [![Open in GitHub Code Spaces](https://img.shields.io/badge/Open_in-Code%20Spaces-131313?style=flat-square&logo=github)](https://github.dev/Lissy93/dashy) From 18ec091d12a404234eb4abe85c2f7fbe0fb8861f Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Wed, 27 May 2026 22:54:37 +0100 Subject: [PATCH 4/8] =?UTF-8?q?=F0=9F=93=9D=20Updates=20deployment=20guide?= =?UTF-8?q?s?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/deployment.md | 173 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 135 insertions(+), 38 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index a9cf29d52d..b15c059713 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -23,17 +23,27 @@ Once you've got Dashy up and running, you'll want to configure it with your own - [Using Docker Compose](#using-docker-compose) - [Podman](#podman) - [Portainer](#portainer) + - [Coolify](#coolify) + - [1Panel](#1panel) - [Kubernetes](#kubernetes) - [Unraid](#unraid) + - [Proxmox VE](#proxmox-ve) + - [TrueNAS SCALE](#truenas-scale) - [Home Server Platforms](#home-server-platforms) - [Synology NAS](#synology-nas) + - [Saltbox](#saltbox) - [Build from Source](#build-from-source) + - [Nix / NixOS](#nix--nixos) - [Deploy to Cloud Service](#deploy-to-cloud-service) - [Netlify](#netlify) - [Vercel](#vercel) + - [Render](#render) + - [Railway](#railway) + - [Google Cloud Run](#google-cloud-run) - [Easypanel](#easypanel) - [EdgeOne Pages](#edgeone-pages) - [Play-with-Docker](#play-with-docker) + - [Managed Hosting](#managed-hosting) - [Hosting with CDN](#hosting-with-cdn) - [Requirements](#requirements) - [System Requirements](#system-requirements) @@ -48,17 +58,17 @@ Once you've got Dashy up and running, you'll want to configure it with your own **Container Info**: [ ![Docker Supported Architecture](https://img.shields.io/badge/Architectures-amd64%20|%20arm32v7%20|%20arm64v8-6ba6e5) -![Docker Base Image](https://img.shields.io/badge/Base_Image-Alpine_3.19-6ba6e5) +![Docker Base Image](https://img.shields.io/badge/Base_Image-node%3A22--alpine-6ba6e5) ![Docker Hosted on](https://img.shields.io/badge/Hosted_on-DockerHub%20%26%20GHCR-6ba6e5) ](https://hub.docker.com/r/lissy93/dashy)
**Status**: -![Build Status](https://img.shields.io/github/actions/workflow/status/Lissy93/dashy/docker-build-publish.yml?label=Build&color=f4a966) +![Build Status](https://img.shields.io/github/actions/workflow/status/Lissy93/dashy/docker.yml?label=Build&color=f4a966) ![Docker Pulls](https://img.shields.io/docker/pulls/lissy93/dashy?color=ecb2f7) ![Docker Stars](https://img.shields.io/docker/stars/lissy93/dashy?color=f7f754&label=Docker%20Stars) ![Docker Image Size](https://img.shields.io/docker/image-size/lissy93/dashy/latest?color=1eea76) ![Docker Latest Version](https://img.shields.io/docker/v/lissy93/dashy/latest?color=a8d8ea&label=Latest%20Version) -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. +Dashy has a prebuilt 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. ```bash docker run -d \ @@ -79,7 +89,7 @@ Explanation of the above options: - `--restart=always` Spin up the container when the daemon starts, or after it has been stopped - `lissy93/dashy:latest` The image to run. Replace `:latest` with a specific version from the [tags](https://hub.docker.com/r/lissy93/dashy/tags) if needed -For all available options, and to learn more, see the [Docker Run Docs](https://docs.docker.com/engine/reference/commandline/run/) +For all available options, and to learn more, see the [Docker Run Docs](https://docs.docker.com/reference/cli/docker/container/run/) Dashy is also available through GHCR: `docker pull ghcr.io/lissy93/dashy:latest` @@ -158,9 +168,24 @@ Alternatively, go to Containers > Add container and use the image `lissy93/dashy --- +## Coolify + +[Coolify](https://coolify.io/) is a self-hostable PaaS (a Heroku/Netlify alternative). Dashy is available as a one-click service template: under **+ New Resource** > **Service**, search "Dashy" and deploy. It runs the full Docker image, so all features work. ([template source](https://github.com/coollabsio/coolify/blob/v4.x/templates/compose/dashy.yaml)) + +--- + +## 1Panel + +[1Panel](https://1panel.pro/) is a web-based Linux server management panel. Dashy is in its official App Store: open **App Store**, search "Dashy", click **Install**, and set the port. ([app page](https://1panel.pro/apps/dashy)) + +--- + ## Kubernetes -@vyrtualsynthese has written a Helm Chart for deploying with Kubernetes, available [here](https://github.com/vyrtualsynthese/selfhosted-helmcharts/tree/main/charts/dashy) +@vyrtualsynthese has written a Helm Chart for deploying with Kubernetes, available [here](https://github.com/vyrtualsynthese/selfhosted-helmcharts/tree/main/charts/dashy). + +> [!NOTE] +> This is a community chart and may lag behind the latest Dashy release โ€” check the image tag before deploying. --- @@ -172,14 +197,34 @@ If you'd prefer to set it up manually, go to Docker > Add Container and use `lis --- +## Proxmox VE + +The community-maintained [Proxmox VE Helper-Scripts](https://community-scripts.github.io/ProxmoxVE/) project has a script that spins up Dashy in its own LXC container. Run this in the Proxmox host shell: + +```bash +bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/dashy.sh)" +``` + +See the [script page](https://community-scripts.github.io/ProxmoxVE/scripts?id=dashy) for options. These scripts are community-run (not affiliated with Proxmox or Dashy), so give it a read before running. + +--- + +## TrueNAS SCALE + +Dashy is in the TrueNAS community apps catalog. Go to **Apps** > **Discover Apps**, search "Dashy", click **Install**, then set the web port and a host-path storage volume for `/app/user-data`. ([catalog entry](https://apps.truenas.com/catalog/dashy/)) + +Older setups may instead find Dashy via [TrueCharts](https://truecharts.org/charts/stable/dashy/), though TrueCharts is no longer integrated with TrueNAS and its chart may be outdated. + +--- + ## Home Server Platforms -Several self-hosting platforms include Dashy in their app stores, giving you a one-click install with a management UI: +Several self-hosting platforms let you install Dashy from an app store, with a management UI on top: -- [CasaOS](https://casaos.io/) - Has Dashy in its built-in app store -- [Cosmos Cloud](https://cosmos-cloud.io/) - Install Dashy from the marketplace -- [Umbrel](https://umbrel.com/) - Available in the Umbrel App Store -- [Runtipi](https://runtipi.io/) - Available in the Runtipi App Store +- [Runtipi](https://runtipi.io/) - In the official Runtipi App Store +- [Cosmos Cloud](https://cosmos-cloud.io/) - In the official Cosmos marketplace +- [CasaOS](https://casaos.io/) - Via the community [BigBear app store](https://github.com/bigbeartechworld/big-bear-casaos) (not the built-in IceWhale store) +- [Umbrel](https://umbrel.com/) - Via a [community app store](https://github.com/dennysubke/dennys-umbrel-app-store) (not the official Umbrel store) These all run Dashy as a Docker container under the hood, so configuration works the same way. You'll find your `conf.yml` in whichever directory the platform maps to `/app/user-data/`. @@ -187,19 +232,14 @@ These all run Dashy as a Docker container under the hood, so configuration works ## Synology NAS -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```. +On DSM 7.2 and later, Docker is provided by the **Container Manager** package: - > Note: Be careful to enter only lowercase, not uppercase letters. +1. Install **Container Manager** from the **Package Center**. +2. In **File Station**, create a folder for Dashy's config (e.g. `docker/dashy`) and put your `conf.yml` (plus any icons/assets) inside it. +3. In Container Manager, open **Registry**, search for `lissy93/dashy`, and download the `latest` tag. +4. Under **Container** > **Create**, pick the image, enable auto-restart, map a host port (e.g. `4000`) to container port `8080`, and mount your `docker/dashy` folder to `/app/user-data`. -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. +Alternatively, use Container Manager's **Project** feature with the [docker-compose.yml](https://github.com/Lissy93/dashy/blob/master/docker-compose.yml) above, or run it over SSH: ```bash docker run -d \ @@ -210,15 +250,25 @@ docker run -d \ lissy93/dashy:latest ``` -(Place your `conf.yml` and any sub-configs / icons / assets inside `/volume1/docker/dashy` on the host.) +Dashy should be reachable on your chosen port within a minute or two. -dashy should be up within 1-2min after you've started the install task procedure +--- + +## Saltbox + +[Saltbox](https://saltbox.dev/) (an Ansible-based server automation project) includes Dashy as a sandbox app. Once Saltbox is set up, install it with: + +```bash +sb install sandbox-dashy +``` + +See the [Saltbox Dashy docs](https://docs.saltbox.dev/sandbox/apps/dashy/) for details. --- ## Build from Source -If you do not want to use Docker, you can run Dashy directly on your host system. For this, you will need both [git](https://git-scm.com/downloads) and the latest or LTS version of [Node.js](https://nodejs.org/) installed, and optionally [yarn](https://yarnpkg.com/) +If you do not want to use Docker, you can run Dashy directly on your host system. For this, you will need both [git](https://git-scm.com/downloads) and [Node.js](https://nodejs.org/) (v20 or newer) installed, and optionally [yarn](https://yarnpkg.com/) 1. Get Code: `git clone https://github.com/Lissy93/dashy.git` and `cd dashy` 2. Configuration: Fill in your settings in `./user-data/conf.yml` @@ -228,6 +278,18 @@ If you do not want to use Docker, you can run Dashy directly on your host system --- +## Nix / NixOS + +Dashy is packaged in [nixpkgs](https://search.nixos.org/packages?query=dashy-ui) as `dashy-ui`, and NixOS ships a `services.dashy` module. Enable it in your configuration: + +```nix +services.dashy.enable = true; +``` + +See the [module options](https://search.nixos.org/options?query=services.dashy) for setting the port and your config. Or run it ad-hoc with `nix run nixpkgs#dashy-ui`. Note the packaged version can lag behind the latest Dashy release. + +--- + ## Deploy to Cloud Service Dashy can be deployed to most cloud providers. The Docker guides above work on any VPS, but these providers offer quicker setup for static or containerized deployments. @@ -251,14 +313,41 @@ Deploy link: `https://app.netlify.com/start/deploy?repository=https://github.com Deploy link: `https://vercel.com/new/project?template=https://github.com/lissy93/dashy` +### Render + +[![Deploy to Render](https://img.shields.io/badge/Deploy-Render-46E3B7?logo=render&logoColor=white)](https://render.com/deploy?repo=https://github.com/lissy93/dashy) + +[Render](https://render.com/) runs the full Docker image, so status checks and config writing work. It builds from the [`render.yaml`](https://github.com/Lissy93/dashy/blob/master/render.yaml) blueprint at the repo root. + +Deploy link: `https://render.com/deploy?repo=https://github.com/lissy93/dashy` + +### Railway + +[![Deploy on Railway](https://img.shields.io/badge/Deploy-Railway-0B0D0E?logo=railway&logoColor=white)](https://railway.app/template/MtdjAQ?referralCode=app) + +[Railway](https://railway.com/) deploys the Dashy container from a template, with a free starter tier. + +Template: `https://railway.app/template/MtdjAQ` + +### Google Cloud Run + +[![Run on Google Cloud](https://img.shields.io/badge/Deploy-Cloud_Run-4285F4?logo=googlecloud&logoColor=white)](https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git) + +[Cloud Run](https://cloud.google.com/run) runs the container serverlessly. The button opens Google Cloud Shell and builds from the repo's `Dockerfile`. + +Deploy link: `https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git` + ### Easypanel -[![Deploy to Easypanel](https://img.shields.io/badge/Deploy-Easypanel-5765F2?logo=data:image/svg+xml;base64,&logoColor=white)](https://easypanel.io/docs/templates/dashy) +[![Deploy to Easypanel](https://img.shields.io/badge/Deploy-Easypanel-5765F2)](https://easypanel.io/docs/templates/dashy) [Easypanel](https://easypanel.io) is a self-hosted server control panel with a Dashy template. It runs the full Docker image, so all features including the Node server work. Template: `https://easypanel.io/docs/templates/dashy` +> [!NOTE] +> The Easypanel template currently pins an older Dashy version. After deploying, change the image tag to `lissy93/dashy:latest` (or a recent version) to get the newest release. + ### EdgeOne Pages [![Deploy to EdgeOne](https://cdnstatic.tencentcs.com/edgeone/pages/deploy.svg)](https://edgeone.ai/pages/new?repository-url=https://github.com/lissy93/dashy) @@ -269,6 +358,9 @@ Deploy link: `https://edgeone.ai/pages/new?repository-url=https://github.com/lis ### Play-with-Docker +> [!WARNING] +> Play-with-Docker is being retired and now shows a deprecation notice, so it may stop working. Treat it as a throwaway demo only, and use another method for anything real. + [![Try in PWD](https://img.shields.io/badge/Try-Play_with_Docker-0db7ed?logo=docker&logoColor=white)](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/) gives you a free, temporary Docker environment in the browser. Good for trying Dashy without installing anything. Sessions last 4 hours. @@ -277,6 +369,15 @@ URL: `https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com --- +## Managed Hosting + +If you'd rather not self-host, a couple of providers will run a Dashy instance for you (paid): + +- [Elestio](https://elest.io/open-source/dashy) - Fully managed Dashy, or bring your own VM +- [PikaPods](https://www.pikapods.com/) - Managed Dashy hosting from a few dollars per month + +--- + ## Hosting with CDN 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. @@ -287,26 +388,22 @@ However without Dashy's node server, there are a couple of features that will be ## Requirements -### System Requirements - -Dashy works well on a Raspberry Pi (tested on Pi 3 and later), but should also run well on any system. - -### Docker +### Architecture +The pre-built Docker image runs on `amd64`, `arm64` and `armv7` (`armv6` is not supported). -The initial build causes a spike in resource usage, but once running it's fairly steady. Minimum 1GB memory and 1GB disk space. +### System Resources +- CPU: any single core, x86-64 or ARM +- RAM: Node server idles around ~80โ€“120 MB; 256 MB is comfortable, works in less +- Disk: ~250 MB for the image + whatever your config/icons need +- Runs fine on a Pi 3 and up ### Bare Metal - -Requires [Node.js](https://nodejs.org/) and [Yarn](https://yarnpkg.com/). The `engines` field in `package.json` specifies `>=18.0.0`, but the Docker image is built and tested on Node 24, so that's the recommended version for bare-metal too. - -Minimum 512MB memory, 2GB disk space. +Requires [Node.js](https://nodejs.org/) (20+) and [Yarn](https://yarnpkg.com/) ### CDN / Cloud Deploy - No specific requirements. The built app (without the Node server) is very lightweight and can be served by any static host or CDN. If you're using custom icons or other assets, additional disk space will be needed. ### Browser Support - JavaScript is required. Dashy targets browsers with >1% global usage and the last 2 versions of each (via [browserslist](https://browsersl.ist/)). In practice, any modern browser works fine. Internet Explorer is not supported. | Browser | Minimum Version | Status | @@ -314,7 +411,7 @@ JavaScript is required. Dashy targets browsers with >1% global usage and the las | Chrome / Chromium | 90+ | Fully supported | | Firefox | 90+ | Fully supported | | Edge | 90+ | Fully supported | -| Safari | 14+ | Supported | +| Safari | 14+ | Mostly Supported | | Opera | 76+ | Supported | | Samsung Internet | 15+ | Supported | | Firefox ESR | Latest | Supported | From fac65c18fd5633ed5e5a5470da22aa56b4e31e8b Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Thu, 28 May 2026 09:51:48 +0100 Subject: [PATCH 5/8] =?UTF-8?q?=F0=9F=9A=80=20Deployment=20blueprint=20for?= =?UTF-8?q?=20render?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- render.yaml | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 render.yaml diff --git a/render.yaml b/render.yaml new file mode 100644 index 0000000000..1f54fc5c30 --- /dev/null +++ b/render.yaml @@ -0,0 +1,21 @@ +# Render Blueprint https://render.com/docs/blueprint-spec +# One-click deploy: https://render.com/deploy?repo=https://github.com/lissy93/dashy +# Builds the repo's Dockerfile and runs the full Node server, so status checks work. +services: + - type: web + name: dashy + runtime: docker + dockerfilePath: ./Dockerfile + # Free tier spins down when idle. Bump to a paid plan for always-on + plan: free + healthCheckPath: / + # Render's filesystem is wiped on each redeploy, so config saved via the UI won't + # persist. To keep it, use a paid plan and uncomment the disk below (Dashy keeps + # its conf.yml and assets in /app/user-data) + # disk: + # name: dashy-user-data + # mountPath: /app/user-data + # sizeGB: 1 + envVars: + - key: NODE_ENV + value: production From f97e66de75286941b26a86b23029975b30d977bd Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Thu, 28 May 2026 09:59:23 +0100 Subject: [PATCH 6/8] =?UTF-8?q?=F0=9F=8E=A8=20Editor=20config=20for=20code?= =?UTF-8?q?=20style?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .editorconfig | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) diff --git a/.editorconfig b/.editorconfig index 9fb14436da..8c52ff9378 100644 --- a/.editorconfig +++ b/.editorconfig @@ -1,24 +1,12 @@ root = true -# Basics - All Files [*] -end_of_line = lf charset = utf-8 -insert_final_newline = true - -# JS, TS and Vue -[*.{js,jsx,ts,tsx,vue}] +end_of_line = lf indent_style = space indent_size = 2 -trim_trailing_whitespace = true insert_final_newline = true +trim_trailing_whitespace = true -# YAML, for config file -[*.{yml,yaml}] -indent_size = 2 - -# Markdown for docs [*.md] trim_trailing_whitespace = false - -# Licensed under MIT, (C) 2024 Alicia Sykes \ No newline at end of file From f5565f84934a239c9eb66afd8da51ad9735efb9a Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Thu, 28 May 2026 12:14:54 +0100 Subject: [PATCH 7/8] =?UTF-8?q?=F0=9F=93=9D=20Documents=20new=20release=20?= =?UTF-8?q?process?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/release-workflow.md | 354 ++++++++++++++++++++------------------- 1 file changed, 178 insertions(+), 176 deletions(-) diff --git a/docs/release-workflow.md b/docs/release-workflow.md index 9181482b0c..a03edc9c15 100644 --- a/docs/release-workflow.md +++ b/docs/release-workflow.md @@ -1,176 +1,178 @@ - -# Releases and Workflows - -- [Release Schedule](#release-schedule) -- [Deployment Process](#deployment-process) -- [Git Strategy](#git-strategy) -- [Automated Workflows](#automated-workflows) -- [Release Pipeline](#release-pipeline) - -## Release Schedule - -We're using [Semantic Versioning](https://semver.org/), to indicate major, minor and patch versions. You can find the current version number in the readme, and check your apps version under the config menu. The version number is pulled from the [package.json](https://github.com/Lissy93/dashy/blob/master/package.json#L3) file. - -Typically there is a new major release every 2 weeks, usually on Sunday, and you can view these under the [Releases Page](https://github.com/Lissy93/dashy/releases). Each new version will also have a corresponding [tag on GitHub](https://github.com/Lissy93/dashy/tags), and each major release will also result in the creation of a new [tag on DockerHub](https://hub.docker.com/r/lissy93/dashy/tags), so that you can fix your container to a certain version. - -For a full breakdown of each change, you can view the [Updates Page](https://dashy.to/updates/). Each new feature or significant change needs to be submitted through a pull request, which makes it easy to review and track these changes, and roll back if needed. - ---- - -## Deployment Process - -All changes and new features are submitted as pull requests, which can then be tested, reviewed and (hopefully) merged into the master branch. Every time there is a change in the major version number, a new release is published. This usually happens every 2 weeks, on a Sunday. - -When a PR is opened: - -- A series of CI checks run against the new code (lint, test, build, Docker smoke test, security audit). The PR cannot be merged if any required check fails -- If `yarn.lock` was modified, Liss-Bot adds a comment summarising which packages changed - -After the PR is merged into master: - -- If code files changed and the version in package.json wasn't already bumped, the patch version is auto-incremented and committed ([bump-and-tag.yml](https://github.com/Lissy93/dashy/blob/master/.github/workflows/bump-and-tag.yml)) -- A git tag is created and pushed for the new version -- The tag push triggers Docker image builds for `linux/amd64`, `linux/arm64` and `linux/arm/v7`, published to both DockerHub and GHCR ([docker-build-publish.yml](https://github.com/Lissy93/dashy/blob/master/.github/workflows/docker-build-publish.yml)) -- If the tag is a major or minor version bump, a draft GitHub release is created with auto-generated release notes ([draft-release.yml](https://github.com/Lissy93/dashy/blob/master/.github/workflows/draft-release.yml)). Patch-only bumps skip the release - -Manual tagging is also available via the [manual-tag.yml](https://github.com/Lissy93/dashy/blob/master/.github/workflows/manual-tag.yml) workflow. You can either provide a specific version (e.g. `3.2.0`) or leave it empty to auto-bump the patch version. This is useful if the automated flow didn't trigger or you need to cut a release outside the normal PR flow. - ---- - -## 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) -2. Code some awesome stuff, then add and commit your changes -3. Create a Pull Request, complete the checklist and ensure the build succeeds -4. Follow up with any reviews on your code -5. 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. -- โšก๏ธ `:zap:` - Improve performance. -- ๐Ÿ”ฅ `:fire:` - Remove code or files. -- ๐Ÿ› `:bug:` - Fix a bug. -- ๐Ÿš‘๏ธ `:ambulance:` - Critical hotfix -- โœจ `:sparkles:` - Introduce new features. -- ๐Ÿ“ `:memo:` - Add or update documentation. -- ๐Ÿš€ `:rocket:` - Deploy stuff. -- ๐Ÿ’„ `:lipstick:` - Add or update the UI and style files. -- ๐ŸŽ‰ `:tada:` - Begin a project. -- โœ… `:white_check_mark:` - Add, update, or pass tests. -- ๐Ÿ”’๏ธ `:lock:` - Fix security issues. -- ๐Ÿ”– `:bookmark:` - Make a Release or Version tag. -- ๐Ÿšจ `:rotating_light:` - Fix compiler / linter warnings. -- ๐Ÿšง `:construction:` - Work in progress. -- โฌ†๏ธ `:arrow_up:` - Upgrade dependencies. -- ๐Ÿ‘ท `:construction_worker:` - Add or update CI build system. -- โ™ป๏ธ `:recycle:` - Refactor code. -- ๐Ÿฉน `:adhesive_bandage:` - Simple fix for a non-critical issue. -- ๐Ÿ”ง `:wrench:` - Add or update configuration files. -- ๐Ÿฑ `:bento:` - Add or update assets. -- ๐Ÿ—ƒ๏ธ `:card_file_box:` - Perform database schema related changes. -- โœ๏ธ `:pencil2:` - Fix typos. -- ๐ŸŒ `:globe_with_meridians:` - Internationalization and translations. - -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 -- If any dependencies were added, explain why it was needed, state the cost associated, and confirm it does not introduce any security issues -- Finally, check the checkboxes, to confirm that the standards are met, and hit submit! - ---- - -## Automated Workflows - -Dashy makes heavy use of [GitHub Actions](https://github.com/features/actions) to fully automate the checking, testing, building, deploying of the project, as well as administration tasks like management of issues, tags, releases and documentation. The following section outlines each workflow, along with a link the the action file, current status and short description. A lot of these automations were made possible using community actions contributed to GH marketplace by some amazing people. - -### CI Checks - -These run on every pull request targeting master. All required checks must pass before merging. - -Action | Description ---- | --- -**PR Quality Check**
[![pr-quality-check.yml](https://github.com/Lissy93/dashy/actions/workflows/pr-quality-check.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/pr-quality-check.yml) | Runs lint, unit tests, a full build and Docker smoke test against every PR. Also runs a security audit on dependencies -**Dependency Update Summary**
[![dependency-updates-summary.yml](https://github.com/Lissy93/dashy/actions/workflows/dependency-updates-summary.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/dependency-updates-summary.yml) | When yarn.lock is modified in a PR, Liss-Bot comments with a summary of which packages changed - -### Releases - -Action | Description ---- | --- -**Auto Version & Tag**
[![bump-and-tag.yml](https://github.com/Lissy93/dashy/actions/workflows/bump-and-tag.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/bump-and-tag.yml) | When a PR with code changes is merged into master, auto-bumps the patch version (if not already bumped) and creates a git tag -**Manual Tag**
[![manual-tag.yml](https://github.com/Lissy93/dashy/actions/workflows/manual-tag.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/manual-tag.yml) | Manual dispatch workflow. Provide a version to tag, or leave empty to auto-bump patch. Updates package.json, commits and creates the tag -**Docker Publish**
[![docker-build-publish.yml](https://github.com/Lissy93/dashy/actions/workflows/docker-build-publish.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/docker-build-publish.yml) | Triggered by tag pushes. Builds multi-arch Docker images and publishes to DockerHub and GHCR with semver tags -**Draft Release**
[![draft-release.yml](https://github.com/Lissy93/dashy/actions/workflows/draft-release.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/draft-release.yml) | Triggered by tag pushes. Creates a draft GitHub release with auto-generated notes for major or minor version bumps. Patch-only bumps are skipped - -### Issue Management - -Action | Description ---- | --- -**Close Stale Issues**
[![close-stale-issues.yml](https://github.com/Lissy93/dashy/actions/workflows/close-stale-issues.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/close-stale-issues.yml) | Issues which have not been updated for a long time will have a comment posted to them. If the author does not reply, the issue will be marked as stale and closed. Also handles issues awaiting user response and pings the maintainer when needed - -### Documentation - -Action | Description ---- | --- -**Wiki Sync**
[![wiki-sync.yml](https://github.com/Lissy93/dashy/actions/workflows/wiki-sync.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/wiki-sync.yml) | Publishes the repository wiki from the markdown files in the docs directory. Runs weekly and on manual dispatch -**Update Docs Site**
[![update-docs-site.yml](https://github.com/Lissy93/dashy/actions/workflows/update-docs-site.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/update-docs-site.yml) | When docs change on master, copies them to the website branch and processes them for the docs site -**Build Docs Site**
[![build-docs-site.yml](https://github.com/Lissy93/dashy/actions/workflows/build-docs-site.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/build-docs-site.yml) | Builds and deploys the documentation website from the WEBSITE/docs-site-source branch - -### Other - -Action | Description ---- | --- -**Mirror to Codeberg**
[![mirror.yml](https://github.com/Lissy93/dashy/actions/workflows/mirror.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/mirror.yml) | Pushes a copy of the repo to Codeberg weekly and on manual dispatch - ---- - -## Release Pipeline - -```mermaid -flowchart TD - A[PR opened] --> B[CI checks run\nlint, test, build, Docker smoke, security] - B --> C{Checks pass?} - C -- No --> D[PR blocked] - C -- Yes --> R[Maintainers review] - R --> E[PR merged into master] - - E --> F{Code files changed?} - F -- No --> G[No action] - F -- Yes --> H{Version already\nbumped in PR?} - H -- Yes --> I[Use existing version] - H -- No --> J[Auto bump patch version] - J --> I - - I --> K[Create git tag] - K --> L[Docker build + publish\namd64, arm64, arm/v7] - K --> M{Major or minor bump?} - M -- Yes --> N[Draft GitHub release] - M -- No --> O[Skip release] -``` - ---- +# Releases and Workflows + +> This document outlines our release schedule, workflows/automations, repository conventions and standards + +- [Versioning and Releases](#versioning-and-releases) + - [High-level tag process](#high-level-tag-process) + - [Creating a Release](#creating-a-release) + - [Versioning](#versioning) +- [Workflows](#workflows) + - [CI](#ci) + - [Docker](#docker) + - [Release](#release) + - [Tag](#tag) + - [Mirror](#mirror) + - [Docs](#docs) +- [Git Strategy](#git-strategy) + - [Commits](#commits) + - [Branches](#branches) + - [Pull Requests](#pull-requests) + +--- + +## Versioning and Releases + +### High-level tag process +- All new features, fixes and updates happen via pull request to `master` +- After a PR is merged, the `version` in the package.json will automatically be bumped by it's patch value (unless the PR already updated the version) +- Whenever the `version` is updated, a new git tag and also Docker tag is created and pushed +- If the major or minor version (not patch version) was bumped, then a release is also drafted + +The tagging process is managed via GitHub actions, using our [`tag.yml`](https://github.com/lissy93/dashy/blob/master/.github/workflows/tag.yml) workflow. +This workflow can also be manually triggered by a maintainer to make and push a new tag (either specify tag version, or leave blank for auto-bump of patch version). + +### Creating a Release +Only repository maintainers can publish releases. The process typically happens automatically whenever the major or minor version is updated (via tag workflow). But a release can also be triggered manually via the [`release.yml`](https://github.com/lissy93/dashy/blob/master/.github/workflows/release.yml) workflow's manual dispatch, by passing it an (already existing, not yet released) tag version. Note that the bot only creates a Draft Release, so you'll then need to head to the releases tab, review it looks correct, and hit Publish. + +### Versioning + +Typically Dashy has multiple patch versions per week, bi-weekly minor releases, and quarterly major releases. + +Dashy uses a form of semantic versioning ([semver](https://semver.org/)), whereby we push a: +- Patch (e.g. `4.6.9`) - New patch version published for every change +- Minor (e.g. `4.7.0`) - New minor version published for groups of features +- Major (e.g. `5.0.0`) - Large releases, possibly not backward compatible + + + +--- + +## Workflows + +### CI + +> Runs checks on pull request to catch obvious/critical issues + +This runs a series of checks against the PR. A path-filter step first works out what changed, so most checks only run when their relevant files were modified (the rest are skipped): + +- **Lint** - Confirms the code is clean and consistent, with ESLint + - _Runs when:_ source or config changes +- **Typecheck** - Confirms TypeScript types are valid, with `vue-tsc` + - _Runs when:_ any code or config changes +- **Test** - Runs the unit test suite + - _Runs when:_ every PR +- **Locale check** - Validates the translation files are complete and well-formed + - _Runs when:_ any languages or locale content ([`src/assets/locales`](https://github.com/lissy93/dashy/blob/master/src/assets/locales/)) is updated +- **Spellcheck** - Catches typos in the source strings ([`en.json`](https://github.com/lissy93/dashy/blob/master/src/assets/locales/en.json)) + - _Runs when:_ English locale file is updated +- **Build check** - Builds Dashy and checks the `dist` output is all good + - _Runs when:_ every PR +- **Docker smoke test** - Builds the Docker image and checks it starts and serves correctly + - _Runs when:_ every PR +- **Dependency audit** - Scans dependency changes for known vulnerabilities (fails on moderate+) + - _Runs when:_ Package is added/updated in [`yarn.lock`](https://github.com/lissy93/dashy/blob/master/yarn.lock) +- **Secret scanning** - Scans the PR diff for committed secrets/keys/credentials, with TruffleHog + - _Runs when:_ every PR +- **Workflow audit** - Lints and security-audits the GitHub Actions, with actionlint + zizmor + - _Runs when:_ a workflow file changes (`.github/workflows/**`) + +| | | +|---|---| +| **Workflow** | [`ci.yml`](https://github.com/lissy93/dashy/blob/master/.github/workflows/ci.yml) | +| **Status** | [![๐Ÿšฆ PR Check](https://github.com/lissy93/dashy/actions/workflows/ci.yml/badge.svg)](https://github.com/lissy93/dashy/actions/workflows/ci.yml) | +| **Triggers** | Pull request (PR opened/updated on master) | +| **Inputs** | _None_ | +| **Outputs** | _None_ | + + +### Docker + +> The Docker workflow builds and publishes the Docker image. + +Uses our [`Dockerfile`](https://github.com/lissy93/dashy/blob/master/Dockerfile). This is a multi-arch (amd64, arm64, armv7) with each run as a matrix. The image is published to both GHCR ([`ghcr.io/lissy93/dashy`](https://github.com/lissy93/dashy/pkgs/container/dashy)) and DockerHub ([`lissy93/dashy`](https://hub.docker.com/r/lissy93/dashy/)). It also runs a trivy security scan, and if critical issues are present the scheduled job will fail, and results published under the Security tab. The job also attests both the build provenance and SBOM, which are published alongside the image. The Docker tags are computed from the values in the Dockerfile. + +| | | +|---|---| +| **Workflow** | [`docker.yml`](https://github.com/lissy93/dashy/blob/master/.github/workflows/docker.yml) | +| **Status** | [![๐Ÿณ Docker](https://github.com/lissy93/dashy/actions/workflows/docker.yml/badge.svg)](https://github.com/lissy93/dashy/actions/workflows/docker.yml) | +| **Triggers** | Tag creation, schedule, manual dispatch | +| **Inputs** | Tag (optional, inferred from git tag) | +| **Outputs** | SHA, manifest, digest, SBOM, attestation | + +### Release + +> Builds the app and drafts a GitHub release with the packaged tarball + +Triggered by a major/minor (`X.Y.0`) tag push, or by manual dispatch against an existing tag. It builds Dashy, packages a release tarball (the built `dist` plus the server files needed to run it), then generates a SHA256 checksum and an SLSA build-provenance attestation. Finally it drafts a GitHub release with auto-generated notes (diffed against the previous `X.Y.0` tag). The release is only a draft - a maintainer reviews it and hits Publish. + +| | | +|---|---| +| **Workflow** | [`release.yml`](https://github.com/lissy93/dashy/blob/master/.github/workflows/release.yml) | +| **Status** | [![๐Ÿš€ Release](https://github.com/lissy93/dashy/actions/workflows/release.yml/badge.svg)](https://github.com/lissy93/dashy/actions/workflows/release.yml) | +| **Triggers** | Major/minor tag push (`*.*.0`), manual dispatch | +| **Inputs** | Tag (required on manual dispatch, must already exist) | +| **Outputs** | Draft release, tarball, SHA256 checksum, provenance attestation | + +### Tag + +> Bumps the version and pushes a new git tag + +When a PR with code changes is merged into master, this bumps the patch version in the package.json (unless the PR already bumped it), commits the change, then creates and pushes a git tag for the new version. That tag push is what kicks off the Docker and Release workflows downstream. It also labels and comments on any issues referenced in the PR, and pings the docs site to rebuild. It can also be triggered manually - either pass a specific version, or leave it blank to auto-bump the patch. + +| | | +|---|---| +| **Workflow** | [`tag.yml`](https://github.com/lissy93/dashy/blob/master/.github/workflows/tag.yml) | +| **Status** | [![๐Ÿ”– Tag](https://github.com/lissy93/dashy/actions/workflows/tag.yml/badge.svg)](https://github.com/lissy93/dashy/actions/workflows/tag.yml) | +| **Triggers** | PR merged to master, manual dispatch | +| **Inputs** | Version (optional, leave blank to auto-bump patch) | +| **Outputs** | Version-bump commit, git tag, issue labels/comments | + +### Mirror + +> Mirrors the repo over to our Codeberg instance + +Pushes a full copy of the repo to our Codeberg mirror, over at [codeberg.org/alicia/dashy](https://codeberg.org/alicia/dashy), so the project isn't solely hosted on GitHub. Runs weekly. Uses the [`lissy93/repo-mirror-action`](https://github.com/Lissy93/repo-mirror-action) action for keeping mirrors in-sync. + +| | | +|---|---| +| **Workflow** | [`mirror.yml`](https://github.com/lissy93/dashy/blob/master/.github/workflows/mirror.yml) | +| **Status** | [![๐Ÿชž Mirror](https://github.com/lissy93/dashy/actions/workflows/mirror.yml/badge.svg)](https://github.com/lissy93/dashy/actions/workflows/mirror.yml) | +| **Triggers** | Schedule (weekly, Sun 03:30 UTC), manual dispatch | +| **Inputs** | _None_ | +| **Outputs** | _None_ | + +### Docs + +> Keeps the docs site and GitHub wiki in sync with the `/docs` directory + +Mirrors the markdown content from [`/docs`](https://github.com/lissy93/dashy/tree/master/docs) to the `WEBSITE/docs-site-source`, where it's then formatted and the Docusaurus site is re-built and deployed to [dashy.to](https://dashy.to/). Runs whenever docs are updated on master. + +| | | +|---|---| +| **Workflow** | [`update-docs-site.yml`](https://github.com/lissy93/dashy/blob/master/.github/workflows/update-docs-site.yml) | +| **Status** | [![๐Ÿ“ Sync Docs](https://github.com/lissy93/dashy/actions/workflows/update-docs-site.yml/badge.svg)](https://github.com/lissy93/dashy/actions/workflows/update-docs-site.yml) | +| **Triggers** | Push to `docs/**` on master, schedule (weekly), manual dispatch | +| **Inputs** | _None_ | +| **Outputs** | Updated docs on the `WEBSITE/docs-site-source` branch | + + +--- + +## Git Strategy + +### Commits +We use [gitmoji](https://gitmoji.dev/) for commits (because it's fun!). +Whereby each commit message starts with an emoji which indicates the change type. + +### Branches +Most branches are named with their type, followed by short description. +E.g. `feat/adds-awesome-feature`, `ref/language-deduplication`, `fix/resolves-missing-icons`. + +### Pull Requests +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't have write access) +2. Code some awesome stuff, then add and commit your changes +3. Create a Pull Request, filling in the template +4. Follow up with any reviews on your code +5. Merge ๐ŸŽ‰ From 51be01d07f70b85da3227fd0317e21e93bea3d5b Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Thu, 28 May 2026 12:31:33 +0100 Subject: [PATCH 8/8] =?UTF-8?q?=F0=9F=93=9D=20Updates=20file=20links=20and?= =?UTF-8?q?=20references?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/authentication/zitadel.md | 2 +- docs/credits.md | 9 +-------- docs/developing.md | 22 ++++++---------------- docs/development-guides.md | 7 +++---- docs/release-workflow.md | 5 ++++- docs/widgets.md | 2 +- 6 files changed, 16 insertions(+), 31 deletions(-) diff --git a/docs/authentication/zitadel.md b/docs/authentication/zitadel.md index 54d14a80e2..bc12e697b4 100644 --- a/docs/authentication/zitadel.md +++ b/docs/authentication/zitadel.md @@ -109,7 +109,7 @@ First boot runs the database migrations and creates the org, admin user, and a m ## 2. Configure Zitadel -Steps below are the manual UI walkthrough. There's also a Management API for scripted setup; an example bootstrap script is at [`alicia-notes/zitadel/configure.sh`](https://github.com/lissy93/dashy/blob/4.1.5/alicia-notes/zitadel/configure.sh) in the source repo. +Steps below are the manual UI walkthrough. Zitadel also has a Management API if you'd rather script the setup. ### Create the project diff --git a/docs/credits.md b/docs/credits.md index ae2712b640..cf9aa8dcec 100644 --- a/docs/credits.md +++ b/docs/credits.md @@ -23,12 +23,11 @@ This app definitely wouldn't have been quite so possible without the making use ### 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/). +At it's core, the application uses [**Vue.js**](https://github.com/vuejs/core), 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), the app is written in [**TypeScript**](https://github.com/Microsoft/TypeScript) and JavaScript, and bundled with [**Vite**](https://github.com/vitejs/vite). 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 - [`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` @@ -36,12 +35,6 @@ At it's core, the application uses [**Vue.js**](https://github.com/vuejs/vue), a ### 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` -- [`vue-material-tabs`](https://github.com/jairoblatt/vue-material-tabs) - Tab view component by @jairoblatt `MIT` -- [`VJsoneditor`](https://github.com/yansenlei/VJsoneditor) - Interactive JSON editor component by @yansenlei `MIT` - - Forked from [`JsonEditor`](https://github.com/josdejong/jsoneditor) by @josdejong `Apache-2.0 License` -- [`vue-swatches`](https://github.com/saintplay/vue-swatches) - Color palete picker by @saintplay `MIT` --- diff --git a/docs/developing.md b/docs/developing.md index 70f009b58e..9f3d7a8621 100644 --- a/docs/developing.md +++ b/docs/developing.md @@ -2,7 +2,7 @@ # Developing This article outlines how to get Dashy running in a development environment, and outlines the basics of the architecture. -If you're adding new features, you may want to check out the [Development Guides](./docs/development-guides.md) docs, for tutorials covering basic tasks. +If you're adding new features, you may want to check out the [Development Guides](./development-guides.md) docs, for tutorials covering basic tasks. - [Setting up the Development Environment](#setting-up-the-dev-environment) - [Prerequisites](#prerequisites) @@ -83,7 +83,7 @@ You can set variables either in your environment, or using the [`.env`](https:// ### 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). +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 [Vite Env Variables and Modes](https://vite.dev/guide/env-and-mode). --- @@ -162,7 +162,7 @@ When you submit your PR, include the required info, by filling out the PR templa 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) +- [Introduction to Vue.js](https://vuejs.org/guide/introduction.html) - [Vue.js Walkthrough](https://www.taniarascia.com/getting-started-with-vue/) - [ES6 Features](https://github.com/lukehoban/es6features) - [Definitive guide to SCSS](https://blog.logrocket.com/the-definitive-guide-to-scss/) @@ -198,7 +198,7 @@ The most significant things to note are: Styleguides: -- Vue: [Vue styleguide](https://vuejs.org/v2/style-guide/) +- Vue: [Vue styleguide](https://vuejs.org/style-guide/) - JavaScript: [github.com/airbnb/javascript](https://github.com/airbnb/javascript) --- @@ -213,14 +213,14 @@ Styleguides: โ”œโ”€โ”€ src/ # Project front-end source code โ”œโ”€โ”€ server.js # A Node.js server to serve up the /dist directory โ”œโ”€โ”€ services/ # All server-side endpoints and utilities -โ”œโ”€โ”€ vue.config.js # Vue.js configuration +โ”œโ”€โ”€ vite.config.mjs # Vite (build tool) configuration โ”œโ”€โ”€ Dockerfile # The blueprint for building the Docker container โ”œโ”€โ”€ docker-compose.yml # A Docker run command โ”œโ”€โ”€ .env # Location for any environmental variables โ”œโ”€โ”€ yarn.lock # Auto-generated list of current packages and version numbers โ”œโ”€โ”€ docs/ # Markdown documentation โ”œโ”€โ”€ README.md # Readme, basic info for getting started -โ”œโ”€โ”€ LICENSE.md # License for use +โ”œโ”€โ”€ LICENSE # License for use โ•ฏ ``` @@ -327,7 +327,6 @@ Styleguides: โ”‚ โ”œโ”€โ”€ CloudBackup.js # Functionality for encrypting, processing and network calls โ”‚ โ”œโ”€โ”€ ConfigSchema.json # The schema, used to validate the users conf.yml file โ”‚ โ”œโ”€โ”€ ConfigAccumulator.js # Central place for managing and combining config -โ”‚ โ”œโ”€โ”€ ConfigHelpers.js # Collection of helper functions to process config using accumulator โ”‚ โ”œโ”€โ”€ ConfigValidator.js # A helper script that validates the config file against schema โ”‚ โ”œโ”€โ”€ CoolConsole.js # Prints info, warning and error messages to browser console, with a cool style โ”‚ โ”œโ”€โ”€ defaults.js # Global constants and their default values @@ -368,14 +367,5 @@ The easiest method of checking performance is to use Chromium's build in auditin [BundlePhobia](https://bundlephobia.com/) is a really useful app that lets you analyze the cost of adding any particular dependency to an application ---- - -## Notes - -### Known Warnings - -When running the build command, several warnings appear. These are not errors, and do not affect the security or performance of the application. They will be addressed in a future update - -`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 7aa7f3be4c..55343bb580 100644 --- a/docs/development-guides.md +++ b/docs/development-guides.md @@ -262,7 +262,7 @@ If add any new variables, ensure that there is always a fallback (define it in [ If this is your first time working on Dashy, then the [Developing Docs](https://github.com/Lissy93/dashy/blob/master/docs/developing.md) instructions for project setup and running. In short, you just need to clone the project, cd into it, install dependencies (`yarn`) and then start the development server (`yarn dev`). -To build a widget, you'll also need some basic knowledge of Vue.js. The [official Vue docs](https://vuejs.org/v2/guide/) provides a good starting point, as does [this guide](https://www.taniarascia.com/getting-started-with-vue/) by Tania Rascia +To build a widget, you'll also need some basic knowledge of Vue.js. The [official Vue docs](https://vuejs.org/guide/) provides a good starting point, as does [this guide](https://www.taniarascia.com/getting-started-with-vue/) by Tania Rascia 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. @@ -278,7 +278,6 @@ Firstly, create a new `.vue` file under [`./src/components/Widgets`](https://git