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