Deploying Homepage by gethomepage

Introduction

Homepage is a modern, fully static, fast, and secure application dashboard with integrations for over 100 services and translations into multiple languages. Designed as a customizable browser startpage, Homepage combines beautiful design with powerful functionality, including real-time service widgets, Docker integration, and extensive theming options.

Built with Next.js and designed for self-hosters, Homepage provides live status information from your services through its widget system. The dashboard supports YAML-based configuration, making it easy to version control and deploy consistently across environments.

Key highlights of Homepage:

• 100+ Integrations: Widgets for Sonarr, Radarr, Plex, and many more
• Docker Integration: Automatic service discovery from Docker labels
• Fast and Static: Server-rendered for optimal performance
• Customizable: YAML configuration with extensive theming
• Secure: No client-side requests to third-party services
• Responsive: Works on desktop, tablet, and mobile
• Multi-Language: Translations for 30+ languages
• Bookmarks: Organize quick links alongside services

This guide walks through deploying Homepage on Klutch.sh using Docker, configuring services and widgets, and customizing your dashboard.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Homepage configuration
• API keys for services you want to display (optional)
• Basic familiarity with Docker and YAML configuration

Preparing Your Repository

Create a GitHub repository with the following structure:

homepage-deploy/
├── Dockerfile
├── config/
│   ├── services.yaml
│   ├── settings.yaml
│   ├── widgets.yaml
│   └── bookmarks.yaml
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile using the official Homepage image:

FROM ghcr.io/gethomepage/homepage:latest

# Environment variables
ENV HOMEPAGE_ALLOWED_HOSTS=${HOMEPAGE_ALLOWED_HOSTS}
ENV PUID=${PUID:-1000}
ENV PGID=${PGID:-1000}

# Copy configuration files
COPY config/ /app/config/

# Expose the application 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/ || exit 1

Basic Configuration Files

Create config/settings.yaml:

# Homepage Settings
title: My Dashboard

# Theme and layout
theme: dark
color: slate
headerStyle: boxed

# Optional: Show/hide elements
showStats: true
hideVersion: true

# Optional: Background
# background:
#   image: /images/background.jpg
#   blur: sm
#   opacity: 50

# Optional: Favicon
# favicon: /images/favicon.ico

# Optional: Card blur
# cardBlur: md

layout:
  - Media:
      style: row
      columns: 3
  - Infrastructure:
      style: row
      columns: 4
  - Bookmarks:
      style: row
      columns: 4

Create config/services.yaml:

# Services Configuration
- Media:
    - Plex:
        icon: plex.png
        href: https://plex.example.com
        description: Media Server
        widget:
          type: plex
          url: https://plex.example.com
          key: {{HOMEPAGE_VAR_PLEX_KEY}}

    - Sonarr:
        icon: sonarr.png
        href: https://sonarr.example.com
        description: TV Show Manager
        widget:
          type: sonarr
          url: https://sonarr.example.com
          key: {{HOMEPAGE_VAR_SONARR_KEY}}

- Infrastructure:
    - Portainer:
        icon: portainer.png
        href: https://portainer.example.com
        description: Container Management

    - Uptime Kuma:
        icon: uptime-kuma.png
        href: https://uptime.example.com
        description: Monitoring

Create config/widgets.yaml:

# Information Widgets
- resources:
    cpu: true
    memory: true
    disk: /

- datetime:
    text_size: xl
    format:
      dateStyle: long
      timeStyle: short
      hourCycle: h23

- openweathermap:
    label: Weather
    latitude: 40.7128
    longitude: -74.0060
    units: metric
    apiKey: {{HOMEPAGE_VAR_OPENWEATHERMAP_KEY}}

Create config/bookmarks.yaml:

# Bookmarks Configuration
- Development:
    - GitHub:
        - abbr: GH
          href: https://github.com

    - Stack Overflow:
        - abbr: SO
          href: https://stackoverflow.com

