Skip to content
Klutch.sh Docs

Deploying Dashy

Introduction

Dashy is a feature-rich, self-hosted dashboard application that helps you organize and access all your self-hosted services from a single, beautiful interface. With support for multiple pages, real-time status monitoring, customizable themes, widgets, and authentication, Dashy provides a centralized hub for managing your homelab or production services.

This comprehensive guide walks you through deploying Dashy on Klutch.sh using a Dockerfile. You’ll learn how to set up the application, configure persistent storage for your dashboard configuration, customize environment variables, and implement production-ready best practices for a reliable and scalable deployment.

Prerequisites

Before you begin deploying Dashy on Klutch.sh, ensure you have:

  • A Klutch.sh account (sign up here)
  • A GitHub repository containing your Dashy Dockerfile and configuration files
  • Basic understanding of Docker and YAML configuration
  • (Optional) A custom domain for accessing your dashboard

Project Structure

A typical Dashy deployment on Klutch.sh requires the following repository structure:

dashy-klutch/
├── Dockerfile
├── conf.yml (optional - can be added later)
└── README.md

The conf.yml file is optional at deployment time. You can create and configure it through Dashy’s built-in UI editor after the initial deployment, or you can include a pre-configured file in your repository.

Sample Dockerfile

Dashy provides an official Docker image that can be used directly, or you can create a custom Dockerfile for more control. Here are two approaches:

For most deployments, using the official Dashy image is the simplest approach:

FROM lissy93/dashy:latest


# Optional: Copy a pre-configured conf.yml
# COPY conf.yml /app/user-data/conf.yml


# Expose the default port
EXPOSE 8080


# The official image already has the correct CMD

Approach 2: Custom Build from Source

If you need to customize the build process or include specific modifications:

FROM node:18.19.1-alpine AS BUILD_IMAGE


# Set the platform to build image for
ARG TARGETPLATFORM
ENV TARGETPLATFORM=${TARGETPLATFORM:-linux/amd64}


# Install additional tools needed if on arm64 / armv7
RUN \
  case "${TARGETPLATFORM}" in \
  'linux/arm64') apk add --no-cache python3 make g++ ;; \
  'linux/arm/v7') apk add --no-cache python3 make g++ ;; \
  esac


# Create and set the working directory
WORKDIR /app


# Clone Dashy repository
RUN apk add --no-cache git && \
    git clone https://github.com/Lissy93/dashy.git . && \
    git checkout 3.1.1


# Install app dependencies
RUN yarn install --frozen-lockfile --network-timeout 300000


# Build initial app for production
RUN yarn build


# Production stage
FROM node:20.11.1-alpine3.19


# Define some ENV Vars
ENV PORT=8080 \
  DIRECTORY=/app \
  IS_DOCKER=true


# Create and set the working directory
WORKDIR ${DIRECTORY}


# Update tzdata for setting timezone
RUN apk add --no-cache tzdata


# Copy built application from build phase
COPY --from=BUILD_IMAGE /app ./


# Create user-data directory for persistent storage
RUN mkdir -p /app/user-data


# Expose the port
EXPOSE ${PORT}


# Finally, run start command
CMD [ "yarn", "build-and-start" ]

Note: For most use cases, the official image (Approach 1) is recommended as it’s maintained by the Dashy team and includes all necessary optimizations.

Configuration File

Dashy uses a conf.yml file for all configuration. You can either:

  1. Start with a minimal config and use Dashy’s built-in UI editor
  2. Pre-configure your dashboard before deployment

Minimal Configuration Example

Create a conf.yml file in your repository:

pageInfo:
  title: My Dashboard
  description: Welcome to my Dashy dashboard
  navLinks:
    - title: GitHub
      path: https://github.com
appConfig:
  theme: default
  layout: auto
  iconSize: medium
  language: en
sections:
  - name: Getting Started
    icon: fas fa-rocket
    items:
      - title: Dashy Documentation
        description: Official Dashy docs
        icon: fas fa-book
        url: https://dashy.to/docs
        target: newtab
      - title: GitHub Repository
        description: View on GitHub
        icon: fab fa-github
        url: https://github.com/Lissy93/dashy
        target: newtab

Advanced Configuration Example

For a more feature-rich dashboard:

pageInfo:
  title: Production Dashboard
  description: Self-hosted services management
  logo: https://i.ibb.co/yhbt6CY/dashy.png
  navLinks:
    - title: Documentation
      path: https://docs.example.com
    - title: Status Page
      path: https://status.example.com


