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/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