Update documentation for admin services implementation

- Document complete admin services setup in admin-services-setup.md - Update services.md with Netdata replacing Cockpit configuration - Include troubleshooting steps and security implementation details - Document tabbed landing page architecture and service organization - Add privacy-focused Netdata configuration details
2025-09-09 21:14:28 +02:00
parent 2fa9ec3a20
commit 914e8a0ba7
2 changed files with 390 additions and 6 deletions
--- a/docs/admin-services-setup.md
+++ b/docs/admin-services-setup.md
@@ -0,0 +1,200 @@
+# Admin Services Setup Documentation
+
+**Date:** 2025-09-09  
+**Status:** ✅ Complete - Landing page with tabbed interface and monitoring services deployed
+
+## Overview
+
+This document details the setup of administrative services accessible through the homelab landing page. The implementation provides a tabbed interface with monitoring and management tools for the homelab infrastructure.
+
+## Landing Page Architecture
+
+### Tab Structure
+- **Home Tab**: Main services (Gitea, File Server, Media Server)
+- **Admin Tab**: Administrative services organized in two sections:
+  - **Server Administration**: Remote-accessible monitoring/management
+  - **Local Network**: Local-only network devices
+
+### Implementation Details
+
+**File Location:** `/home/hoborg/homelab/config/www/index.html`  
+**Deployment:** `sudo cp config/www/index.html /var/www/homelab/`
+
+**Features:**
+- Responsive CSS Grid layout
+- Font Awesome icons for visual consistency
+- JavaScript tab switching functionality
+- Professional gradient styling with hover effects
+- Separate styling for different service types (admin, disabled, cloud)
+
+## Admin Services Configuration
+
+### Server Administration Services
+
+#### 1. Glances (System Monitoring)
+- **Status:** ✅ Deployed
+- **Access:** https://ak-homelab.duckdns.org/glances/
+- **Port:** 61208 (behind nginx reverse proxy)
+- **Authentication:** Nginx basic auth (admin / AdminPass2024!)
+- **Features:** Real-time CPU/RAM/disk metrics, process monitoring
+
+**Configuration Files:**
+- Service: `/home/hoborg/homelab/config/systemd/glances-web.service`
+- Nginx: Reverse proxy with basic auth in `homelab.conf`
+
+#### 2. Netdata (Real-time Monitoring) 
+- **Status:** ✅ Deployed (replaced Cockpit)
+- **Access:** https://ak-homelab.duckdns.org/netdata/
+- **Port:** 19999 (behind nginx reverse proxy)
+- **Authentication:** Nginx basic auth (admin / AdminPass2024!)
+- **Privacy:** Cloud features disabled, local-only operation
+
+**Configuration Files:**
+- Main config: `/home/hoborg/homelab/config/netdata/netdata.conf`
+- Deployment script: `/home/hoborg/homelab/scripts/deploy-netdata-config.sh`
+
+**Privacy Configuration:**
+```ini
+[global]
+    bind socket to IP = 127.0.0.1
+    telemetry enabled = no
+
+[cloud]
+    enabled = no
+    
+[registry]
+    enabled = no
+```
+
+#### 3. Portainer (Docker Management)
+- **Status:** 📋 Planned
+- **Access:** https://ak-homelab.duckdns.org/portainer/
+- **Port:** 9000 (behind nginx reverse proxy)
+- **Authentication:** Built-in user management
+
+### Local Network Services
+
+#### 1. NAS Storage
+- **Access:** http://192.168.0.101:5000/
+- **Description:** Network Attached Storage management interface
+- **Icon:** `fas fa-hdd`
+- **Authentication:** Built-in device authentication
+
+#### 2. Router Configuration
+- **Access:** http://192.168.0.1
+- **Description:** Network router administration
+- **Icon:** `fas fa-network-wired`
+- **Authentication:** Router's built-in authentication
+
+## Security Implementation
+
+### Nginx Basic Authentication
+
+**Auth File:** `/etc/nginx/auth/glances`  
+**Credentials:** admin / AdminPass2024!
+
+**Services using basic auth:**
+- Glances (system metrics exposure)
+- Netdata (system metrics exposure)
+
+**Creation Command:**
+```bash
+sudo htpasswd -c /etc/nginx/auth/glances admin
+```
+
+### Service-Level Security
+
+- **Netdata:** Configured for localhost-only access, cloud features disabled
+- **Glances:** Web server bound to localhost, accessible only through reverse proxy
+- **Portainer:** Uses built-in authentication with RBAC
+- **Local Network:** Services remain on local network only (no external exposure)
+
+## Deployment Scripts
+
+### 1. Netdata Setup Script
+**File:** `/home/hoborg/homelab/scripts/setup-netdata.sh`
+- Installs netdata package
+- Enables and starts service
+- Stops/disables Cockpit services
+- Deploys updated landing page
+
+### 2. Netdata Configuration Deployment
+**File:** `/home/hoborg/homelab/scripts/deploy-netdata-config.sh` 
+- Deploys privacy-focused Netdata configuration
+- Updates nginx configuration with Netdata reverse proxy
+- Tests configuration and performs rollback on failure
+- Includes connectivity testing
+
+## Troubleshooting Steps Completed
+
+### 1. Cockpit Compatibility Issues
+**Problem:** Cockpit had infinite loading issues due to MIME type conflicts with reverse proxy
+**Solution:** Replaced Cockpit with Netdata for better reverse proxy compatibility
+
+**Error Details:**
+- Content-Security-Policy errors
+- MIME type mismatches for static assets
+- Path rewriting complications with static file serving
+
+### 2. Configuration Management Approach
+**Problem:** Initial scripts modified configuration files directly
+**Solution:** Implemented proper workflow - edit repo files first, then deploy via scripts
+
+**Workflow:**
+1. Edit configuration in `/home/hoborg/homelab/config/`
+2. Test changes locally when possible
+3. Deploy via simple copy scripts with backup/rollback capabilities
+4. Update documentation
+
+## Current Status
+
+### ✅ Completed
+- Landing page with tabbed interface
+- Glances system monitoring with basic auth
+- Netdata real-time monitoring with privacy configuration
+- Nginx reverse proxy configuration for all services
+- Updated documentation and deployment scripts
+- NAS Storage link added to Local Network section
+
+### 📋 Pending
+- Portainer Docker management deployment
+- Final nginx configuration deployment (for Netdata access)
+- lazydocker terminal tool installation
+
+## Access Summary
+
+### External Access (HTTPS with SSL)
+- **Glances:** https://ak-homelab.duckdns.org/glances/ (basic auth required)
+- **Netdata:** https://ak-homelab.duckdns.org/netdata/ (basic auth required)  
+- **Portainer:** https://ak-homelab.duckdns.org/portainer/ (planned, built-in auth)
+
+### Local Network Access
+- **NAS Storage:** http://192.168.0.101:5000/ (device auth)
+- **Router:** http://192.168.0.1 (router auth)
+
+### Direct Service Access (for testing)
+- **Netdata Direct:** http://127.0.0.1:19999/ (localhost only after config deployment)
+- **Glances Direct:** http://127.0.0.1:61208/ (localhost only)
+
+## Files Modified/Created
+
+### Configuration Files
+- `/home/hoborg/homelab/config/www/index.html` - Updated with admin sections
+- `/home/hoborg/homelab/config/nginx/homelab.conf` - Added Netdata reverse proxy
+- `/home/hoborg/homelab/config/netdata/netdata.conf` - Privacy-focused configuration
+- `/home/hoborg/homelab/config/systemd/glances-web.service` - Glances systemd service
+
+### Scripts Created
+- `/home/hoborg/homelab/scripts/setup-netdata.sh` - Netdata installation script
+- `/home/hoborg/homelab/scripts/deploy-netdata-config.sh` - Configuration deployment script
+
+### Documentation Updated
+- `/home/hoborg/homelab/docs/services.md` - Updated monitoring services section
+- `/home/hoborg/homelab/docs/admin-services-setup.md` - This comprehensive setup document
+
+## Next Steps
+
+1. Deploy Netdata configuration: `sudo -A ./scripts/deploy-netdata-config.sh`
+2. Install and configure Portainer for Docker management
+3. Install lazydocker for SSH-based Docker administration
+4. Consider additional monitoring tools (htop, iotop alternatives) for terminal use
--- a/docs/services.md
+++ b/docs/services.md
@@ -4,12 +4,12 @@ Planning and configuration for self-hosted services and applications.

 ## Nginx Reverse Proxy

