Deploying Hubleys

Introduction

Hubleys is a personal dashboard application designed to be your browser’s start page. It provides a clean interface with dynamic backgrounds from Unsplash, weather information from OpenWeatherMap, and customizable link sections. The dashboard supports multiple users and groups with different access levels.

Built for simplicity and aesthetics, Hubleys focuses on providing a pleasant, informative homepage experience. The dynamic backgrounds change regularly, and the weather widget keeps you informed at a glance. The link sections can be organized to provide quick access to your most-used services.

Key highlights of Hubleys:

• Dynamic Backgrounds: Beautiful images from Unsplash
• Weather Widget: Current weather and forecasts
• Link Organization: Customizable link sections
• User Management: Support for multiple users
• Group Access: Control who sees what
• Clean Design: Minimalist, distraction-free interface
• Lightweight: Simple Docker deployment

This guide walks through deploying Hubleys on Klutch.sh using Docker, configuring integrations, and setting up your dashboard.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Hubleys configuration
• (Optional) An Unsplash API key for backgrounds
• (Optional) An OpenWeatherMap API key for weather
• Basic familiarity with Docker and containerization concepts

Preparing Your Repository

Create a GitHub repository with the following structure:

hubleys-deploy/
├── Dockerfile
├── config.yml
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile using the Hubleys image:

FROM ghcr.io/knrdl/hubleys-dashboard:latest

# Copy configuration
COPY config.yml /data/config.yml

# Environment variables for API keys
ENV OPENWEATHERMAP_API_KEY=${OPENWEATHERMAP_API_KEY}
ENV UNSPLASH_API_KEY=${UNSPLASH_API_KEY}

# Expose the application port
EXPOSE 8080

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

Hubleys Configuration File

Create config.yml:

# Hubleys Configuration

# Weather configuration (requires API key)
weather:
  enabled: true
  location: "New York,US"
  units: metric  # or imperial

# Background configuration (requires API key)
backgrounds:
  enabled: true
  collection: "nature"
  refresh_interval: 3600  # seconds

# User and group configuration
users:
  - username: admin
    password_hash: "$2b$12$..."  # Use bcrypt hash
    groups:
      - admins
      - users

groups:
  - name: admins
    sections:
      - all
  - name: users
    sections:
      - public

# Link sections
sections:
  - name: Media
    id: media
    access: users
    links:
      - name: Plex
        url: https://plex.example.com
        icon: plex

      - name: Jellyfin
        url: https://jellyfin.example.com
        icon: jellyfin

  - name: Tools
    id: tools
    access: admins
    links:
      - name: Portainer
        url: https://portainer.example.com
        icon: portainer

      - name: Grafana
        url: https://grafana.example.com
        icon: grafana

Environment Variables Reference

Variable	Required	Description
OPENWEATHERMAP_API_KEY	No	API key for weather data
UNSPLASH_API_KEY	No	API key for background images

Deploying Hubleys on Klutch.sh

Get API Keys (Optional)

For full functionality, obtain:

• Unsplash API key from Unsplash Developers
• OpenWeatherMap API key from OpenWeatherMap

Create Configuration

Customize your config.yml with your links and settings.

Push Your Repository to GitHub

git init
git add Dockerfile config.yml .dockerignore README.md
git commit -m "Initial Hubleys deployment configuration"
git remote add origin https://github.com/yourusername/hubleys-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 named “hubleys” or “startpage”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Hubleys repository.

Configure HTTP Traffic

• Select HTTP as the traffic type
• Set the internal port to 8080

Set Environment Variables

Configure the following environment variables:

Variable	Value
OPENWEATHERMAP_API_KEY	Your OpenWeatherMap API key
UNSPLASH_API_KEY	Your Unsplash API key

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
/data	1 GB	Configuration and user data

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and start Hubleys with HTTPS enabled.

Access Hubleys

Once deployment completes, access your dashboard at https://your-app-name.klutch.sh.

Customizing Hubleys

Configuring Weather

Set your location for accurate weather:

weather:
  enabled: true
  location: "London,UK"  # City,Country code
  units: metric  # or imperial

Background Settings

Configure dynamic backgrounds:

backgrounds:
  enabled: true
  collection: "nature"  # Unsplash collection
  refresh_interval: 3600  # How often to change

Popular Unsplash collections:

• nature
• architecture
• minimal
• landscapes

Organizing Links

Create sections for different categories:

sections:
  - name: "Work"
    links:
      - name: "Email"
        url: "https://mail.example.com"
        icon: "email"

User Management

Create users with bcrypt password hashes:

# Generate password hash (use online bcrypt generator or htpasswd)
htpasswd -nbBC 12 "" yourpassword | tr -d ':\n' | sed 's/$2y/$2b/'

Add to configuration:

users:
  - username: user1
    password_hash: "$2b$12$..."
    groups:
      - users

Access Control

Control section visibility with groups:

groups:
  - name: family
    sections:
      - media
      - general

sections:
  - name: Media
    id: media
    access: family

Troubleshooting

Weather Not Loading

• Verify API key is correct
• Check location format (City,Country)
• Ensure API key has appropriate permissions

Backgrounds Not Changing

• Verify Unsplash API key
• Check collection name exists
• Review API rate limits

Login Issues

• Verify password hash format
• Check username matches exactly
• Ensure group access is configured

Additional Resources

• Hubleys GitHub Repository
• Unsplash API Documentation
• OpenWeatherMap API
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Hubleys on Klutch.sh creates a beautiful, functional start page with dynamic backgrounds and weather information. The simple configuration and multi-user support make it suitable for personal use or sharing with family members. With persistent storage for your settings and the aesthetic touches of Unsplash backgrounds, Hubleys provides a pleasant daily homepage experience.