homarr-dashboard/DEPLOYMENT.md

🚀 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

• Homarr Dashboard: http://your-server-ip:7575
• Dash. System Monitor: http://your-server-ip:3001
• Traefik Dashboard: http://your-server-ip:8080

---

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.

• Direct: http://your-server-ip:3001
• Embedded: Add as iFrame widget in Homarr

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

• Homarr Documentation
• Dash. Documentation
• Docker Compose Reference

---

Support

For issues or questions:

• Homarr Discord: https://discord.gg/homarr
• GitHub Issues: https://github.com/homarr-labs/homarr/issues