Deploying Homarr

Introduction

Homarr is a highly customizable browser homepage that serves as a dashboard for your homeserver. Unlike simple bookmark managers, Homarr integrates directly with your Docker containers and services to display real-time status, statistics, and controls. The modern interface combines beautiful design with powerful functionality.

Built with Next.js and designed for homelabs, Homarr features drag-and-drop customization, service integrations for popular applications like Sonarr, Radarr, and Plex, and the ability to control Docker containers directly from your browser. The dashboard supports multiple users, authentication providers, and extensive theming options.

Key highlights of Homarr:

Docker Integration: View and manage containers directly from the dashboard
Service Widgets: Live statistics from Sonarr, Radarr, Plex, and 50+ services
Drag-and-Drop Editor: Customize layout with intuitive editing
Multi-User Support: Individual dashboards for each user
Authentication: SSO, LDAP, and built-in authentication options
Calendar Integration: Track media releases and events
Weather and News: Information widgets for daily updates
Responsive Design: Works on desktop, tablet, and mobile

This guide walks through deploying Homarr on Klutch.sh using Docker, configuring service integrations, and customizing your dashboard.

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your Homarr configuration
Basic familiarity with Docker and containerization concepts
(Optional) API keys for services you want to integrate

Preparing Your Repository

Create a GitHub repository with the following structure:

homarr-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile using the official Homarr image:

FROM ghcr.io/homarr-labs/homarr:latest

# Environment variables
ENV SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY}
ENV PUID=${PUID:-1000}
ENV PGID=${PGID:-1000}
ENV TZ=${TZ:-Etc/UTC}

# Expose the application port
EXPOSE 7575

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

Advanced Dockerfile with Database

For production with external database:

FROM ghcr.io/homarr-labs/homarr:latest

ENV SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY}
ENV PUID=${PUID:-1000}
ENV PGID=${PGID:-1000}
ENV TZ=${TZ:-Etc/UTC}

# Database configuration (optional)
ENV DB_URL=${DB_URL}
ENV DB_HOST=${DB_HOST}
ENV DB_PORT=${DB_PORT:-5432}
ENV DB_NAME=${DB_NAME:-homarr}
ENV DB_USER=${DB_USER}
ENV DB_PASSWORD=${DB_PASSWORD}

EXPOSE 7575

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

Environment Variables Reference

Variable	Required	Default	Description
`SECRET_ENCRYPTION_KEY`	Yes	-	Encryption key (auto-generated if not set)
`PUID`	No	1000	User ID for file ownership
`PGID`	No	1000	Group ID for file ownership
`TZ`	No	Etc/UTC	Container timezone
`DB_URL`	No	-	Database connection URL
`DB_HOST`	No	-	Database hostname
`DB_PORT`	No	5432	Database port
`DB_NAME`	No	homarr	Database name
`DB_USER`	No	-	Database username
`DB_PASSWORD`	No	-	Database password

Deploying Homarr on Klutch.sh

Generate Encryption Key

Generate a secure encryption key:

openssl rand -hex 32

Save this key for configuration.

Push Your Repository to GitHub

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

Create a New App

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

Configure HTTP Traffic

Select HTTP as the traffic type
Set the internal port to 7575

Set Environment Variables

Configure the following environment variables:

Variable	Value
`SECRET_ENCRYPTION_KEY`	Your generated encryption key
`PUID`	`1000`
`PGID`	`1000`
`TZ`	Your timezone (e.g., `America/New_York`)

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
`/appdata`	5 GB	Configuration, database, and icons

Deploy Your Application

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

Access Homarr

Once deployment completes, access your dashboard at https://your-app-name.klutch.sh. Create your admin account on first access.

Configuring Homarr

Initial Setup

Access your Homarr instance
Create your admin account
Start customizing your dashboard

Adding Applications

Enter edit mode (pencil icon)
Click Add Tile
Select Application
Configure:
- App name and URL
- Icon (auto-detected or custom)
- Category/section
Save changes

Adding Widgets

Homarr supports various widget types:

Media:

Sonarr, Radarr, Lidarr
Plex, Jellyfin, Emby
qBittorrent, Deluge

System:

Docker containers
System resources
Network status

Information:

Weather
Calendar
RSS feeds
Notes

Configuring Integrations

Click on a service tile
Select Configure
Enter API credentials:
- API URL
- API Key
- Username/Password (if required)
Test connection
Save configuration

Docker Integration

Note: Docker socket integration requires access to the Docker daemon. For Klutch.sh deployments, use API-based integrations instead of socket connections.

Organizing Your Dashboard

Sections:

Group related apps into sections
Rename sections for clarity
Collapse sections to save space

Layout:

Drag tiles to rearrange
Resize tiles for emphasis
Use multiple columns

User Management

Navigate to Settings > Users
Add new users
Configure permissions:
- View only
- Edit dashboard
- Admin access

Customization

Themes

Go to Settings > Appearance
Choose color scheme
Customize:
- Primary color
- Background
- Card opacity
- Border radius

Custom CSS

Add custom styling:

/* Example: Glassmorphism effect */
.tile {
  backdrop-filter: blur(10px);
  background: rgba(255, 255, 255, 0.1);
}

Background Images

Go to Settings > Appearance
Upload or link background image
Adjust blur and opacity

Troubleshooting

Widgets Not Updating

Verify API credentials are correct
Check service is accessible from Homarr
Review integration logs

Configuration Not Saving

Ensure persistent volume is mounted
Check file permissions
Verify encryption key is consistent

Performance Issues

Reduce number of widgets
Increase refresh intervals
Check resource allocation

Additional Resources

Conclusion

Deploying Homarr on Klutch.sh creates a powerful, customizable dashboard for managing your homeserver and applications. The service integrations provide real-time monitoring and control, while the beautiful interface makes daily use a pleasure. With persistent storage for your configuration and support for multiple users, Homarr becomes the central hub for your self-hosted services.