impulsivefps
/
homarr-dashboard
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
homarr-dashboard/DEPLOYMENT.md

9.9 KiB
Raw Blame History

🚀 Homarr Deployment Guide

Complete deployment guide for Homarr with system monitoring, RSS feeds, and a sleek dark theme matching lemonlink.eu.

📋 Table of Contents

  1. Overview
  2. Prerequisites
  3. Quick Start
  4. Configuration
  5. Board Setup
  6. Public/Private Access
  7. Troubleshooting

Overview

This deployment includes:

Component Purpose
Homarr 1.0 Modern dashboard with drag-and-drop
Dash. Real-time system monitoring
Traefik Reverse proxy for public access
Watchtower Automatic container updates

Features

  • ✅ 5 Pre-configured Boards: Main, Infrastructure, Media, System, News
  • ✅ 60+ Apps: Pre-configured with icons and categories
  • ✅ System Monitoring: Full Dash. integration with CPU/RAM/Storage/Network
  • ✅ RSS Feeds: Homelab, Cybersecurity, and Technology news
  • ✅ Dark Theme: Matching lemonlink.eu aesthetic
  • ✅ Public/Private Boards: Granular access control
  • ✅ Docker Integration: Manage containers from dashboard

Prerequisites

System Requirements

  • OS: Linux (Ubuntu 20.04+, Debian 11+, etc.)
  • Docker: 20.10+ with Docker Compose v2
  • RAM: 2GB minimum, 4GB recommended
  • Storage: 5GB free space

Install Docker (if not installed)

# Ubuntu/Debian
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

# Verify installation
docker --version
docker compose version

Quick Start

1. Clone or Copy Files

cd ~
# Copy the homarr-deploy folder to your server
cp -r homarr-deploy /opt/
cd /opt/homarr-deploy

2. Configure Environment

# Copy example environment file
cp .env.example .env

# Edit configuration
nano .env

# Generate a new encryption key (PowerShell)
# -join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Maximum 256) })

3. Start Services

# Start all services
docker compose up -d

# Verify services are running
docker compose ps

# View logs
docker compose logs -f

4. Access Homarr

Configuration

Initial Setup

  1. First Run: Navigate to http://your-server-ip:7575
  2. Onboarding: Create admin account
  3. Boards: Create your first board

Creating Boards

Board 1: Main Dashboard (Public)

Navigate to: Manage → Boards → New Board

Name: Main Dashboard
Visibility: Public
Theme: LemonLink Dark (customize colors)

Add Widgets:

  1. Clock: Large format, show date
  2. Weather: Your location
  3. RSS Feed - Homelab:
    • URLs: https://selfh.st/rss/,https://noted.lol/rss/,https://feeds.fireside.fm/selfhosted/rss
    • Posts limit: 10
  4. RSS Feed - Cyber:
    • URLs: https://www.bleepingcomputer.com/feed/,https://feeds.feedburner.com/TheHackersNews,https://krebsonsecurity.com/feed/
    • Posts limit: 10
  5. RSS Feed - Tech:
    • URLs: https://news.ycombinator.com/rss,https://techcrunch.com/feed/,https://feeds.arstechnica.com/arstechnica/index
    • Posts limit: 10

Add Apps:

  • Gmail, GitHub, Reddit, YouTube, Discord
  • Proxmox, Portainer, Plex, Nextcloud, Vaultwarden

Board 2: Infrastructure (Private)

Navigate to: Manage → Boards → New Board

Name: Infrastructure
Visibility: Private