-**Status**: ✅ Active  
-**Port**: 80 (HTTP), 443 (HTTPS)  
+**Status**: ✅ Active
+**Port**: 80 (HTTP), 443 (HTTPS)
 **Configuration**: `/etc/nginx/sites-available/homelab`

 ### Features
- Path-based routing to services (`/gitea/`, `/files/`, `/media/`)  
+- Path-based routing to services (`/gitea/`, `/files/`, `/media/`)
 - SSL termination with Let's Encrypt certificates
 - Security headers (XSS protection, content type sniffing prevention)
 - WebDAV support for Copyparty file server
@@ -160,7 +160,7 @@ docker-compose up -d

 **Port Assignments:**
 - **System SSH**: 2222 (for server administration)
- **Gitea SSH**: 2223 (for Git operations) 
+- **Gitea SSH**: 2223 (for Git operations)
 - **Gitea Web**: 3000 (web interface)

 **Database**: SQLite (default, stored in container volume)
@@ -532,7 +532,7 @@ sudo usermod -aG docker hoborg
 - No auto-discovery of services
 - Requires config reload for changes

-#### Traefik  
+#### Traefik
 ✅ **Pros:**
 - Docker-native auto-discovery via labels
 - Automatic HTTPS with Let's Encrypt
@@ -670,7 +670,7 @@ server {

 ### Router Port Forwarding Requirements
 - **HTTP**: Port 80 → 192.168.0.100:80
- **HTTPS**: Port 443 → 192.168.0.100:443  
+- **HTTPS**: Port 443 → 192.168.0.100:443
 - **Remove**: Direct port 3000 forwarding (will go through nginx)

 ### SSL Certificates
@@ -749,3 +749,187 @@ sudo -u postgres pg_dump gitea > /backup/gitea-db-$DATE.sql
 - **Bookstack**: Documentation wiki
  - What is this for? How does it compare to Logseq?
 - **FreshRSS**: RSS feed aggregator
+
+## System Monitoring & Management
+
+### Overview
+
+**Status:** 🚧 **PLANNED** - Implementing hybrid monitoring and management solution
+
+**Selected Tools:**
+- **Portainer** - Docker container management (web UI with built-in auth)
+- **Glances** - Real-time system monitoring (web + terminal, nginx basic auth required)
+- **Netdata** - Real-time system monitoring with rich dashboards (web UI, nginx basic auth)
+- **lazydocker** - Terminal-based Docker management (SSH sessions)
+
+### Architecture Decision
+
+**Hybrid Approach Rationale:**
+- **SSH workflow**: lazydocker + glances terminal mode for command-line administration
+- **Web overview**: Glances for quick system status checks
+- **Real-time monitoring**: Netdata for detailed system metrics and historical data
+- **Docker UI**: Portainer for comprehensive container management
+
+### Authentication Strategy
+
+- **Portainer**: ✅ Built-in user authentication and RBAC
+- **Glances**: ⚠️ Nginx basic auth required (exposes system metrics)
+- **Netdata**: ⚠️ Nginx basic auth required (exposes system metrics, cloud features disabled)
+- **Router**: ✅ Has own administrative login
+- **NAS Storage**: ✅ Has own administrative login
+
+**Nginx basic auth implemented** for monitoring services that expose system information without built-in authentication.
+
+### Service Details
+
+#### Portainer (Docker Management)
+**Status:** 📋 **Planned**
+- **Access**: https://ak-homelab.duckdns.org/portainer/
+- **Port**: 9000 (behind reverse proxy)
+- **Authentication**: Built-in user accounts with role-based permissions
+- **Features**: Container lifecycle, image management, volume management, stack deployment
+
+#### Glances (System Monitoring)
+**Status:** 📋 **Planned**
+- **Access**: https://ak-homelab.duckdns.org/glances/ (nginx basic auth)
+- **Port**: 61208 (behind reverse proxy with auth)
+- **Authentication**: Nginx basic auth (due to no built-in authentication)
+- **Features**: Real-time CPU/RAM/disk metrics, process monitoring, network stats
+- **Terminal mode**: Available via SSH for command-line monitoring
+
+#### Netdata (Real-time System Monitoring)
+**Status:** ✅ **DEPLOYED**
+- **Access**: https://ak-homelab.duckdns.org/netdata/ (nginx basic auth)
+- **Port**: 19999 (behind reverse proxy with auth)
+- **Authentication**: Nginx basic auth (same credentials as Glances: admin/AdminPass2024!)
+- **Configuration**: Privacy-focused local-only setup with cloud features disabled
+- **Features**: Real-time system metrics, network monitoring, process tracking, historical data
+
+#### lazydocker (Terminal Docker Tools)
+**Status:** 📋 **Planned**
+- **Access**: SSH terminal only
+- **Installation**: `pacman -S lazydocker`
+- **Usage**: Command-line Docker container management for SSH workflows
+
+### URL Architecture
+
+```
+Landing Page - Admin Tab:
+Server Administration:
+├── Glances → https://ak-homelab.duckdns.org/glances/ (nginx basic auth)
+├── Netdata → https://ak-homelab.duckdns.org/netdata/ (nginx basic auth)
+└── Portainer → https://ak-homelab.duckdns.org/portainer/ (built-in auth)
+
+Local Network:
+├── NAS Storage → http://192.168.0.101:5000/ (built-in auth)
+└── Router → http://192.168.0.1 (built-in auth)
+```
+
+### Implementation Plan
+
+1. **Package Installation**
+   ```bash
+   sudo pacman -S glances cockpit lazydocker
+   ```
+
+2. **Portainer Deployment**
+   ```bash
+   docker run -d \
+     --name portainer \
+     -p 9000:9000 \
+     -v /var/run/docker.sock:/var/run/docker.sock \
+     -v portainer_data:/data \
+     portainer/portainer-ce
+   ```
+
+3. **Service Configuration**
+   - Enable Cockpit: `sudo systemctl enable --now cockpit.socket`
+   - Configure Glances web mode: `glances -w -p 61208`
+   - Create systemd service for Glances web server
+
+4. **Nginx Configuration**
+   - Add reverse proxy configurations for all services
+   - Configure basic auth for Glances endpoint
+   - SSL termination for all admin services
+
+5. **Landing Page Update**
+   - Add all admin service links to Admin tab
+   - Include authentication indicators
+
+### Security Considerations
+
+**Data Exposure Analysis (Glances):**
+- **Exposed**: System metrics, process names, resource usage, network stats
+- **Not Exposed**: File contents, passwords, configuration details, logs
+- **Risk Level**: Medium (reconnaissance data for attackers)
+- **Mitigation**: Nginx basic auth prevents unauthorized access
+
+**Service Hardening:**
+- All services behind HTTPS with SSL certificates
+- Each service handles authentication independently
+- No shared credentials between services
+- Services isolated behind reverse proxy
+
+## Remote Desktop Access
+
+### TigerVNC
+
+**Status:** ✅ **INSTALLED** - VNC server for remote desktop access
+
+**Installation:**
+```bash
+# Install TigerVNC server and client
+sudo pacman -S tigervnc
+```
+
+**Service Configuration:**
+```bash
+# Configure user for VNC display :1
+echo ":1=hoborg" | sudo tee -a /etc/tigervnc/vncserver.users
+
+# Set VNC password
+vncpasswd
+
+# Configure desktop environment (~/.vnc/xstartup)
+#!/bin/bash
+xrdb $HOME/.Xresources
+startxfce4 &
+
+# Make executable
+chmod +x ~/.vnc/xstartup
+```
+
+**Service Management:**
+```bash
+# Enable and start VNC service
+sudo systemctl enable vncserver@:1.service
+sudo systemctl start vncserver@:1.service
+
+# Check service status
+sudo systemctl status vncserver@:1.service
+
+# Service uses vncsession-start for proper X11 session management
+```
+
+**Access Details:**
+- **Display**: `:1` (port 5901)
+- **Local Access**: VNC client to `192.168.0.100:5901`
+- **External Access**: Requires router port forwarding 5901→192.168.0.100:5901
+- **Security**: Password authentication, consider SSH tunneling for external access
+
+**Client Connection:**
+- **Windows**: TigerVNC Viewer to `192.168.0.100:5901`
+- **SSH Tunnel**: `ssh -L 5901:localhost:5901 hoborg@192.168.0.100 -p 2222`
+- **Tunneled Access**: VNC client to `localhost:5901`
+
+**Service Features:**
+- ✅ Systemd integration with proper session management
+- ✅ Automatic startup on boot
+- ✅ User-specific VNC sessions via `/etc/tigervnc/vncserver.users`
+- ✅ Uses `vncsession-start` for robust X11 handling
+- ✅ Proper PID file management in `/run/vncsession-:1.pid`
+
+**Security Considerations:**
+- VNC traffic is unencrypted - use SSH tunneling for remote access
+- Firewall configuration needed for direct external access
+- Consider VPN access instead of direct port forwarding