Deploying HomeServerHQ

Introduction

HomeServerHQ is a self-hosted dashboard designed to centralize the management and monitoring of home server services. It provides a unified web interface where you can view the status of all your self-hosted applications, access quick links, monitor system resources, and organize your homelab infrastructure.

Built with modern web technologies, HomeServerHQ offers a clean, customizable dashboard experience that makes it easy to keep track of multiple services running across your home network or cloud infrastructure. The application focuses on simplicity and usability while providing essential monitoring capabilities.

Key highlights of HomeServerHQ:

• Unified Dashboard: View all your self-hosted services from a single, organized interface
• Service Status Monitoring: Real-time health checks and status indicators for your applications
• Quick Access Links: One-click access to all your service web interfaces
• Customizable Layout: Organize services into categories and customize the appearance
• Resource Monitoring: Track CPU, memory, and disk usage across your infrastructure
• Mobile Responsive: Access your dashboard from any device with a responsive design
• Docker Integration: Native support for Docker container monitoring
• Lightweight: Minimal resource footprint for running alongside other services
• Self-Hosted: Complete control over your data with no external dependencies

This guide walks through deploying HomeServerHQ on Klutch.sh using Docker, configuring the dashboard for your services, and setting up the application for daily use.

Why Deploy HomeServerHQ on Klutch.sh

Deploying HomeServerHQ on Klutch.sh provides several advantages for managing your home server infrastructure:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds HomeServerHQ without complex orchestration or manual server configuration. Push to GitHub, and your dashboard deploys automatically.

Persistent Storage: Attach persistent volumes for your configuration and customizations. Your dashboard settings survive container restarts and redeployments without data loss.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your dashboard from anywhere without manual certificate management.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates to your Dockerfile trigger automatic redeployments, keeping your deployment in sync with your repository.

Scalable Resources: Allocate CPU and memory based on your monitoring needs. HomeServerHQ is lightweight, so minimal resources are typically sufficient.

Environment Variable Management: Securely store sensitive configuration through Klutch.sh’s environment variable system without exposing credentials in your repository.

Custom Domains: Assign a custom domain to your HomeServerHQ instance for easy access to your homelab dashboard.

Always-On Availability: Your dashboard remains accessible 24/7 without managing your own hardware or dealing with home network configuration.

Prerequisites

Before deploying HomeServerHQ on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your HomeServerHQ configuration
• Basic familiarity with Docker and containerization concepts
• A list of services you want to monitor and their URLs
• (Optional) A custom domain for your HomeServerHQ instance

Understanding HomeServerHQ Architecture

HomeServerHQ is built on a streamlined architecture designed for reliability:

Web Frontend: The dashboard interface is built with modern JavaScript frameworks, providing a responsive and interactive user experience.

Backend API: A lightweight backend handles service status checks, configuration management, and real-time updates.

Configuration Storage: Service definitions and dashboard settings are stored in configuration files, making it easy to back up and version control.

Health Check System: Periodic health checks monitor the status of configured services and update the dashboard in real-time.

Preparing Your Repository

To deploy HomeServerHQ on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

homeserverhq-deploy/
├── Dockerfile
├── config/
│   └── services.json
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM homeserverhq/homeserverhq:latest

# Set environment variables
ENV NODE_ENV=production
ENV PORT=3000

# Copy custom configuration if needed
COPY config/ /app/config/

# Expose the web interface port
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

Configuration File

Create a config/services.json file to define your monitored services:

{
  "services": [
    {
      "name": "Jellyfin",
      "url": "https://jellyfin.example.com",
      "icon": "jellyfin",
      "category": "Media"
    },
    {
      "name": "Nextcloud",
      "url": "https://cloud.example.com",
      "icon": "nextcloud",
      "category": "Productivity"
    }
  ],
  "categories": [
    "Media",
    "Productivity",
    "Infrastructure"
  ]
}

Creating the .dockerignore File

Create a .dockerignore file to exclude unnecessary files from the build:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
node_modules/
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
PORT	No	3000	Port for the web interface
NODE_ENV	No	production	Node.js environment setting
BASE_URL	No	-	Base URL for the application
CHECK_INTERVAL	No	60	Seconds between health checks

