iSuTech Knowledge Hub - Admin Guide

iSuTech Knowledge Hub - Admin Guide

For System Administrators

---

🎯 Overview

This guide is for administrators who manage the iSuTech Knowledge Hub infrastructure, security, and maintenance.

Your responsibilities:

• User access management
• System monitoring
• Monthly maintenance
• Troubleshooting issues
• Security management

Server: Hetzner (46.224.40.5) Site: https://docs.isutech.co.za Repository: https://github.com/gedeza/isutech-knowledge-hub

---

🔐 Access Management

Adding New Users

On the server, run:

# SSH to server
ssh root@46.224.40.5

# Add new user to password file
htpasswd /etc/nginx/.htpasswd newusername

# Enter password when prompted (twice)

Example:

htpasswd /etc/nginx/.htpasswd john.doe
New password: ********
Re-type new password: ********
Adding password for user john.doe

No restart needed - works immediately!

---

Removing Users

# Remove user from password file
htpasswd -D /etc/nginx/.htpasswd username

---

Changing Passwords

# Change existing user's password
htpasswd /etc/nginx/.htpasswd username

# Enter new password when prompted

Security Best Practice: Rotate the main password quarterly.

---

Listing All Users

# View all users
cat /etc/nginx/.htpasswd

# Output shows usernames (passwords are hashed)

---

📊 System Monitoring

Daily Health Checks (5 minutes)

Quick verification:

# SSH to server
ssh root@46.224.40.5

# Check all services
systemctl status nginx
systemctl status cron

# Check recent auto-updates
tail -n 20 /var/log/docs-update.log

# Should show: "Update Completed Successfully"

Green lights:

• ✅ Nginx: active (running)
• ✅ Cron: active (running)
• ✅ Last update: successful
• ✅ No errors in logs

---

Weekly Checks (10 minutes)

# Check disk space
df -h
# Should be <80% full

# Check logs size
du -sh /var/log/docs-update.log
du -sh /var/log/nginx/

# Check SSL certificate
certbot certificates
# Should show >30 days remaining

# Test site accessibility
curl -I https://docs.isutech.co.za
# Should return: HTTP/2 200 (after auth)

---

🔄 Manual Updates

Trigger Update Immediately

# Instead of waiting 10 minutes for auto-update
/var/www/docs/scripts/update-docs.sh

# Check logs
tail -n 30 /var/log/docs-update.log

When to use:

• Urgent documentation update needed
• Testing after configuration change
• Troubleshooting update issues

---

Force Rebuild

# Navigate to repository
cd /var/www/docs/repo

# Activate virtual environment
source /var/www/docs/venv/bin/activate

# Clean rebuild
mkdocs build --clean

# Check for errors in output

---

🛠️ Configuration Management

Update Nginx Configuration

# Edit nginx config
nano /etc/nginx/sites-available/docs.isutech.co.za

# Make changes

# Test configuration
nginx -t

# If successful, reload
systemctl reload nginx

# Verify
systemctl status nginx

Common changes:

• Add new IP to whitelist
• Update password file path
• Adjust caching settings

---

Update Auto-Update Script

# Edit update script
nano /var/www/docs/scripts/update-docs.sh

# Make changes

# Test manually
/var/www/docs/scripts/update-docs.sh

# Check logs
tail -n 50 /var/log/docs-update.log

---

Update Cron Schedule

# Edit cron jobs
crontab -e

# Current: */10 * * * * /var/www/docs/scripts/update-docs.sh
# (every 10 minutes)

# Change to hourly:
# 0 * * * * /var/www/docs/scripts/update-docs.sh

# Save and exit

---

🔐 Security Management

SSL Certificate Management

Check certificate status:

certbot certificates

# Output shows:
# - Certificate name
# - Domains
# - Expiry date
# - Certificate path

Manual renewal (if needed):

certbot renew

# Or specific domain:
certbot renew --cert-name docs.isutech.co.za

# Reload nginx
systemctl reload nginx

Test renewal process:

certbot renew --dry-run

# Should complete successfully

Auto-renewal: Configured automatically by Certbot. Runs twice daily.

---

Password Security

Strong password guidelines:

• Minimum 12 characters
• Mix of upper/lower case
• Include numbers and symbols
• Not a dictionary word
• Unique to this system