appConfig:
  theme: nord
  layout: auto
  iconSize: medium
  language: en
  statusCheck: true
  statusCheckInterval: 60
  disableConfiguration: false
  enableMultiTasking: true
  webSearch:
    disableWebSearch: false
    searchEngine: duckduckgo
  auth:
    enableGuestAccess: true
    users:
      - user: admin
        hash: your-hashed-password-here
        type: admin


sections:
  - name: Monitoring
    icon: fas fa-chart-line
    displayData:
      collapsed: false
      rows: 2
    items:
      - title: Grafana
        description: Metrics Dashboard
        icon: hl-grafana
        url: https://grafana.example.com
        statusCheck: true
        target: newtab


      - title: Prometheus
        description: Metrics Collection
        icon: hl-prometheus
        url: https://prometheus.example.com
        statusCheck: true
        target: newtab


  - name: Infrastructure
    icon: fas fa-server
    items:
      - title: Portainer
        description: Container Management
        icon: hl-portainer
        url: https://portainer.example.com
        statusCheck: true
        target: newtab


  - name: Media
    icon: fas fa-photo-video
    displayData:
      collapsed: false
    items:
      - title: Jellyfin
        description: Media Server
        icon: hl-jellyfin
        url: https://jellyfin.example.com
        target: newtab

Configuration Notes:

  • statusCheck: true enables real-time monitoring of service availability
  • statusCheckInterval defines how often (in seconds) to check service status
  • target: newtab ensures links open in new tabs (recommended)
  • Dashy supports Font Awesome icons (fas fa-*), Homelab icons (hl-*), and auto-fetched favicons

For password hashing, use Dashy’s built-in hash generator or run:

Terminal window
echo -n 'your-password' | sha256sum

Deploying to Klutch.sh

Follow these steps to deploy Dashy on Klutch.sh:

    Step 1: Prepare Your Repository

    • Create a new GitHub repository or use an existing one
    • Add your Dockerfile to the repository root
    • (Optional) Add your conf.yml configuration file to the root
    • Commit and push your changes to GitHub

    Step 2: Create a New App on Klutch.sh

    Step 3: Configure Your App

    In the app creation form, configure the following settings:

    • App Name: Choose a descriptive name (e.g., “dashy-dashboard”)
    • GitHub Repository: Select your repository containing the Dockerfile
    • Branch: Choose the branch to deploy (e.g., main or master)
    • Traffic Type: Select HTTP (Dashy is a web application)
    • Internal Port: Set to 8080 (Dashy’s default port)
    • Region: Choose your preferred deployment region
    • Compute Resources: Select based on your needs (minimum: 0.5 CPU, 512MB RAM)
    • Instances: Start with 1 instance (scale up as needed)

    Step 4: Configure Environment Variables

    Add the following environment variables in the Klutch.sh dashboard:

    Required Variables:

    • None (Dashy works with defaults)

    Optional Variables for Customization:

    • NODE_ENV - Set to production for production deployments
    • PORT - Custom port (default is 8080, but Klutch.sh will handle routing)
    • HOST - Set to 0.0.0.0 to bind to all interfaces (default)
    • UID - User ID for file permissions (default: 1000)
    • GID - Group ID for file permissions (default: 1000)

    Optional Security Variables:

    • AUTH_USERNAME - Enable basic HTTP auth with username
    • AUTH_PASSWORD - Password for basic HTTP auth

    Example Environment Variables:

    NODE_ENV=production
    HOST=0.0.0.0
    PORT=8080

    Step 5: Attach Persistent Storage

    Dashy stores its configuration and user data in /app/user-data. To persist your dashboard configuration across deployments:

    • In the Klutch.sh app settings, navigate to the Volumes section
    • Click “Add Volume” or “Attach Volume”
    • Mount Path: /app/user-data
    • Size: 1GB (more than sufficient for configuration files)

    This ensures your conf.yml and any customizations persist across container restarts and redeployments.

    Step 6: Deploy Your Application

    • Review all your settings
    • Click “Create” or “Deploy” to start the deployment
    • Klutch.sh will automatically detect your Dockerfile and build the image
    • Monitor the build logs to ensure successful deployment

    Step 7: Access Your Dashboard

    Once deployment is complete:

    • Your Dashy dashboard will be available at: https://your-app-name.klutch.sh
    • For production use, consider setting up a custom domain
    • Access the dashboard and configure it using the built-in editor (click the settings icon)

Customizing the Build Process

If you need to customize how Dashy is built or started, you can use Nixpacks environment variables:

Custom Start Command

To override the default start command:

Runtime Environment Variable:

  • NIXPACKS_START_CMD - Set to your custom start command

Example:

NIXPACKS_START_CMD=node server.js

Custom Build Command

To customize the build process:

