464 lines
9.9 KiB
Markdown
464 lines
9.9 KiB
Markdown
# 🚀 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
|