Recommended: Use password manager to generate and store.

Rotation schedule:

• Main password: Every 3 months
• Individual users: As needed
• After staff departure: Immediately

---

Access Log Review

# Check who's accessing the site
tail -n 100 /var/log/nginx/docs-access.log

# Check for failed login attempts
grep " 401 " /var/log/nginx/docs-access.log | tail -n 20

# Check for errors
tail -n 50 /var/log/nginx/docs-error.log

Red flags:

• Many 401 errors (failed logins) from one IP
• Unusual access patterns
• Errors in error log

---

🆘 Troubleshooting

Issue: Site Not Loading

Diagnosis:

systemctl status nginx
nginx -t
tail -n 50 /var/log/nginx/docs-error.log

Fix:

# Restart nginx
systemctl restart nginx

# If configuration error:
nginx -t  # Shows error line
nano /etc/nginx/sites-available/docs.isutech.co.za
# Fix error
nginx -t  # Test again
systemctl reload nginx

---

Issue: Documentation Not Updating

Diagnosis:

# Check update log
tail -n 100 /var/log/docs-update.log

# Check Git status
cd /var/www/docs/repo
git status
git log -n 5

# Check cron is running
systemctl status cron

Fix:

# Manual update
/var/www/docs/scripts/update-docs.sh

# If Git issues:
cd /var/www/docs/repo
git pull origin main

# If build fails:
source /var/www/docs/venv/bin/activate
mkdocs build --clean

---

Issue: SSL Certificate Expired

Diagnosis:

certbot certificates
# Check expiry date

Fix:

# Manual renewal
certbot renew
systemctl reload nginx

# If renewal fails, check:
tail -n 50 /var/log/letsencrypt/letsencrypt.log

---

Issue: Disk Space Full

Diagnosis:

df -h
# Check % used

Fix:

# Clean old logs
journalctl --vacuum-time=30d

# Remove old nginx logs
find /var/log/nginx -name "*.gz" -mtime +90 -delete

# Clean apt cache
apt clean

# Check again
df -h

---

📅 Monthly Maintenance (15 minutes)

First Monday of each month:

Task 1: Update System Packages

apt update
apt upgrade -y

# Check if reboot needed
[ -f /var/run/reboot-required ] && echo "Reboot required"

# If needed (schedule during off-hours):
reboot

---

Task 2: Review Logs

# Documentation updates
tail -n 100 /var/log/docs-update.log
grep -i "error" /var/log/docs-update.log | tail -n 20

# Nginx errors
tail -n 50 /var/log/nginx/docs-error.log

# Failed logins
grep " 401 " /var/log/nginx/docs-access.log | tail -n 20

---

Task 3: Disk Space Check

df -h
du -sh /var/www/docs
du -sh /var/log/nginx

Action if >80% full: Clean logs (see troubleshooting above)

---

Task 4: SSL Certificate Check

certbot certificates

# Should show >30 days remaining

# Test renewal
certbot renew --dry-run

---

Task 5: Update MkDocs Material (if new version)

Check https://github.com/squidfunk/mkdocs-material/releases

source /var/www/docs/venv/bin/activate
pip list | grep mkdocs-material

# If update available:
pip install --upgrade mkdocs-material
pip install --upgrade mkdocs-git-revision-date-localized-plugin
pip install --upgrade mkdocs-minify-plugin

# Test build
cd /var/www/docs/repo
mkdocs build

---

Task 6: Backup Password File

# Create monthly backup
cp /etc/nginx/.htpasswd /root/backups/htpasswd-$(date +%Y%m%d).bak

# Keep last 12 months only
find /root/backups/ -name "htpasswd-*.bak" -mtime +365 -delete

---

📁 Important File Locations

Server Paths

# Documentation
/var/www/docs/                     # Main directory
/var/www/docs/repo/                # Git repository
/var/www/docs/repo/site/           # Built static site (served by Nginx)
/var/www/docs/venv/                # Python virtual environment
/var/www/docs/scripts/             # Auto-update script

# Configuration
/etc/nginx/sites-available/docs.isutech.co.za  # Nginx config
/etc/nginx/sites-enabled/docs.isutech.co.za    # Symlink to above
/etc/nginx/.htpasswd                            # Password file