Buildtime Environment Variable:

  • NIXPACKS_BUILD_CMD - Set to your custom build command

Example:

NIXPACKS_BUILD_CMD=yarn install && yarn build --mode production

Note: When using a Dockerfile, Klutch.sh automatically detects and uses it, so these Nixpacks variables are only relevant if you’re not using a Dockerfile.

Persistent Volumes Configuration

Dashy requires persistent storage for maintaining your dashboard configuration. Here’s what you need to know:

What to Persist

The /app/user-data directory contains:

  • conf.yml - Your dashboard configuration
  • backup.yml - Automatic backups of your configuration
  • auth.json - User authentication data (if using multi-user auth)
  • item-icons/ - Custom uploaded icons

Setting Up Volumes on Klutch.sh

    1. Navigate to Volumes: In your app settings on Klutch.sh, find the “Volumes” or “Storage” section

    2. Add a New Volume:

      • Click “Add Volume” or “Attach Volume”
      • Mount Path: /app/user-data
      • Size: 1-5GB (depending on your needs; 1GB is usually sufficient)

    3. Deploy/Redeploy: After attaching the volume, redeploy your app if it’s already running

Backing Up Your Configuration

To back up your Dashy configuration:

  1. Use Dashy’s built-in cloud backup feature
  2. Manually download conf.yml from the config editor
  3. Access the volume through Klutch.sh and download files (if available)

Advanced Configuration

Custom Themes

Dashy includes many built-in themes. To use them:

  1. Edit your conf.yml or use the UI config editor
  2. Set appConfig.theme to one of:
    • default, nord, nord-frost, material, material-dark
    • colorful, high-contrast-light, high-contrast-dark
    • dracula, one-dark, bee, tiger

Status Monitoring

Enable real-time status checks for your services:

appConfig:
  statusCheck: true
  statusCheckInterval: 60  # Check every 60 seconds


sections:
  - name: Services
    items:
      - title: My Service
        url: https://example.klutch.sh
        statusCheck: true
        statusCheckUrl: https://example.klutch.sh/health

Multi-User Authentication

Set up multiple users with different access levels:

appConfig:
  auth:
    enableGuestAccess: false
    users:
      - user: admin
        hash: your-sha256-hash
        type: admin
      - user: viewer
        hash: another-sha256-hash
        type: normal

Generate password hashes:

Terminal window
echo -n 'your-password' | sha256sum

Search Engine Integration

Configure web search directly from Dashy:

appConfig:
  webSearch:
    disableWebSearch: false
    searchEngine: duckduckgo
    openingMethod: newtab

Troubleshooting

Application Won’t Start

Issue: Container fails to start or crashes immediately

Solutions:

  • Check the Klutch.sh deployment logs for error messages
  • Verify that the internal port is set to 8080
  • Ensure your Dockerfile has proper syntax
  • Confirm that environment variables are correctly set

Configuration Changes Not Persisting

Issue: Dashboard configuration resets after redeployment

Solutions:

  • Verify that a persistent volume is attached to /app/user-data
  • Check that the volume is properly mounted in the Klutch.sh dashboard
  • Ensure file permissions are correct (UID/GID environment variables)

Services Not Showing Status

Issue: Status indicators show as “unknown” or don’t update

Solutions:

  • Ensure statusCheck: true is set in your configuration
  • Verify that the service URLs are accessible from the Dashy container
  • Check if services require authentication (use statusCheckHeaders if needed)
  • Increase statusCheckInterval if services are rate-limiting

Example with authentication:

items:
  - title: Authenticated Service
    url: https://secure.example.com
    statusCheck: true
    statusCheckHeaders:
      Authorization: Bearer your-token-here

Performance Issues

Issue: Dashboard is slow or unresponsive

Solutions:

  • Increase compute resources (CPU/RAM) in Klutch.sh
  • Reduce statusCheckInterval to decrease polling frequency
  • Disable unused widgets or features
  • Consider reducing the number of items per section

Cannot Access Dashboard

Issue: Unable to reach the dashboard URL

Solutions:

  • Verify the app is deployed and running in Klutch.sh
  • Check that traffic type is set to HTTP
  • Ensure the internal port matches Dashy’s configured port (8080)
  • Check Klutch.sh deployment logs for errors

Security Best Practices

1. Enable Authentication

Always enable authentication for production deployments:

appConfig:
  auth:
    enableGuestAccess: false
    users:
      - user: admin
        hash: your-secure-hash
        type: admin

2. Use HTTPS with Custom Domains

  • Configure a custom domain with Klutch.sh
  • Klutch.sh automatically provides SSL/TLS certificates
  • Ensure all service URLs use HTTPS where possible

