From 914e8a0ba7431a04f31ee6115746fa43eda19570 Mon Sep 17 00:00:00 2001 From: Arpad Krejczinger Date: Tue, 9 Sep 2025 21:14:28 +0200 Subject: [PATCH] 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 --- docs/admin-services-setup.md | 200 +++++++++++++++++++++++++++++++++++ docs/services.md | 196 ++++++++++++++++++++++++++++++++-- 2 files changed, 390 insertions(+), 6 deletions(-) create mode 100644 docs/admin-services-setup.md diff --git a/docs/admin-services-setup.md b/docs/admin-services-setup.md new file mode 100644 index 0000000..0dee393 --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/services.md b/docs/services.md index b9bd0ae..2a8550a 100644 --- 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