homelab/docs/admin-services-setup.md

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:

[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:

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