# Logs
/var/log/docs-update.log           # Auto-update logs
/var/log/nginx/docs-access.log     # Web access logs
/var/log/nginx/docs-error.log      # Nginx errors
/var/log/letsencrypt/              # SSL certificate logs

# SSL Certificates
/etc/letsencrypt/live/docs.isutech.co.za/  # Current certificates

---

🔑 Credentials & Access

Server Access

IP: 46.224.40.5 User: root Auth: SSH key How to connect: ssh root@46.224.40.5

GitHub Repository

Repo: https://github.com/gedeza/isutech-knowledge-hub Access: Personal Access Token Token location: [Securely stored - you have this]

Site Authentication

Username: isutech Password: [Password manager] Password file: /etc/nginx/.htpasswd

---

📊 Performance Metrics

Target metrics:

Metric	Target	Check Command
Uptime	>99.9%	systemctl status nginx
Page load	<2 seconds	Browser DevTools
Build time	<10 seconds	Check update logs
Disk space	<80%	df -h
Auto-update success	100%	Check logs
SSL validity	>30 days	certbot certificates

---

🚨 Emergency Procedures

Site Down - Emergency Response

1. Quick assessment (2 minutes):

ssh root@46.224.40.5
systemctl status nginx
nginx -t
tail -n 50 /var/log/nginx/docs-error.log

2. Quick fixes (5 minutes):

# Restart nginx
systemctl restart nginx

# If configuration error, restore backup
cp /etc/nginx/sites-available/docs.isutech.co.za.backup /etc/nginx/sites-available/docs.isutech.co.za
nginx -t
systemctl reload nginx

3. Escalate if not resolved in 10 minutes

---

Locked Out - Password Reset

# SSH to server (using SSH key)
ssh root@46.224.40.5

# Create new password for main user
htpasswd /etc/nginx/.htpasswd isutech

# Enter new password

---

Data Recovery

Git repository is the source of truth:

# If local copy corrupted, re-clone
cd /var/www/docs
mv repo repo.corrupted
git clone https://TOKEN@github.com/gedeza/isutech-knowledge-hub.git repo
/var/www/docs/scripts/update-docs.sh

Everything is in Git - no data loss possible!

---

📞 Escalation

When to Escalate

Escalate immediately if:

• Site down >30 minutes
• Security breach suspected
• Data corruption
• Server unresponsive
• SSL certificate issues not resolving

Escalation Contacts

Technical Lead: [Contact info] Hetzner Support: https://console.hetzner.cloud/ Let’s Encrypt Support: https://community.letsencrypt.org/

Information to Provide

When escalating, include:

1. What’s wrong - specific symptoms
2. When it started - date/time
3. What you tried - troubleshooting steps
4. Logs - relevant excerpts
5. Impact - who/what affected

---

✅ Admin Checklist

Keep this handy for routine tasks:

Daily (5 min):

• Check site loads
• Review update logs
• Check for errors

Weekly (10 min):

• Disk space check
• SSL certificate check
• Review access logs
• Test auto-updates

Monthly (15 min):

• Update system packages
• Review all logs
• SSL renewal test
• Update MkDocs if needed
• Backup password file

Quarterly (30 min):

• Rotate main password
• Review user access list
• Security audit
• Performance review

---

🎓 Learning Resources

MkDocs Material:

• Docs: https://squidfunk.github.io/mkdocs-material/
• GitHub: https://github.com/squidfunk/mkdocs-material

Nginx:

• Docs: https://nginx.org/en/docs/
• Beginners Guide: https://nginx.org/en/docs/beginners_guide.html

Let’s Encrypt:

• Certbot: https://certbot.eff.org/
• Community: https://community.letsencrypt.org/

Linux System Administration:

• Ubuntu Server: https://ubuntu.com/server/docs

---

📝 Change Log

Keep a log of major changes:

Date: DD/MM/YYYY
Admin: [Your Name]
Change: [What changed]
Reason: [Why]
Result: [Outcome]

Example:

Date: 09/11/2025
Admin: Technical Lead
Change: Added logo to header
Reason: Professional branding
Result: Successfully deployed

---

iSuTech Knowledge Hub Admin Guide Last Updated: 09/11/2025 Questions? Contact Technical Lead