Deploying HomeServerHQ on Klutch.sh

Once your repository is prepared, follow these steps to deploy HomeServerHQ:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile config/ .dockerignore README.md
git commit -m "Initial HomeServerHQ deployment configuration"
git remote add origin https://github.com/yourusername/homeserverhq-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “homeserverhq” or “homelab-dashboard”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your HomeServerHQ Dockerfile.

Configure HTTP Traffic

HomeServerHQ serves its web interface over HTTP. In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000 (default port)

Set Environment Variables

In the environment variables section, add the following:

Variable	Value
NODE_ENV	production
BASE_URL	https://example-app.klutch.sh
CHECK_INTERVAL	60

Attach Persistent Volumes

Persistent storage preserves your configuration. Add the following volumes:

Mount Path	Recommended Size	Purpose
/app/config	100 MB	Service configuration and settings
/app/data	500 MB	Dashboard data and customizations

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the HomeServerHQ container
• Provision an HTTPS certificate

Access HomeServerHQ

Once deployment completes, access your HomeServerHQ instance at https://example-app.klutch.sh. You can begin configuring your services and customizing your dashboard.

Initial Setup and Configuration

Adding Services

After accessing your dashboard, add services you want to monitor:

1. Navigate to the Settings section
2. Click Add Service
3. Enter the service name, URL, and select an icon
4. Assign the service to a category
5. Save and watch the service appear on your dashboard

Customizing Categories

Organize your services logically:

• Media: Jellyfin, Plex, Navidrome
• Productivity: Nextcloud, Paperless-ngx, Bookstack
• Infrastructure: Portainer, Traefik, Pi-hole
• Monitoring: Grafana, Uptime Kuma, Prometheus

Theme Customization

HomeServerHQ supports visual customization:

1. Access Settings > Appearance
2. Choose a color scheme
3. Adjust layout preferences
4. Set a custom background if desired

Production Best Practices

Security Recommendations

• Access Control: Consider using an authentication proxy for your dashboard
• HTTPS Only: Always access your dashboard over HTTPS
• Regular Updates: Keep HomeServerHQ updated for security patches
• Firewall Rules: Restrict access to trusted networks when possible

Performance Optimization

• Check Intervals: Balance monitoring frequency with performance needs
• Service Count: Monitor only essential services to reduce overhead
• Resource Allocation: HomeServerHQ is lightweight; minimal resources suffice

Backup Strategy

Protect your configuration:

1. Configuration Backups: Regularly back up /app/config
2. Version Control: Keep your services.json in Git
3. Export Settings: Use any built-in export functionality

Troubleshooting Common Issues

Services Show as Offline

Symptoms: Services display as offline when they are running.

Solutions:

• Verify the service URLs are accessible from the HomeServerHQ container
• Check that health check endpoints are responding
• Review network connectivity between HomeServerHQ and your services
• Ensure SSL certificates are valid if using HTTPS URLs

Dashboard Not Loading

Symptoms: Browser cannot connect to HomeServerHQ.

Solutions:

• Verify the deployment is running in the Klutch.sh dashboard
• Confirm HTTP traffic type is selected with port 3000
• Check container logs for startup errors
• Clear browser cache and try again

Configuration Changes Not Saving

Symptoms: Dashboard reverts to default settings after restart.

Solutions:

• Verify persistent volumes are correctly mounted
• Check write permissions on the config directory
• Ensure the volume has sufficient space

Additional Resources

• HomeServerHQ GitHub Repository
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying HomeServerHQ on Klutch.sh gives you a centralized dashboard for monitoring and accessing all your self-hosted services. The combination of HomeServerHQ’s clean interface and Klutch.sh’s deployment simplicity means you can focus on managing your homelab rather than infrastructure.

With service status monitoring, quick access links, and customizable organization, HomeServerHQ transforms how you interact with your self-hosted applications. Whether you’re running a few services or managing an extensive homelab, HomeServerHQ on Klutch.sh provides a reliable, always-available command center for your infrastructure.