Sanitized mirror from private repository - 2026-04-19 09:52:01 UTC

2026-04-19 09:52:01 +00:00
commit d90cf1f849
1439 changed files with 363705 additions and 0 deletions
--- a/docs/admin/DOCUMENTATION_MAINTENANCE_GUIDE.md
+++ b/docs/admin/DOCUMENTATION_MAINTENANCE_GUIDE.md
@@ -0,0 +1,294 @@
+# 📚 Documentation Maintenance Guide
+
+*Comprehensive guide for maintaining homelab documentation across all systems*
+
+## 🎯 Overview
+
+This guide covers the maintenance procedures for keeping documentation synchronized and up-to-date across all three documentation systems:
+
+1. **Git Repository** (Primary source of truth)
+2. **DokuWiki Mirror** (Web-based access)
+3. **Gitea Wiki** (Native Git integration)
+
+## 🏗️ Documentation Architecture
+
+### System Hierarchy
+```
+📚 Documentation Systems
+├── 🏠 Git Repository (git.vish.gg/Vish/homelab)
+│   ├── Status: ✅ Primary source of truth
+│   ├── Location: /home/homelab/organized/repos/homelab/docs/
+│   └── Structure: Organized hierarchical folders
+│
+├── 🌐 DokuWiki Mirror (atlantis.vish.local:8399)
+│   ├── Status: ✅ Fully operational (160 pages)
+│   ├── Sync: Manual via scripts/sync-dokuwiki-simple.sh
+│   └── Access: Web interface, collaborative editing
+│
+└── 📖 Gitea Wiki (git.vish.gg/Vish/homelab/wiki)
+    ├── Status: 🔄 Partially organized (364 pages)
+    ├── Sync: API-based via Gitea token
+    └── Access: Native Git integration
+```
+
+## 🔄 Synchronization Procedures
+
+### 1. DokuWiki Synchronization
+
+#### Full Sync Process
+```bash
+# Navigate to repository
+cd /home/homelab/organized/repos/homelab
+
+# Run DokuWiki sync script
+./scripts/sync-dokuwiki-simple.sh
+
+# Verify installation
+ssh -p 60000 vish@192.168.0.200 "
+  curl -s 'http://localhost:8399/doku.php?id=homelab:start' | grep -E 'title' | head -1
+"
+```
+
+#### Manual Page Upload
+```bash
+# Convert single markdown file to DokuWiki
+convert_md_to_dokuwiki() {
+    local input_file="$1"
+    local output_file="$2"
+    
+    sed -e 's/^# \(.*\)/====== \1 ======/' \
+        -e 's/^## \(.*\)/===== \1 =====/' \
+        -e 's/^### \(.*\)/==== \1 ====/' \
+        -e 's/^#### \(.*\)/=== \1 ===/' \
+        -e 's/\*\*\([^*]*\)\*\*/\*\*\1\*\*/g' \
+        -e 's/\*\([^*]*\)\*/\/\/\1\/\//g' \
+        -e 's/`\([^`]*\)`/%%\1%%/g' \
+        -e 's/^- \[x\]/  * ✅/' \
+        -e 's/^- \[ \]/  * ☐/' \
+        -e 's/^- /  * /' \
+        "$input_file" > "$output_file"
+}
+```
+
+### 2. Gitea Wiki Management
+
+#### API Authentication
+```bash
+# Set Gitea API token
+export GITEA_TOKEN=REDACTED_TOKEN
+export GITEA_URL="https://git.vish.gg"
+export REPO_OWNER="Vish"
+export REPO_NAME="homelab"
+```
+
+#### Create/Update Wiki Pages
+```bash
+# Create new wiki page
+create_wiki_page() {
+    local page_name="$1"
+    local content="$2"
+    
+    curl -X POST "$GITEA_URL/api/v1/repos/$REPO_OWNER/$REPO_NAME/wiki" \
+        -H "Authorization: token $GITEA_TOKEN" \
+        -H "Content-Type: application/json" \
+        -d "{
+            \"title\": \"$page_name\",
+            \"content_base64\": \"$(echo -n "$content" | base64 -w 0)\",
+            \"message\": \"Update $page_name documentation\"
+        }"
+}
+```
+
+## 📊 Current Status Assessment
+
+### Documentation Coverage Analysis
+
+#### Repository Structure (✅ Complete)
+```
+docs/
+├── admin/           # 23 files - Administration guides
+├── advanced/        # 9 files - Advanced topics
+├── getting-started/ # 8 files - Beginner guides
+├── hardware/        # 5 files - Hardware documentation
+├── infrastructure/  # 25 files - Infrastructure guides
+├── runbooks/        # 7 files - Operational procedures
+├── security/        # 2 files - Security documentation
+├── services/        # 15 files - Service documentation
+└── troubleshooting/ # 18 files - Troubleshooting guides
+```
+
+#### DokuWiki Status (✅ Synchronized)
+- **Total Pages**: 160 pages successfully synced
+- **Structure**: Hierarchical namespace organization
+- **Last Sync**: February 14, 2026
+- **Access**: http://atlantis.vish.local:8399/doku.php?id=homelab:start
+
+#### Gitea Wiki Status (🔄 Needs Cleanup)
+- **Total Pages**: 364 pages (many outdated/duplicate)
+- **Structure**: Flat list requiring reorganization
+- **Issues**: Missing category pages, broken navigation
+- **Priority**: Medium - functional but needs improvement
+
+## 🛠️ Maintenance Tasks
+
+### Daily Tasks
+- [ ] Check for broken links in documentation
+- [ ] Verify DokuWiki accessibility
+- [ ] Monitor Gitea Wiki for spam/unauthorized changes
+
+### Weekly Tasks
+- [ ] Review and update operational status documents
+- [ ] Sync any new documentation to DokuWiki
+- [ ] Check documentation metrics and usage
+
+### Monthly Tasks
+- [ ] Full documentation audit
+- [ ] Update service inventory and status
+- [ ] Review and update troubleshooting guides
+- [ ] Clean up outdated Gitea Wiki pages
+
+### Quarterly Tasks
+- [ ] Comprehensive documentation reorganization
+- [ ] Update all architecture diagrams
+- [ ] Review and update security documentation
+- [ ] Performance optimization of documentation systems
+
+## 🔍 Quality Assurance
+
+### Documentation Standards
+1. **Consistency**: Use standardized templates and formatting
+2. **Accuracy**: Verify all procedures and commands
+3. **Completeness**: Ensure all services are documented
+4. **Accessibility**: Test all links and navigation
+5. **Currency**: Keep status indicators up to date
+
+### Review Checklist
+```markdown
+## Documentation Review Checklist
+
+### Content Quality
+- [ ] Information is accurate and current
+- [ ] Procedures have been tested
+- [ ] Links are functional
+- [ ] Code examples work as expected
+- [ ] Screenshots are current (if applicable)
+
+### Structure & Navigation
+- [ ] Proper heading hierarchy
+- [ ] Clear table of contents
+- [ ] Cross-references are accurate
+- [ ] Navigation paths are logical
+
+### Formatting & Style
+- [ ] Consistent markdown formatting
+- [ ] Proper use of status indicators (✅ 🔄 ⚠️ ❌)
+- [ ] Code blocks are properly formatted
+- [ ] Lists and tables are well-structured
+
+### Synchronization
+- [ ] Changes reflected in all systems
+- [ ] DokuWiki formatting is correct
+- [ ] Gitea Wiki links are functional
+```
+
+## 🚨 Troubleshooting
+
+### Common Issues
+
+#### DokuWiki Sync Failures
+```bash
+# Check DokuWiki accessibility
+curl -I http://atlantis.vish.local:8399/doku.php?id=homelab:start
+
+# Verify SSH access to Atlantis
+ssh -p 60000 vish@192.168.0.200 "echo 'SSH connection successful'"
+
+# Check DokuWiki data directory permissions
+ssh -p 60000 vish@192.168.0.200 "
+  ls -la /volume1/@appdata/REDACTED_APP_PASSWORD/all_shares/metadata/docker/dokuwiki/dokuwiki/data/pages/
+"
+```
+
+#### Gitea Wiki API Issues
+```bash
+# Test API connectivity
+curl -H "Authorization: token $GITEA_TOKEN" \
+  "$GITEA_URL/api/v1/repos/$REPO_OWNER/$REPO_NAME/wiki"
+
+# Verify token permissions
+curl -H "Authorization: token $GITEA_TOKEN" \
+  "$GITEA_URL/api/v1/user"
+```
+
+#### Repository Sync Issues
+```bash
+# Check Git status
+git status
+git log --oneline -5
+
+# Verify remote connectivity
+git remote -v
+git fetch origin
+```
+
+## 📈 Metrics and Monitoring
+
+### Key Performance Indicators
+1. **Documentation Coverage**: % of services with complete documentation
+2. **Sync Frequency**: How often documentation is synchronized
+3. **Access Patterns**: Which documentation is most frequently accessed
+4. **Update Frequency**: How often documentation is updated
+5. **Error Rates**: Sync failures and broken links
+
+### Monitoring Commands
+```bash
+# Count total documentation files
+find docs/ -name "*.md" | wc -l
+
+# Check for broken internal links
+grep -r "\[.*\](.*\.md)" docs/ | grep -v "http" | while read line; do
+    file=$(echo "$line" | cut -d: -f1)
+    link=$(echo "$line" | sed 's/.*](\([^)]*\)).*/\1/')
+    if [[ ! -f "$(dirname "$file")/$link" ]] && [[ ! -f "$link" ]]; then
+        echo "Broken link in $file: $link"
+    fi
+done
+
+# DokuWiki health check
+curl -s http://atlantis.vish.local:8399/doku.php?id=homelab:start | \
+  grep -q "homelab:start" && echo "✅ DokuWiki OK" || echo "❌ DokuWiki Error"
+```
+
+## 🔮 Future Improvements
+
+### Automation Opportunities
+1. **Git Hooks**: Automatic DokuWiki sync on repository push
+2. **Scheduled Sync**: Cron jobs for regular synchronization
+3. **Health Monitoring**: Automated documentation health checks
+4. **Link Validation**: Automated broken link detection
+
+### Enhanced Features
+1. **Bidirectional Sync**: Allow DokuWiki edits to flow back to Git
+2. **Version Control**: Better tracking of documentation changes
+3. **Search Integration**: Unified search across all documentation systems
+4. **Analytics**: Usage tracking and popular content identification
+
+## 📞 Support and Escalation
+
+### Contact Information
+- **Repository Issues**: https://git.vish.gg/Vish/homelab/issues
+- **DokuWiki Access**: http://atlantis.vish.local:8399
+- **Emergency Access**: SSH to vish@192.168.0.200:60000
+
+### Escalation Procedures
+1. **Minor Issues**: Create repository issue with "documentation" label
+2. **Sync Failures**: Check system status and retry
+3. **Major Outages**: Follow emergency access procedures
+4. **Data Loss**: Restore from Git repository (source of truth)
+
+---
+
+**Last Updated**: February 14, 2026  
+**Next Review**: March 14, 2026  
+**Maintainer**: Homelab Administrator  
+**Status**: ✅ Active and Operational