Add Widgets:

  1. iFrame: Embed Dash. (http://your-server-ip:3001)
  2. System Health Monitor: Connect to Proxmox
  3. DNS Hole: Connect to Pi-hole/AdGuard

Add Apps:

  • All infrastructure apps (see apps.json)

Board 3: Media Center (Private)

Name: Media Center
Visibility: Private

Add Widgets:

  1. Media Server: Connect to Plex/Jellyfin
  2. Torrent: Connect to qBittorrent/Transmission
  3. Media Requests: Connect to Overseerr/Jellyseerr

Board 4: System Overview (Private)

Name: System Overview
Visibility: Private
Layout: Full-width iFrame

Add Widget:

  1. iFrame: Dash. at http://your-server-ip:3001 (full screen)

Board 5: News Hub (Public)

Name: News Hub
Visibility: Public

Add Widgets:

  1. RSS Feed - Homelab (full width)
  2. RSS Feed - Cybersecurity (full width)
  3. RSS Feed - Technology (full width)

Public/Private Access

Access Control

Board Visibility Access
Main Dashboard Public Anyone
News Hub Public Anyone
Infrastructure Private Logged-in users only
Media Center Private Logged-in users only
System Overview Private Logged-in users only

Setting Up External Access (with NPM)

Since you're using Nginx Proxy Manager (NPM), the setup is straightforward:

Step 1: Ensure NPM Network Exists

# Check if network exists
docker network ls | grep npm-network

# Create if missing
docker network create npm-network

The docker-compose.yml is already configured to connect to the npm-network.

Option 1: Cloudflare Tunnel (Recommended)

# Install cloudflared
docker run --rm -v /opt/homarr-deploy/cloudflared:/home/nonroot/.cloudflared cloudflare/cloudflared:latest tunnel login

# Create tunnel
docker run --rm -v /opt/homarr-deploy/cloudflared:/home/nonroot/.cloudflared cloudflare/cloudflared:latest tunnel create homarr

# Configure tunnel
cat > /opt/homarr-deploy/cloudflared/config.yml << 'EOF'
tunnel: YOUR_TUNNEL_ID
credentials-file: /home/nonroot/.cloudflared/YOUR_TUNNEL_ID.json

ingress:
  - hostname: dashboard.lemonlink.eu
    service: http://homarr:7575
  - hostname: system.lemonlink.eu
    service: http://dash:3001
  - service: http_status:404
EOF

# Run tunnel
docker run -d --name cloudflared \
  -v /opt/homarr-deploy/cloudflared:/home/nonroot/.cloudflared \
  cloudflare/cloudflared:latest tunnel run

Option 2: Nginx Proxy Manager

Add to your existing NPM:

  • Domain: dashboard.lemonlink.eu
  • Forward Hostname/IP: homarr
  • Forward Port: 7575
  • Scheme: http

Option 3: Using Gitea + Webhook (Advanced)

See GITEA_SETUP.md for automated deployment via Gitea webhooks.

Dash. Configuration

Environment Variables

The Dash. container is pre-configured with:

environment:
  - DASHDOT_ENABLE_CPU_TEMPS=true
  - DASHDOT_ALWAYS_SHOW_PERCENTAGES=true
  - DASHDOT_ENABLE_STORAGE_SPLIT_VIEW=true
  - DASHDOT_SPEED_TEST_INTERVAL=240
  - DASHDOT_WIDGET_LIST=os,cpu,storage,ram,network

Access Dash.

Customization

Modify docker-compose.yml to change:

  • Widget order
  • Display options
  • Speed test interval

RSS Feed Configuration

Pre-configured Feeds

See config/rss-feeds.json for complete list.

Adding to Homarr

  1. Edit board → Add Widget → RSS Feed
  2. Enter feed URLs (comma-separated)
  3. Configure display options:
    • Posts limit: 10-20
    • Description line clamp: 2-5
    • Hide description: No

Feed Categories

Category Feeds
Homelab Selfh.st, Noted, Self-Hosted Podcast, r/SelfHosted
Cybersecurity Bleeping Computer, The Hacker News, Krebs on Security
Technology Hacker News, TechCrunch, Ars Technica, Wired
Linux Phoronix, LWN, OMG! Ubuntu, Arch News
Docker Docker Blog, LinuxServer.io

Theming

Dark Theme (lemonlink.eu Style)

Navigate to: Board Settings → Appearance

Primary Color: #6366f1 (Indigo)
Secondary Color: #8b5cf6 (Purple)
Background: #0a0a0f (Near black)
Text Color: #e2e8f0 (Light gray)
Accent Color: #fbbf24 (Amber)

Custom CSS

Add to Board Settings → Custom CSS:

/* Glassmorphism effect */
.homarr-card {
  background: rgba(255, 255, 255, 0.05) !important;
  backdrop-filter: blur(10px) !important;
  border: 1px solid rgba(255, 255, 255, 0.1) !important;
  border-radius: 16px !important;
}

/* Hover animation */
.homarr-card:hover {
  transform: translateY(-4px) !important;
  box-shadow: 0 20px 40px rgba(0, 0, 0, 0.3) !important;
}

Maintenance

Backup

# Backup Homarr data
tar -czf homarr-backup-$(date +%Y%m%d).tar.gz homarr/

# Backup configurations
tar -czf config-backup-$(date +%Y%m%d).tar.gz config/

Updates

Watchtower is configured to auto-update daily.

Manual update:

docker compose pull
docker compose up -d

Logs

# Homarr logs
docker compose logs -f homarr

# Dash. logs
docker compose logs -f dash

# All logs
docker compose logs -f

Troubleshooting

Issue: Homarr won't start

# Check logs
docker compose logs homarr

# Verify permissions
ls -la homarr/appdata/

# Reset permissions
sudo chown -R $USER:$USER homarr/

Issue: Dash. shows no data

# Ensure privileged mode is enabled
docker compose stop dash
docker compose rm dash
docker compose up -d dash

# Check Dash. logs
docker compose logs dash

Issue: RSS feeds not loading

  • Check URL is valid and accessible
  • Ensure feed is RSS/ATOM/JSON format
  • Try accessing feed URL directly in browser

Issue: Cannot access from internet

  • Check firewall rules (ports 80, 443, 7575, 3001)
  • Verify DNS records point to server
  • Check reverse proxy configuration

Security Recommendations

  1. Use HTTPS: Enable SSL/TLS with Let's Encrypt
  2. Strong Passwords: Use password manager for admin account
  3. Firewall: Restrict port access
  4. VPN: Consider VPN for private boards
  5. Updates: Keep containers updated
  6. Backups: Regular data backups

Resources

Support

For issues or questions: