# 🚀 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](#overview)
2. [Prerequisites](#prerequisites)
3. [Quick Start](#quick-start)
4. [Configuration](#configuration)
5. [Board Setup](#board-setup)
6. [Public/Private Access](#publicprivate-access)
7. [Troubleshooting](#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)

```bash
# 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

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

### 2. Configure Environment

```bash
# 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

```bash
# 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

```bash
# 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)

```bash
# 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](GITEA_SETUP.md) for automated deployment via Gitea webhooks.

---

## Dash. Configuration

### Environment Variables

The Dash. container is pre-configured with:

```yaml
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:

```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

```bash
# 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:
```bash
docker compose pull
docker compose up -d
```

### Logs

```bash
# 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

```bash
# 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

```bash
# 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](https://homarr.dev/docs/)
- [Dash. Documentation](https://getdashdot.com/)
- [Docker Compose Reference](https://docs.docker.com/compose/)

---

## Support

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