homarr-dashboard/SETUP_WALKTHROUGH.md

🚀 Homarr Setup Walkthrough (Logged In)

You're logged in! Let's create your boards step by step.

---

Step 1: Create Your First Board

1.1 Go to Board Management

1. Click your profile icon (top right)
2. Select "Manage"
3. Click "Boards" in left sidebar
4. Click "New Board" button

1.2 Create "Main Dashboard" Board

Name: Main Dashboard
Description: Public dashboard with news and quick links
Visibility: Public

Click Create

---

Step 2: Add Apps (Before Adding to Board)

2.1 Go to App Management

1. While in Manage section
2. Click "Apps" in left sidebar
3. Click "New App" button

2.2 Add Common Apps

Add Gmail:

Name: Gmail
Description: Email
Icon URL: gmail (just type "gmail", it will find it)
URL: https://mail.google.com

Add GitHub:

Name: GitHub
Description: Code Repository
Icon URL: github
URL: https://github.com

Add Proxmox (if you have it):

Name: Proxmox
Description: Virtualization
Icon URL: proxmox
URL: https://proxmox.lemonlink.eu (or your IP)

Add 10-15 more apps you use regularly...

Click Create for each app.

---

Step 3: Add Widgets to Your Board

3.1 Open Your Board for Editing

1. Go back to "Boards" in Manage
2. Click on "Main Dashboard"
3. Click "Open Board"
4. Click the "Pencil Icon" (Edit Mode)

3.2 Add Clock Widget

1. Click "Add Item" button
2. Select "Clock"
3. It appears on board
4. Click the 3 dots (⋮) on the widget → "Edit Item"
5. Settings:
   - Show date: ✅
   - Time format: 24h (or your preference)
   - Size: Make it 2x2 (drag bottom-right corner)
6. Click Save

3.3 Add Weather Widget

1. Click "Add Item"
2. Select "Weather"
3. Edit item (3 dots → Edit)
4. Enter your location (City, Country)
5. Set temperature unit
6. Save

3.4 Add RSS Feed Widget (Homelab News)

1. Click "Add Item"
2. Select "RSS Feed"
3. Edit item
4. Settings:
   
   Name: Homelab News
   
   Feed URLs (one per line):
   https://selfh.st/rss/
   https://noted.lol/rss/
   https://feeds.fireside.fm/selfhosted/rss
   
   Posts limit: 10
   Description line clamp: 3
   Hide description: No
   
5. Save
6. Resize to make it wider (3x2 or 4x2)

3.5 Add More RSS Widgets

Cybersecurity News:

Feed URLs:
https://www.bleepingcomputer.com/feed/
https://feeds.feedburner.com/TheHackersNews
https://krebsonsecurity.com/feed/

Tech News:

Feed URLs:
https://news.ycombinator.com/rss
https://techcrunch.com/feed/
https://feeds.arstechnica.com/arstechnica/index

3.6 Add Apps to Board

1. Click "Add Item"
2. Select "App"
3. Edit item (3 dots → Edit)
4. Select the app from dropdown (Gmail, GitHub, etc.)
5. Save
6. Repeat for each app

3.7 Arrange Everything

- Drag widgets/apps to position them
- Resize by dragging bottom-right corner
- Align items nicely in rows
- Exit edit mode (click "Exit" or checkmark) to save

---

Step 4: Create System Monitor Board (Private)

4.1 Create New Board

Manage → Boards → New Board

Name: System Overview
Description: Server monitoring
Visibility: Private (requires login)

4.2 Add Dash. Widget

1. Open board → Edit Mode
2. Add Item → iFrame
3. Edit settings:
   
   Name: System Monitor
   URL: http://YOUR-SERVER-IP:3001
   
4. Make it FULL WIDTH (6x4 or largest size)
5. Save and exit edit mode

---

Step 5: Create Infrastructure Board (Private)

5.1 Create Board

Name: Infrastructure
Visibility: Private

5.2 Add Docker Integration

1. Go to Manage → Integrations
2. Click "New Integration"
3. Select "Docker"
4. Name: Local Docker
5. Socket: /var/run/docker.sock
6. Test connection
7. Save

5.3 Add Apps to Board

Add apps you created earlier:
- Proxmox
- Portainer
- TrueNAS
- Pi-hole
- Grafana
- etc.

---

Step 6: Theme Customization

6.1 Open Board Settings

1. Open a board
2. Click "Settings" (gear icon) in top bar
3. Click "Appearance" tab

6.2 Dark Theme Colors

Primary Color: #6366f1 (Indigo)
Secondary Color: #8b5cf6 (Purple)
Background Color: #0a0a0f (Very dark)
Text Color: #e2e8f0 (Light gray)
Accent Color: #fbbf24 (Amber/Gold)

6.3 Custom CSS (Optional)

In Appearance settings, find "Custom CSS" box:

.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;
}

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

---

Step 7: Quick Tips

Keyboard Shortcuts

Ctrl + K (or /)  → Open search
Esc              → Close search

Search Usage

1. Press Ctrl+K
2. Type "proxm" → Finds Proxmox
3. Press Enter → Opens it

Edit Mode Tips

- Drag to move items
- Drag corner to resize
- 3 dots menu → Edit, Delete, Move
- Items snap to grid automatically

---

Example Layouts

Main Dashboard Layout

┌─────────────────────────────────────────┐
│  [CLOCK]    [WEATHER]    [SEARCH]      │
├─────────────────────────────────────────┤
│  [RSS - Homelab]  [RSS - Cyber]        │
│  (2 columns)                           │
├─────────────────────────────────────────┤
│  [Gmail] [GitHub] [Reddit] [YouTube]   │
│  [Proxmox] [Portainer] [Plex]          │
└─────────────────────────────────────────┘

System Overview Layout

┌─────────────────────────────────────────┐
│                                         │
│         [DASH. IFRAME]                  │
│         (Full Screen)                   │
│                                         │
└─────────────────────────────────────────┘

---

✅ Check Your Progress

• Created Main Dashboard (Public)
• Created System Overview (Private)
• Added 5-10 Apps
• Added Clock + Weather
• Added 3 RSS feeds
• Arranged items nicely
• Set dark theme colors
• Tested search (Ctrl+K)

---

🆘 Common Issues

Can't find apps in dropdown?

You need to CREATE apps first in Manage → Apps
THEN add them to boards

Widgets not loading?

- Check if URLs are correct
- For RSS: Verify feed URLs work in browser
- For Dash: Check if http://IP:3001 is accessible

Changes not saving?

Make sure to EXIT EDIT MODE (click checkmark or "Exit")

---

Need more help? Check the other guides in your repo or ask!