Skip to content

deployment

Jump to bottom
liss-bot edited this page Apr 12, 2026 · 25 revisions

Deployment

Welcome to Dashy, so glad you're here :) Deployment is super easy, and there are several methods available depending on what type of system you're using. If you're self-hosting, then deploying with Docker (or similar container engine) is the recommended approach.

Quick Start

If you want to skip the fuss, and get straight down to it, then you can spin up a new instance of Dashy by running:

docker run -p 8080:8080 lissy93/dashy

See Management Docs for info about securing, monitoring, updating, health checks, auto starting, web server configuration, etc

Once you've got Dashy up and running, you'll want to configure it with your own content, for this you can reference the configuring docs.

Deployment Methods

Deploy with Docker

Container Info: Docker Supported Architecture Docker Base Image Docker Hosted on
Status: Build Status Docker Pulls Docker Stars Docker Image Size Docker Latest Version

Dashy has a built container image hosted on Docker Hub. You will need Docker installed on your system.

docker run -d \
  -p 8080:8080 \
  -v /root/my-local-conf.yml:/app/user-data/conf.yml \
  --name my-dashboard \
  --restart=always \
  lissy93/dashy:latest

Explanation of the above options:

  • -d Detached mode (not running in the foreground of your terminal)
  • -p The port that should be exposed, and the port it should be mapped to in your host system [host-port][container-port], leave the container port as is
  • -v Specify volumes, to pass data from your host system to the container, in the format of [host-path]:[container-path], you can use this to pass your config file, directory of assets (like icons), custom CSS or web assets (like favicon.ico, manifest.json etc)
  • --name Give your container a human-readable name
  • --restart=always Spin up the container when the daemon starts, or after it has been stopped
  • lissy93/dashy:latest This last option is the image the container should be built from, you can also use a specific version or architecture type, by replacing :latest with one of the tags

For all available options, and to learn more, see the Docker Run Docs

Dashy is also available through GHCR: docker pull ghcr.io/lissy93/dashy:latest

If you're deploying Dashy on a modern ARM-based board, such as a Raspberry Pi (2+), then you'll need to use one of Dashy's ARM images. Set the base image + tag to either lissy93/dashy:arm64v8 or lissy93/dashy:arm32v7, depending on your system architecture. You can also use the multi-arch image, which should work on all system architectures.

The image defaults to :latest, but you can instead specify a specific version, e.g. docker pull lissy93/dashy:release-1.5.0

Using Docker Compose

Using Docker Compose can be useful for saving your specific config in files, without having to type out a long run command each time. Save compose config as a YAML file, and then run docker compose up -d (optionally use the -f flag to specify file location, if it isn't located at ./docker-compose.yml), -d is detached mode (not running in the foreground of your terminal). Compose is also useful if you are using clusters, as the format is very similar to stack files, used with Docker Swarm.

The following is a complete example of a docker-compose.yml for Dashy. Run it as is, or uncomment the additional options you need.

---
services:
  dashy:
    # To build from source, replace 'image: lissy93/dashy' with 'build: .'
    # build: .
    image: lissy93/dashy
    container_name: Dashy
    # Pass in your config file below, by specifying the path on your host machine
    # volumes:
      # - /root/my-config.yml:/app/user-data/conf.yml
    ports:
      - 8080:8080
    # Set any environmental variables
    environment:
      - NODE_ENV=production
    # Specify your user ID and group ID. You can find this by running `id -u` and `id -g`
    #  - UID=1000
    #  - GID=1000
    # Specify restart policy
    restart: unless-stopped
    # Configure healthchecks
    healthcheck:
      test: ['CMD', 'node', '/app/services/healthcheck']
      interval: 1m30s
      timeout: 10s
      retries: 3
      start_period: 40s

You can use a different tag, by for example setting image: lissy93/dashy:arm64v8, or pull from GHCR instead by setting image: ghcr.io/lissy93/dashy.

If you are building from source, and would like to use one of the other Dockerfiles, then under services.dashy first set context: ., then specify the the path to the dockerfile, e.g. dockerfile: ./docker/Dockerfile-arm32v7

Podman

Podman 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.

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, you can deploy Dashy from its UI:

  1. Go to Stacks > Add stack
  2. Paste the 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

Unraid

Dashy is available through the 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 - Has Dashy in its built-in app store
  • Cosmos Cloud - Install Dashy from the marketplace
  • Umbrel - Available in the Umbrel App Store
  • Runtipi - 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/.

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.

    Note: Be careful to enter only lowercase, not uppercase letters.

  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.

docker run -d \
  -p 4000:8080 \
  -v /volume1/docker/dashy/my-local-conf.yml:/app/user-data/conf.yml \
  --name dashy \
  --restart=always \
  lissy93/dashy:latest

dashy should be up within 1-2min after you've started the install task procedure

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 and the latest or LTS version of Node.js installed, and optionally yarn

  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
  3. Install dependencies: yarn
  4. Build: yarn build
  5. Run: yarn start

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.

Note

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

Dashy includes a netlify.toml so deployment works out of the box. Netlify is free for personal use, supports custom domains, and deploys automatically from your Git repo.

Deploy link: https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy

Vercel

Deploy with Vercel

Vercel hosts static frontends with a generous free tier, custom domains, and built-in analytics.

Deploy link: https://vercel.com/new/project?template=https://github.com/lissy93/dashy

Easypanel

Deploy to Easypanel

Easypanel 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

EdgeOne Pages

Deploy to EdgeOne

EdgeOne Pages is Tencent's edge hosting platform. Static deploy from your Git repo.

Deploy link: https://edgeone.ai/pages/new?repository-url=https://github.com/lissy93/dashy

Play-with-Docker

Try in PWD

Play with Docker gives you a free, temporary Docker environment in the browser. Good for trying Dashy without installing anything. Sessions last 4 hours.

URL: https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml

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.

However without Dashy's node server, there are a couple of features that will be unavailable to you, including: Writing config changes to disk through the UI, triggering a rebuild through the UI and application status checks. Everything else will work fine.

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

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

Requires Node.js (v17 recommended) and Yarn. 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.

Minimum 512MB memory, 2GB disk space.

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). 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

Clone this wiki locally