3. Secure Environment Variables

  • Never commit sensitive data to your repository
  • Use Klutch.sh’s environment variables for secrets
  • Mark sensitive variables as “secret” in the dashboard

4. Regular Updates

  • Keep Dashy updated by rebuilding with the latest image
  • Monitor the Dashy releases page
  • Update your Dockerfile tag to specific versions rather than latest for production

5. Network Security

  • Limit access to your dashboard using Klutch.sh’s access controls
  • Consider using a VPN for accessing sensitive dashboards
  • Implement rate limiting if exposed to the internet

6. Configuration Backup

  • Regularly back up your conf.yml file
  • Use Dashy’s cloud backup feature for automated backups
  • Store backups securely outside the application

Scaling and Performance

Vertical Scaling

For better performance with many services and widgets:

  • Increase CPU allocation (0.5 → 1.0+ CPU cores)
  • Increase memory allocation (512MB → 1GB+ RAM)
  • Adjust in the Klutch.sh dashboard under app settings

Horizontal Scaling

Dashy supports multiple instances:

  • Increase instance count in Klutch.sh (1 → 2+ instances)
  • Klutch.sh automatically load balances traffic
  • Ensure persistent volumes are properly configured

Note: If using multi-user authentication with sessions, consider using sticky sessions or external session storage.

Performance Optimization

  • Minimize the number of status checks
  • Increase statusCheckInterval for less critical services
  • Use icon caching (built into Dashy)
  • Optimize image sizes in your configuration
  • Disable unnecessary widgets and features

Example: Production Deployment

Here’s a complete example for a production-ready Dashy deployment:

Repository Structure

dashy-production/
├── Dockerfile
├── conf.yml
├── .dockerignore
└── README.md

Dockerfile

FROM lissy93/dashy:3.1.1


# Copy production configuration
COPY conf.yml /app/user-data/conf.yml


# Set proper permissions
USER root
RUN chown -R 1000:1000 /app/user-data
USER 1000


EXPOSE 8080

.dockerignore

.git
.gitignore
node_modules
README.md
.env

Klutch.sh Configuration

Environment Variables:

NODE_ENV=production
HOST=0.0.0.0

Resources:

  • CPU: 1.0 cores
  • Memory: 1GB
  • Instances: 2
  • Region: US East

Storage:

  • Volume mounted at: /app/user-data
  • Size: 2GB

Networking:

  • Traffic Type: HTTP
  • Internal Port: 8080
  • Custom Domain: dashboard.example.com

Monitoring and Maintenance

Health Checks

Dashy includes a built-in health check endpoint:

GET /health

Configure health checks in Klutch.sh:

  • Health Check Path: /health
  • Health Check Interval: 30 seconds
  • Timeout: 5 seconds

Monitoring Recommendations

  • Monitor CPU and memory usage through Klutch.sh dashboard
  • Set up alerts for downtime or performance degradation
  • Track response times for your dashboard
  • Monitor volume usage to prevent storage issues

Maintenance Schedule

Establish a regular maintenance routine:

  1. Weekly: Review dashboard performance and logs
  2. Monthly: Update Dashy to the latest version
  3. Quarterly: Audit user access and authentication settings
  4. As Needed: Back up configuration files

Migration from Other Platforms

Migrating from Docker

If you’re currently running Dashy in Docker:

  1. Export your current conf.yml from your Docker volume
  2. Create a new GitHub repository with your Dockerfile
  3. Add your conf.yml to the repository
  4. Deploy to Klutch.sh following this guide
  5. Update DNS/domain settings to point to your new deployment

Migrating from Kubernetes

If you’re migrating from a Kubernetes deployment:

  1. Extract your Dashy configuration from ConfigMaps or Secrets
  2. Convert environment variables to Klutch.sh format
  3. Identify any persistent volumes and plan storage accordingly
  4. Deploy to Klutch.sh with equivalent resources
  5. Test thoroughly before switching traffic

Resources

Official Dashy Resources

Klutch.sh Resources

Community Resources

Conclusion

Deploying Dashy on Klutch.sh provides you with a powerful, customizable dashboard for managing all your self-hosted services and applications. With Klutch.sh’s automated Docker detection, persistent storage, and built-in SSL, you can focus on configuring your perfect dashboard without worrying about infrastructure management.

Whether you’re managing a homelab, coordinating a development team, or organizing production services, Dashy on Klutch.sh offers the flexibility, performance, and reliability you need. Start with the basic configuration provided in this guide, then customize and expand your dashboard as your needs grow.

For additional help or advanced configurations, consult the resources section above or reach out to the Dashy and Klutch.sh communities.