- Social:
    - Twitter:
        - abbr: TW
          href: https://twitter.com

    - Reddit:
        - abbr: RD
          href: https://reddit.com

Environment Variables Reference

Variable	Required	Description
HOMEPAGE_ALLOWED_HOSTS	Yes	Comma-separated list of allowed hostnames
PUID	No	User ID for file ownership (default: 1000)
PGID	No	Group ID for file ownership (default: 1000)
HOMEPAGE_VAR_*	No	Custom variables for configuration

Deploying Homepage on Klutch.sh

Push Your Repository to GitHub

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

Create a New App

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

Configure HTTP Traffic

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

Set Environment Variables

Configure the following environment variables:

Variable	Value
HOMEPAGE_ALLOWED_HOSTS	your-app-name.klutch.sh
PUID	1000
PGID	1000
HOMEPAGE_VAR_PLEX_KEY	Your Plex API key (if using)
HOMEPAGE_VAR_SONARR_KEY	Your Sonarr API key (if using)
HOMEPAGE_VAR_OPENWEATHERMAP_KEY	Your OpenWeatherMap API key

Attach Persistent Volumes (Optional)

Mount Path	Recommended Size	Purpose
/app/config	1 GB	Configuration files (if not in image)
/app/public/images	1 GB	Custom images and backgrounds

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container and start Homepage with HTTPS enabled.

Access Homepage

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

Configuring Services

Available Widgets

Homepage supports widgets for many services:

Media:

• Plex, Jellyfin, Emby
• Sonarr, Radarr, Lidarr
• Tautulli, Overseerr

Downloads:

• qBittorrent, Transmission
• SABnzbd, NZBget

Infrastructure:

• Portainer, Proxmox
• Uptime Kuma, Healthchecks
• AdGuard Home, Pi-hole

Information:

• Weather (OpenWeatherMap)
• Calendar (CalDAV)
• RSS feeds

Widget Configuration

Each widget has specific configuration options:

- ServiceName:
    icon: service.png
    href: https://service.example.com
    description: Service description
    widget:
      type: servicetype
      url: https://service.example.com
      key: your-api-key
      # Additional widget-specific options

Using Environment Variables

Protect sensitive values:

widget:
  type: sonarr
  url: https://sonarr.example.com
  key: {{HOMEPAGE_VAR_SONARR_KEY}}  # Set in Klutch.sh environment

Customization

Themes

Change theme in settings.yaml:

theme: dark  # or light
color: slate  # blue, cyan, emerald, gray, green, indigo, orange, pink, purple, red, rose, sky, stone, teal, violet, yellow, zinc

Layout Options

Configure service layout:

layout:
  - Media:
      style: row  # or column
      columns: 3
      icon: mdi-play-circle
  - Infrastructure:
      style: row
      columns: 4

Custom Icons

Use built-in icons or custom images:

icon: plex.png  # From dashboard-icons
icon: si-github  # Simple Icons
icon: mdi-server  # Material Design Icons
icon: /images/custom.png  # Custom image

Troubleshooting

Widgets Not Loading

• Verify service URLs are accessible
• Check API keys are correct
• Ensure HOMEPAGE_ALLOWED_HOSTS is set

Configuration Errors

• Validate YAML syntax
• Check for missing required fields
• Review container logs

CORS Issues

• Ensure services allow cross-origin requests
• Use proxy widgets where available

Additional Resources

• Official Homepage Website
• Homepage GitHub Repository
• Homepage Configuration Docs
• Widget Reference
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Homepage on Klutch.sh creates a beautiful, functional dashboard for accessing and monitoring your services. The extensive widget system provides real-time insights into your infrastructure, while the YAML-based configuration enables version-controlled, reproducible deployments. Whether you need a simple bookmark page or a comprehensive monitoring dashboard, Homepage delivers a fast, secure, and highly customizable solution.