Skip to content

armgit / dashy

Public Imported from GitHub
0

🚀 A self-hostable personal dashboard built for you. Includes status-checking, widgets, themes, icon packs, a UI editor and tons more!

📝 Fixes contents in auth docs, updates deployment docs

Alicia Sykesa9cfb5fda13d
diff --git a/docs/authentication.md b/docs/authentication.md
index 53c50cb8..25982129 100644
--- a/docs/authentication.md
+++ b/docs/authentication.md
@@ -5,26 +5,26 @@
- [Hash Password](#hash-password)
- [Logging In and Out](#logging-in-and-out)
- [Guest Access](#enabling-guest-access)
- - [Per-User Access](#granular-access)
+ - [Granular Access](#granular-access)
+ - [Permissions](#permissions)
- [Using Environment Variables for Passwords](#using-environment-variables-for-passwords)
- [Adding HTTP Auth to Configuration](#adding-http-auth-to-configuration)
- - [Security Considerations](#security)
+ - [Security](#security)
- [HTTP Auth](#http-auth)
- [Using Config-File Users](#using-config-file-users-recommended)
- [Using Static Credentials](#using-static-credentials)
- [Keycloak Auth](#keycloak)
- - [Deploying Keycloak](#1-deploy-keycloak)
- - [Setting up Keycloak](#2-setup-keycloak-users)
- - [Configuring Dashy for Keycloak](#3-enable-keycloak-in-dashy-config-file)
- - [Troubleshooting Keycloak](#troubleshooting-keycloak)
+- [Header Authentication](#header-authentication)
- [OIDC Auth](#oidc)
- - [authentik](#authentik)
+- [authentik](#authentik)
- [Alternative Authentication Methods](#alternative-authentication-methods)
+ - [Reverse Proxy Auth](#reverse-proxy-auth)
+ - [Zero-Trust Tunnels](#zero-trust-tunnels)
- [VPN](#vpn)
- [IP-Based Access](#ip-based-access)
- [Web Server Authentication](#web-server-authentication)
- - [OAuth Services](#oauth-services)
- - [Auth on Cloud Hosting Services](#static-site-hosting-providers)
+ - [SSO / OAuth Providers](#sso--oauth-providers)
+ - [Cloud Hosting Providers](#cloud-hosting-providers)
> [!IMPORTANT]
@@ -287,8 +287,6 @@ Your app is now secured :) When you load Dashy, it will redirect to your Keycloa
From within the Keycloak console, you can then configure things like time-outs, password policies, etc. You can also backup your full Keycloak config, and it is recommended to do this, along with your Dashy config. You can spin up both Dashy and Keycloak simultaneously and restore both applications configs using a `docker-compose.yml` file, and this is recommended.
----
-
### Troubleshooting Keycloak
If you encounter issues with your Keycloak setup, follow these steps to troubleshoot and resolve common problems.
@@ -307,6 +305,52 @@ Solution: In "TC clients" -> "Access settings" -> "Root URL" https://dashy.my.do
---
+## Header Authentication
+
+Header authentication allows Dashy to trust an upstream reverse proxy to handle authentication. The proxy authenticates users and forwards their identity to Dashy via a configurable HTTP header (e.g. `REMOTE_USER`). This is the standard pattern used by [Authelia](https://www.authelia.com/), [Authentik](https://goauthentik.io/), Traefik's `forwardAuth`, Caddy's `forward_auth`, and Nginx's `auth_request`.
+
+This is useful when you already have a central authentication layer in front of your self-hosted services and want Dashy to automatically pick up the authenticated user without requiring a separate login.
+
+### Configuration
+
+```yaml
+appConfig:
+ auth:
+ enableHeaderAuth: true
+ users:
+ - user: alice
+ hash: 0a7b1d4c2e... # SHA-256 hash of password
+ type: admin
+ - user: bob
+ hash: 3f8e2b1a9d...
+ type: normal
+ headerAuth:
+ userHeader: Remote-User
+ proxyWhitelist:
+ - 172.18.0.2
+ - 127.0.0.1
+```
+
+- **`userHeader`** - The HTTP header name containing the authenticated username. Defaults to `Remote-User` if not specified. Common values: `Remote-User` (Authelia), `X-authentik-username` (Authentik), or whatever your proxy forwards. Header matching is case-insensitive.
+- **`proxyWhitelist`** - Required. An array of IP addresses that Dashy will accept the header from. Only requests originating from these IPs will be trusted. This prevents clients from spoofing the header directly.
+- **`users`** - Required. The header username is matched against this list to determine the user's role (`admin` or `normal`) and to generate the session token. Users must be defined here even though authentication is handled externally.
+
+### How it Works
+
+1. User visits Dashy, which is behind a reverse proxy (e.g. Authelia)
+2. The proxy authenticates the user and forwards the request with a header like `Remote-User: alice`
+3. Dashy's server checks that the request comes from a whitelisted proxy IP, then returns the username via the `/get-user` endpoint
+4. The client matches the username against the configured users, generates a session token, and sets the auth cookie
+5. From this point, standard Dashy auth applies - `isLoggedIn()`, admin checks, and granular access controls all work as normal
+
+### Notes
+
+- The `proxyWhitelist` checks `req.socket.remoteAddress`, which is the direct connection source. If your proxy connects through Docker networking, use the container's internal IP (e.g. `172.18.0.2`), not the external IP
+- Logout clears Dashy's session cookie, but the user remains authenticated at the proxy level. Revisiting the page will re-authenticate automatically
+- When header auth is enabled, server-side API endpoints are also protected by the proxy whitelist. Requests not from a whitelisted IP will be rejected. Admin enforcement applies - only users with `type: admin` can access write endpoints (config save, rebuild)
+
+---
+
## OIDC
Dashy also supports using a general [OIDC compatible](https://openid.net/connect/) authentication server. In order to use it, the authentication section needs to be configured:
@@ -352,7 +396,7 @@ Groups and roles will be populated and available for controlling display similar
---
-### authentik
+## authentik
This documentation is specific to `authentik`, however it may be useful in getting other idP's working with `Dashy`.
@@ -529,201 +573,127 @@ sections:
```
---
-## Header Authentication
-
-Header authentication allows Dashy to trust an upstream reverse proxy to handle authentication. The proxy authenticates users and forwards their identity to Dashy via a configurable HTTP header (e.g. `REMOTE_USER`). This is the standard pattern used by [Authelia](https://www.authelia.com/), [Authentik](https://goauthentik.io/), Traefik's `forwardAuth`, Caddy's `forward_auth`, and Nginx's `auth_request`.
-
-This is useful when you already have a central authentication layer in front of your self-hosted services and want Dashy to automatically pick up the authenticated user without requiring a separate login.
-
-### Configuration
-
-```yaml
-appConfig:
- auth:
- enableHeaderAuth: true
- users:
- - user: alice
- hash: 0a7b1d4c2e... # SHA-256 hash of password
- type: admin
- - user: bob
- hash: 3f8e2b1a9d...
- type: normal
- headerAuth:
- userHeader: Remote-User
- proxyWhitelist:
- - 172.18.0.2
- - 127.0.0.1
-```
-
-- **`userHeader`** - The HTTP header name containing the authenticated username. Defaults to `Remote-User` if not specified. Common values: `Remote-User` (Authelia), `X-authentik-username` (Authentik), or whatever your proxy forwards. Header matching is case-insensitive.
-- **`proxyWhitelist`** - Required. An array of IP addresses that Dashy will accept the header from. Only requests originating from these IPs will be trusted. This prevents clients from spoofing the header directly.
-- **`users`** - Required. The header username is matched against this list to determine the user's role (`admin` or `normal`) and to generate the session token. Users must be defined here even though authentication is handled externally.
+## Alternative Authentication Methods
-### How it Works
+These are alternatives to Dashy's built-in auth, Keycloak, and OIDC. Most of them sit in front of Dashy at the network or reverse proxy level, which is generally the better approach for anything internet-facing.
-1. User visits Dashy, which is behind a reverse proxy (e.g. Authelia)
-2. The proxy authenticates the user and forwards the request with a header like `Remote-User: alice`
-3. Dashy's server checks that the request comes from a whitelisted proxy IP, then returns the username via the `/get-user` endpoint
-4. The client matches the username against the configured users, generates a session token, and sets the auth cookie
-5. From this point, standard Dashy auth applies - `isLoggedIn()`, admin checks, and granular access controls all work as normal
+- [Reverse Proxy Auth](#reverse-proxy-auth) - Authelia, Authentik, or similar sitting in front of Dashy
+- [Zero-Trust Tunnels](#zero-trust-tunnels) - Cloudflare Tunnel, Tailscale Funnel
+- [VPN](#vpn) - Keep Dashy off the internet entirely
+- [IP-Based Access](#ip-based-access) - Restrict by source IP in your web server
+- [Web Server Authentication](#web-server-authentication) - HTTP basic auth at the proxy level
+- [SSO / OAuth Providers](#sso--oauth-providers) - Cloud-hosted identity providers
+- [Cloud Hosting Providers](#cloud-hosting-providers) - Built-in auth on hosting platforms
-### Notes
+### Reverse proxy auth
-- The `proxyWhitelist` checks `req.socket.remoteAddress`, which is the direct connection source. If your proxy connects through Docker networking, use the container's internal IP (e.g. `172.18.0.2`), not the external IP
-- Logout clears Dashy's session cookie, but the user remains authenticated at the proxy level. Revisiting the page will re-authenticate automatically
-- When header auth is enabled, server-side API endpoints are also protected by the proxy whitelist. Requests not from a whitelisted IP will be rejected. Admin enforcement applies - only users with `type: admin` can access write endpoints (config save, rebuild)
+The most common setup for self-hosters running multiple services. You put an auth server in front of your reverse proxy, and it handles login, 2FA, and sessions for everything behind it. You configure it once, and all your apps get protected.
----
+Dashy has [Header Authentication](#header-authentication) support, so when your proxy authenticates a user and forwards their identity via a header, Dashy picks up the username and maps it to a configured user automatically. No separate Dashy login needed.
-## Alternative Authentication Methods
+**Authelia** is lightweight and Docker-friendly. It supports 2FA, per-path access rules, and multiple user backends. To get started quickly:
-If you are self-hosting Dashy, and require secure authentication to prevent unauthorized access, then you can either use Keycloak, or one of the following options:
+1. `git clone https://github.com/authelia/authelia.git`
+2. `cd authelia/examples/compose/lite`
+3. Edit `users_database.yml`, `configuration.yml`, and `docker-compose.yml` for your domain and users
+4. `docker compose up -d`
-- [Authentication Server](#authentication-server) - Put Dashy behind a self-hosted auth server
-- [VPN](#vpn) - Use a VPN to tunnel into the network where Dashy is running
-- [IP-Based Access](#ip-based-access) - Disallow access from all IP addresses, except your own
-- [Web Server Authentication](#web-server-authentication) - Enable user control within your web server or proxy
-- [OAuth Services](#oauth-services) - Implement a user management system using a cloud provider
-- [Password Protection (for cloud providers)](#static-site-hosting-providers) - Enable password-protection on your site
+See the [Authelia docs](https://www.authelia.com/docs/) for the full setup guide.
-### Authentication Server
+**Authentik** is heavier but gives you a proper admin UI, built-in OIDC/SAML support, and user self-service (password resets, enrollment flows, etc). Good if you want a single identity provider across many apps. See the [authentik Docker Compose install](https://docs.goauthentik.io/docs/installation/docker-compose) to get started, and the [authentik section](#authentik) above for Dashy-specific OIDC config.
-#### Authelia
+### Zero-trust tunnels
-[Authelia](https://www.authelia.com/) is an open-source full-featured authentication server, which can be self-hosted and either on bare metal, in a Docker container or in a Kubernetes cluster. It allows for fine-grained access control rules based on IP, path, users etc, and supports 2FA, simple password access or bypass policies for your domains.
+These let you expose Dashy to the internet without opening inbound ports or configuring port forwarding. Auth is handled by the tunnel provider before traffic ever reaches your server.
-- `git clone https://github.com/authelia/authelia.git`
-- `cd authelia/examples/compose/lite`
-- Modify the `users_database.yml` the default username and password is authelia
-- Modify the `configuration.yml` and `docker-compose.yml` with your respective domains and secrets
-- `docker-compose up -d`
+**Cloudflare Tunnel** connects Dashy to Cloudflare's edge network via an outbound-only `cloudflared` daemon (runs nicely as a Docker sidecar). Cloudflare handles DNS, TLS, and DDoS protection. Pair it with Cloudflare Access to require identity provider login before anyone reaches Dashy. The free tier covers most home setups. See the [Cloudflare Tunnel docs](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/).
-For more information, see the [Authelia docs](https://www.authelia.com/docs/)
+**Tailscale Funnel** exposes Dashy through your Tailscale mesh to the public internet, with automatic TLS. Simpler to set up than Cloudflare but you get less control over access policies. See the [Funnel docs](https://tailscale.com/kb/1223/funnel).
### VPN
-A catch-all solution to accessing services running from your home network remotely is to use a VPN. It means you do not need to worry about implementing complex authentication rules, or trusting the login implementation of individual applications. However it can be inconvenient to use on a day-to-day basis, and some public and corporate WiFi block VPN connections. Two popular VPN protocols are [OpenVPN](https://openvpn.net/) and [WireGuard](https://www.wireguard.com/)
-
-### IP-Based Access
-
-If you have a static IP or use a VPN to access your running services, then you can use conditional access to block access to Dashy from everyone except users of your pre-defined IP address. This feature is offered by most cloud providers, and supported by most web servers.
+A VPN keeps Dashy off the public internet entirely. You connect to your home network remotely and access Dashy like you're on the LAN. No auth to configure, no attack surface to worry about. The downside: you need the VPN running to see anything, and some networks (corporate WiFi, hotels) block VPN traffic.
-#### Apache
+[WireGuard](https://www.wireguard.com/) is fast and minimal. Most self-hosters run it through a UI like [wg-easy](https://github.com/wg-easy/wg-easy), which gives you a web interface for managing peers and generating QR codes for mobile.
-In Apache, this is configured in your `.htaccess` file in Dashy's root folder, and should look something like:
+[Tailscale](https://tailscale.com/) wraps WireGuard and takes care of NAT traversal, key exchange, and device management. No port forwarding needed, works across networks with zero config. There's a generous free tier. [Headscale](https://github.com/juanfont/headscale) is a self-hosted coordination server if you want to keep everything on your own infrastructure.
-```text
-Order Deny,Allow
-Deny from all
-Allow from [your-ip]
-```
+[OpenVPN](https://openvpn.net/) still works fine if you already have it running, but for a new setup WireGuard or Tailscale are easier to get going.
-#### NGINX
+### IP-based access
-In NGINX you can specify [control access](https://docs.nginx.com/nginx/admin-guide/security-controls/controlling-access-proxied-http/) rules for a given site in your `nginx.conf` or hosts file. For example:
+If you have a static IP or are already on a VPN, you can restrict access to Dashy by source IP at the web server level. This works well as an extra layer on top of other auth methods.
+NGINX:
```text
-server {
- listen 8080;
- server_name www.dashy.example.com;
- location / {
- root /path/to/dashy/;
- passenger_enabled on;
- allow [your-ip];
- deny all;
- }
- }
-```
-
-#### Caddy
-
-In Caddy, [Request Matchers](https://caddyserver.com/docs/caddyfile/matchers) can be used to filter requests
-
-```text
-dashy.site {
- @public_networks not remote_ip [your-ip]
- respond @public_networks "Access denied" 403
+location / {
+ proxy_pass http://dashy:8080;
+ allow 192.168.1.0/24;
+ allow 203.0.113.50;
+ deny all;
}
```
-### Web Server Authentication
-
-Most web servers make password protecting certain apps very easy. Note that you should also set up HTTPS and have a valid certificate in order for this to be secure.
-
-#### Apache
-
-First crate a `.htaccess` file in Dashy's route directory. Specify the auth type and path to where you want to store the password file (usually the same folder). For example:
-
+Caddy ([request matchers docs](https://caddyserver.com/docs/caddyfile/matchers)):
```text
-AuthType Basic
-AuthName "Please Sign into Dashy"
-AuthUserFile /path/dashy/.htpasswd
-require valid-user
+dashy.example.com {
+ @blocked not remote_ip 192.168.1.0/24 203.0.113.50
+ respond @blocked "Access denied" 403
+ reverse_proxy dashy:8080
+}
```
-Then create a `.htpasswd` file in the same directory. List users and their hashed passwords here, with one user on each line, and a colon between username and password (e.g. `[username]:[hashed-password]`). You will need to generate an MD5 hash of your desired password, this can be done with an [online tool](https://www.web2generators.com/apache-tools/htpasswd-generator). Your file will look something like:
-
+Apache (2.4+):
```text
-alicia:$apr1$jv0spemw$RzOX5/GgY69JMkgV6u16l0
+<Location />
+ Require ip 192.168.1.0/24
+ Require ip 203.0.113.50
+</Location>
```
-#### NGINX
+### Web server authentication
-NGINX has an [authentication module](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html) which can be used to add passwords to given sites, and is fairly simple to set up. Similar to above, you will need to create a `.htpasswd` file. Then just enable auth and specify the path to that file, for example:
+Your reverse proxy can handle HTTP basic auth directly, no extra services needed. This gives you a browser login prompt in front of Dashy. Make sure you're using HTTPS, as basic auth sends credentials base64-encoded (not encrypted) with every request.
+NGINX ([auth module docs](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html)):
```text
location / {
- auth_basic "closed site";
- auth_basic_user_file conf/htpasswd;
+ auth_basic "Dashy";
+ auth_basic_user_file /etc/nginx/conf.d/.htpasswd;
+ proxy_pass http://dashy:8080;
}
```
-#### Caddy
-
-Caddy has a [basic-auth](https://caddyserver.com/docs/caddyfile/directives/basicauth) directive, where you specify a username and hash. The password hash needs to be base-64 encoded, the [`caddy hash-password`](https://caddyserver.com/docs/command-line#caddy-hash-password) command can help with this. For example:
+Generate the password file with `htpasswd -c /etc/nginx/conf.d/.htpasswd alicia`.
+Caddy ([basicauth directive](https://caddyserver.com/docs/caddyfile/directives/basicauth)):
```text
-basicauth /secret/* {
- alicia JDJhJDEwJEVCNmdaNEg2Ti5iejRMYkF3MFZhZ3VtV3E1SzBWZEZ5Q3VWc0tzOEJwZE9TaFlZdEVkZDhX
+dashy.example.com {
+ basicauth {
+ alicia $2a$14$... # generate with: caddy hash-password
+ }
+ reverse_proxy dashy:8080
}
```
-For more info about implementing a single sign on for all your apps with Caddy, see [this tutorial](https://joshstrange.com/securing-your-self-hosted-apps-with-single-signon/)
-
-#### Lighttpd
-
-You can use the [mod_auth](https://doc.lighttpd.net/lighttpd2/mod_auth.html) module to secure your site with Lighttpd. Like with Apache, you need to first create a password file listing your usernames and hashed passwords, but in Lighttpd, it's usually called `.lighttpdpassword`.
-
-Then in your `lighttpd.conf` file (usually in the `/etc/lighttpd/` directory), load in the mod_auth module, and configure it's directives. For example:
-
+Apache:
```text
-server.modules += ( "mod_auth" )
-auth.debug = 2
-auth.backend = "plain"
-auth.backend.plain.userfile = "/home/lighttpd/.lighttpdpassword"
-
-$HTTP["host"] == "dashy.my-domain.net" {
- server.document-root = "/home/lighttpd/dashy.my-domain.net/http"
- server.errorlog = "/var/log/lighttpd/dashy.my-domain.net/error.log"
- accesslog.filename = "/var/log/lighttpd/dashy.my-domain.net/access.log"
- auth.require = (
- "/docs/" => (
- "method" => "basic",
- "realm" => "Password protected area",
- "require" => "user=alicia"
- )
- )
-}
+AuthType Basic
+AuthName "Dashy"
+AuthUserFile /path/to/.htpasswd
+Require valid-user
```
-Restart your web server for changes to take effect.
+Generate the password file with `htpasswd -c /path/to/.htpasswd alicia`.
+
+### SSO / OAuth providers
-### OAuth Services
+Cloud identity providers like [Auth0](https://auth0.com/), [Okta](https://developer.okta.com/), [Ory](https://www.ory.sh/), and [Google Cloud Identity](https://cloud.google.com/identity) can work with Dashy through its [OIDC support](#oidc). If your provider speaks OIDC (most do), just configure it as described in the OIDC section and you're set.
-There are also authentication services, such as [Ory.sh](https://www.ory.sh/), [Okta](https://developer.okta.com/), [Auth0](https://auth0.com/), [Firebase](https://firebase.google.com/docs/auth/). Implementing one of these solutions would involve some changes to the [`Auth.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/Auth.js) file, but should be fairly straightforward.
+For providers that only support OAuth2 or SAML without an OIDC layer, you'll need something in between to translate. Authentik, Keycloak, and Authelia can all bridge from SAML/OAuth2 to OIDC.
-### Static Site Hosting Providers
+### Cloud hosting providers
-If you are hosting Dashy on a cloud platform, you will probably find that it has built-in support for password protected access to web apps. For more info, see the relevant docs for your provider, for example: [Netlify Password Protection](https://docs.netlify.com/visitor-access/password-protection/), [Cloudflare Access](https://www.cloudflare.com/teams/access/), [AWS Cognito](https://aws.amazon.com/cognito/), [Azure Authentication](https://docs.microsoft.com/en-us/azure/app-service/scenario-secure-app-authentication-app-service) and [Vercel Password Protection](https://vercel.com/docs/platform/projects#password-protection).
+If you're running Dashy on a cloud platform, most have their own auth options you can enable without touching Dashy's config. See your provider's docs: [Cloudflare Access](https://www.cloudflare.com/teams/access/), [Netlify Password Protection](https://docs.netlify.com/visitor-access/password-protection/), [AWS Cognito](https://aws.amazon.com/cognito/), [Azure App Service Authentication](https://learn.microsoft.com/en-us/azure/app-service/overview-authentication-authorization), and [Vercel Password Protection](https://vercel.com/docs/security/password-protection).
**[⬆️ Back to Top](#authentication)**
diff --git a/docs/deployment.md b/docs/deployment.md
index c51f6129..0d6c990a 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -21,24 +21,19 @@ Once you've got Dashy up and running, you'll want to configure it with your own
- [Deployment Methods](#deployment-methods)
- [Deploy with Docker](#deploy-with-docker)
- [Using Docker Compose](#using-docker-compose)
+ - [Podman](#podman)
+ - [Portainer](#portainer)
- [Kubernetes](#kubernetes)
- [Unraid](#unraid)
+ - [Home Server Platforms](#home-server-platforms)
- [Synology NAS](#synology-nas)
- [Build from Source](#build-from-source)
- - [Deploy to cloud service](#deploy-to-cloud-service)
+ - [Deploy to Cloud Service](#deploy-to-cloud-service)
- [Netlify](#netlify)
- - [Heroku](#heroku)
- [Vercel](#vercel)
- - [DigitalOcean](#digitalocean)
- - [Google Cloud Platform](#google-cloud-platform)
- - [Platform.sh](#platformsh)
- - [Render](#render)
- - [Railway](#railway)
- - [Scalingo](#scalingo)
- - [Play-with-Docker](#play-with-docker)
- - [Surge.sh](#surgesh)
- [Easypanel](#easypanel)
- [EdgeOne Pages](#edgeone-pages)
+ - [Play-with-Docker](#play-with-docker)
- [Hosting with CDN](#hosting-with-cdn)
- [Requirements](#requirements)
- [System Requirements](#system-requirements)
@@ -54,15 +49,14 @@ 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 Hosted on](https://img.shields.io/badge/Hosted_on-DockerHub-6ba6e5)
+![Docker Hosted on](https://img.shields.io/badge/Hosted_on-DockerHub%20%26%20GHCR-6ba6e5)
](https://hub.docker.com/r/lissy93/dashy)<br>
-**Status**: [
-![Docker Build Status](https://img.shields.io/docker/cloud/build/lissy93/dashy?label=Docker%20Build)
+**Status**:
+![Build Status](https://img.shields.io/github/actions/workflow/status/Lissy93/dashy/docker-build-publish.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 Cloud Build](https://img.shields.io/docker/cloud/automated/lissy93/dashy?color=f4a966&label=Docker%20Build)
-](https://hub.docker.com/r/lissy93/dashy)
+![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.
@@ -136,6 +130,38 @@ If you are building from source, and would like to use one of the [other Dockerf
---
+## Podman
+
+[Podman](https://podman.io/) is a drop-in replacement for Docker that runs containers without a daemon and doesn't require root. If you're on Fedora, RHEL, or just prefer daemonless containers, Podman works with the same images and mostly the same CLI.
+
+```bash
+podman run -d \
+ -p 8080:8080 \
+ -v /path/to/my-conf.yml:/app/user-data/conf.yml:Z \
+ --name dashy \
+ --restart=always \
+ docker.io/lissy93/dashy:latest
+```
+
+The `:Z` suffix on the volume mount handles SELinux relabeling, which you'll need on Fedora/RHEL. If you're not using SELinux, you can leave it off.
+
+Podman also supports `podman-compose` or `podman compose` (with the compose plugin) using the same `docker-compose.yml` file shown above.
+
+---
+
+## Portainer
+
+If you manage your Docker host through [Portainer](https://www.portainer.io/), you can deploy Dashy from its UI:
+
+1. Go to Stacks > Add stack
+2. Paste the [docker-compose.yml](https://github.com/Lissy93/dashy/blob/master/docker-compose.yml) contents, or point to the URL
+3. Adjust the port and volume mappings as needed
+4. Deploy the stack
+
+Alternatively, go to Containers > Add container and use the image `lissy93/dashy:latest` with port `8080` mapped.
+
+---
+
## Kubernetes
@vyrtualsynthese has written a Helm Chart for deploying with Kubernetes, available [here](https://github.com/vyrtualsynthese/selfhosted-helmcharts/tree/main/charts/dashy)
@@ -144,7 +170,22 @@ If you are building from source, and would like to use one of the [other Dockerf
## Unraid
-// TODO
+Dashy is available through the [Community Applications](https://forums.unraid.net/topic/38582-plug-in-community-applications/) plugin. Search for "Dashy" in the Apps tab and install from there. The template pre-fills the Docker image, port mapping, and volume paths for you.
+
+If you'd prefer to set it up manually, go to Docker > Add Container and use `lissy93/dashy:latest` as the repository. Map port `8080` and add a path mapping for your config file to `/app/user-data/conf.yml`.
+
+---
+
+## Home Server Platforms
+
+Several self-hosting platforms include Dashy in their app stores, giving you a one-click install with a management UI:
+
+- [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
+
+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/`.
---
@@ -189,168 +230,52 @@ If you do not want to use Docker, you can run Dashy directly on your host system
---
-## Deploy to cloud service
+## Deploy to Cloud Service
-If you don't have a home server, then fear not - Dashy can be deployed to pretty much any cloud provider. The above Docker and NPM guides will work exactly the same on a VPS, but I've also setup some 1-Click deploy links for 10+ of the most common cloud providers, to make things easier. Note that if your instance is exposed to the internet, it will be your responsibility to adequately secure it.
-
-Some hosting providers required a bit of extra configuration, which was why I've made separate branches for deploying to those services (named: [`deploy_cloudflare`](https://github.com/Lissy93/dashy/tree/deploy_cloudflare), [`deploy_digital-ocean`](https://github.com/Lissy93/dashy/tree/deploy_digital-ocean), [`deploy_platform-sh`](https://github.com/Lissy93/dashy/tree/deploy_platform-sh) and [`deploy_render`](https://github.com/Lissy93/dashy/tree/deploy_render)). If there's another cloud service which you'd like 1-click deployment to be supported for, feel free to raise an issue.
+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.
> [!NOTE]
-> If you use a static hosting provider, then status checks, writing new config changes to disk from the UI, and triggering a rebuild through the UI will not be available. This is because these features need endpoints provided by Dashy's local Node server. Everything else should work just the same though.
+> Static hosting providers (Netlify, Vercel, EdgeOne) won't have status checks, config writing to disk, or UI-triggered rebuilds, since those features need Dashy's Node server. Everything else works fine.
### Netlify
-[![Deploy to Netlify](https://i.ibb.co/GtKMysT/deploy-netlify-button.png)](https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy)
-
-[Netlify](https://www.netlify.com/) offers Git-based serverless cloud hosting for web applications. Their services are free to use for personal use, and they support deployment from both public and private repos, as well as direct file upload. The free plan also allows you to use your own custom domain or sub-domain, and is easy to setup.
-
-To deploy Dashy to Netlify, use the following link
+[![Deploy to Netlify](https://img.shields.io/badge/Deploy-Netlify-00C7B7?logo=netlify&logoColor=white)](https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy)
-```text
-https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy
-```
-
-### Heroku
-
-[![Deploy to Heroku](https://i.ibb.co/GdMFzBP/deploy-heroku-button.png)](https://heroku.com/deploy?template=https://github.com/Lissy93/dashy)
+Dashy includes a [`netlify.toml`](https://github.com/Lissy93/dashy/blob/master/netlify.toml) so deployment works out of the box. [Netlify](https://www.netlify.com/) is free for personal use, supports custom domains, and deploys automatically from your Git repo.
-[Heroku](https://www.heroku.com/) is a fully managed cloud platform as a service. You define app settings in a Procfile and app.json, which specifying how the app should be build and how the server should be started. Heroku costs a minimum of $5 for 1,000 dyno hours per month (there are around 720 hours in a month), and supports custom domains. Heroku's single-dyno service is not as quite performant as some other providers, and the app will have a short wake-up time when not visited for a while
-
-To deploy Dashy to Heroku, use the following link
-
-```text
-https://heroku.com/deploy?template=https://github.com/Lissy93/dashy
-```
+Deploy link: `https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy`
### Vercel
-[![Deploy with Vercel](https://i.ibb.co/mJF3R7m/deploy-vercel-button.png)](https://vercel.com/new/project?template=https://github.com/lissy93/dashy)
-
-[Vercel](https://vercel.com/) is a performance-focused platform for hosting static frontend apps. It comes bundled with some useful tools for monitoring and analyzing application performance and other metrics. Vercel is free for personal use, allows for custom domains and has very reasonable limits.
-
-To deploy Dashy to Vercel, use the following link
-
-```text
-https://vercel.com/new/project?template=https://github.com/lissy93/dashy
-```
-
-### DigitalOcean
-
-[![Deploy to DO](https://i.ibb.co/PFt0PkB/deploy-digital-ocean-button.png)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean&refcode=3838338e7f79)
-
-[DigitalOcean](https://www.digitalocean.com/) is a cloud service providing affordable developer-friendly virtual machines from $5/month. But they also have an app platform, where you can run web apps, static sites, APIs and background workers. CDN-backed static sites are free for personal use.
-
-```text
-https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean
-```
-
-### Google Cloud Platform
-
-[![Run on Google Cloud](https://i.ibb.co/LkvHttd/deploy-google-cloud-button.png)](https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git)
+[![Deploy with Vercel](https://img.shields.io/badge/Deploy-Vercel-000000?logo=vercel&logoColor=white)](https://vercel.com/new/project?template=https://github.com/lissy93/dashy)
-[Cloud Run](https://cloud.google.com/run/) is a service offered by [Google Cloud](https://cloud.google.com/). It's a fully managed serverless platform, for developing and deploying highly scalable containerized applications. Similar to AWS and Azure, GCP offers a wide range of cloud services, which are billed on a pay‐per‐use basis, but Cloud Run has a [free tier](https://cloud.google.com/run/pricing) offering 180,000 vCPU-seconds, 360,000 GiB-seconds, and 2 million requests per month.
+[Vercel](https://vercel.com/) hosts static frontends with a generous free tier, custom domains, and built-in analytics.
-To deploy Dashy to GCP, use the following link
+Deploy link: `https://vercel.com/new/project?template=https://github.com/lissy93/dashy`
-```text
-https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git
-```
-
-### Platform.sh
-
-[![Deploy to Platform.sh](https://i.ibb.co/nPnJgJP/deploy-platform-sh-button.png)](https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy&utm_campaign=deploy_on_platform?utm_medium=button&utm_source=affiliate_links&utm_content=https://github.com/lissy93/dashy)
-
-[Platform.sh](https://platform.sh) is an end-to-end solution for developing and deploying applications. It is geared towards enterprise users with large teams, and focuses on allowing applications to scale up and down. Unlike the above providers, Platform.sh is not free, although you can deploy a test app to it without needing a payment method
-
-To deploy Dashy to Platform.sh, use the following link
-
-```text
-https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy
-```
-
-### Render
-
-[![Deploy to Render](https://i.ibb.co/QXNCbxT/deploy-render-button.png)](https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render)
-
-[Render](https://render.com) is cloud provider that provides easy deployments for static sites, Docker apps, web services, databases and background workers. Render is great for developing applications, and very easy to use. Static sites are free, and services start at $7/month. Currently there are only 2 server locations - Oregon, USA and Frankfurt, Germany. For more info, see the [Render Docs](https://render.com/docs)
-
-To deploy Dashy to Render, use the following link
-
-```text
-https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render
-```
-
-### Railway
-
-[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/MtdjAQ?referralCode=app)
+### Easypanel
-[Railway](https://railway.app/) is a Platform as a Service (PaaS) that offers a complete platform for building and delivering programs to the backend of the cloud. You bring your code and Railway does the rest. Railway offers an extremely good developer experience and makes it effortless to deploy apps. Railway offers a free Trial Plan, and paid plans start at $5/month. Railway has 4 server locations: US-west, US-east, EU-west and ASIA-South-East.
+[![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)
-```text
-https://railway.app/template/MtdjAQ
-```
+[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.
-### Scalingo
+Template: `https://easypanel.io/docs/templates/dashy`
-[![Deploy on Scalingo](https://i.ibb.co/nj0KxyH/deploy-scalingo-button.png)](https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master)
+### EdgeOne Pages
-[Scalingo](https://scalingo.com/) is a scalable container-based cloud platform as a service. It's focus is on compliance and uptime, and is geared towards enterprise users. Scalingo is also not free, although they do have a 3-day free trial that does not require a payment method.
+[![Deploy to EdgeOne](https://cdnstatic.tencentcs.com/edgeone/pages/deploy.svg)](https://edgeone.ai/pages/new?repository-url=https://github.com/lissy93/dashy)
-To deploy Dashy to Scalingo, use the following link
+[EdgeOne Pages](https://pages.edgeone.ai) is Tencent's edge hosting platform. Static deploy from your Git repo.
-```text
-https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master
-```
+Deploy link: `https://edgeone.ai/pages/new?repository-url=https://github.com/lissy93/dashy`
### Play-with-Docker
-[![Try in PWD](https://i.ibb.co/SfbH7Zy/deploy-pwd-button.png)](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/) is a community project by Marcos Liljedhal and Jonathan Leibiusky and sponsored by Docker, intended to provide a hands-on learning environment. Their labs let you quickly spin up a Docker container or stack, and test out the image in a temporary, sandboxed environment. There's no need to sign up, and it's completely free.
-
-To run Dashy in PWD, use the following URL:
-
-```text
-https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml
-```
+[![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)
-### Surge.sh
+[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.
-![Follow instructions below](https://i.ibb.co/XkcKzKz/deploy-surge-button.png)
-
-[Surge.sh](http://surge.sh/) is quick and easy static web publishing platform for frontend-apps.
-Surge supports [password-protected projects](https://surge.sh/help/adding-password-protection-to-a-project). You can also [add a custom domain](https://surge.sh/help/adding-a-custom-domain) and then [force HTTPS by default](https://surge.sh/help/using-https-by-default) and optionally [set a custom SSL certificate](https://surge.sh/help/securing-your-custom-domain-with-ssl)
-
-To deploy Dashy to Surge.sh, first clone and cd into Dashy, install dependencies, and then use the following commands
-
-```bash
-yarn add -g surge
-yarn build
-surge ./dist
-```
-
-### Easypanel
-
-[![Deploy to Easypanel](https://i.ibb.co/ZNPwQX3/deploy-easypanel-button.png)](https://easypanel.io/docs/templates/dashy)
-
-[Easypanel](https://easypanel.io) it's a modern server control panel. You can use it to deploy Dashy on your own server.
-
-To deploy Dashy to Easypanel, use the following link
-
-```text
-https://easypanel.io/docs/templates/dashy
-```
-
-### 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)
-
-[EdgeOne Pages](https://pages.edgeone.ai) it's a is built on a cloud-edge integrated architecture, combining hosting, acceleration, computing, and integration to enable faster and more efficient deployments.
-To deploy Dashy to EdgeOne, use the following link
-
-```text
-https://edgeone.ai/pages/new?repository-url=https://github.com/lissy93/dashy
-```
+URL: `https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml`
---
@@ -370,22 +295,29 @@ Dashy works well on a Raspberry Pi (tested on Pi 3 and later), but should also r
### Docker
-Initial app build causes a spike in resource usage, but once the built app is running it is fairly steady. For this reason, Dashy works best with a minimum of 1GB of memory, and 1GB of disk space.
+The initial build causes a spike in resource usage, but once running it's fairly steady. Minimum 1GB memory and 1GB disk space.
### Bare Metal
-Minimum 526mb mem, 2GB disk space.
+Requires [Node.js](https://nodejs.org/) (v17 recommended) and [Yarn](https://yarnpkg.com/). The `engines` field in `package.json` specifies `>=16.0.0`, but the Docker image uses Node 20 and that's the best-tested version. Builds require the `--openssl-legacy-provider` flag, which the npm scripts already set.
-### CDN / Cloud Deploy
+Minimum 512MB memory, 2GB disk space.
-No specific requirements. The built application alone (without the Node server) is very light-weight, and can be handled smoothly by pretty much any CDN or cloud deployment service (see [this list](/docs/deployment.md#deploy-to-cloud-service) or natively supported cloud providers).
+### CDN / Cloud Deploy
-If you're using your own icons, or other assets, additional disk space will be required for those resources.
+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 to run Dashy.
-
-In terms of browser support, pretty much any browser released since 2018 should render content just fine. However, for Internet Explorer, only IE11+ is supported, yet performance here is still not optimal. The recommended browser is either a Chromium-based / Webkit browser (Chrome, Brave, Vivaldi, Edge, Yandex, etc), or Firefox or one of it's forks (FF-ESR, Tor, LibreWolf, etc). Recent versions of Safari and Opera are also supported, but with limited continuous testing.
-
-<p align="center"><img width="500" src="https://i.ibb.co/pjnmbw9/browser-compatibility.png" /></p>
+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 |
+|---------|----------------|--------|
+| Chrome / Chromium | 90+ | Fully supported |
+| Firefox | 90+ | Fully supported |
+| Edge | 90+ | Fully supported |
+| Safari | 14+ | Supported |
+| Opera | 76+ | Supported |
+| Samsung Internet | 15+ | Supported |
+| Firefox ESR | Latest | Supported |
+| Internet Explorer | - | Not supported |