diff --git a/SETUP_WALKTHROUGH.md b/SETUP_WALKTHROUGH.md new file mode 100644 index 0000000..c229198 --- /dev/null +++ b/SETUP_WALKTHROUGH.md @@ -0,0 +1,344 @@ +# 🚀 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!