hoborg/homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation for admin services implementation

Browse Source 
- 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
This commit is contained in:
Arpad Krejczinger
2025-09-09 21:14:28 +02:00
parent 2fa9ec3a20
commit 914e8a0ba7
2 changed files with 390 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

200
docs/admin-services-setup.md Normal file
View File

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

184
docs/services.md
View File

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