210 lines
7.1 KiB
Markdown
210 lines
7.1 KiB
Markdown
# DokuWiki Documentation Mirror
|
|
|
|
*Created: February 14, 2026*
|
|
*Status: ✅ **FULLY OPERATIONAL***
|
|
*Integration: Automated documentation mirroring*
|
|
|
|
## 🎯 Overview
|
|
|
|
The homelab documentation is now mirrored in DokuWiki for improved accessibility and collaborative editing. This provides a web-based interface for viewing and editing documentation alongside the Git repository source.
|
|
|
|
## 🌐 Access Information
|
|
|
|
### DokuWiki Instance
|
|
- **URL**: http://atlantis.vish.local:8399
|
|
- **Main Page**: http://atlantis.vish.local:8399/doku.php?id=homelab:start
|
|
- **Host**: Atlantis (Synology NAS)
|
|
- **Port**: 8399
|
|
- **Authentication**: None required for viewing/editing
|
|
|
|
### Access Methods
|
|
- **LAN**: http://atlantis.vish.local:8399
|
|
- **Tailscale**: http://100.83.230.112:8399 (if Tailscale configured)
|
|
- **Direct IP**: http://192.168.0.200:8399
|
|
|
|
## 📚 Documentation Structure
|
|
|
|
### Namespace Organization
|
|
```
|
|
homelab:
|
|
├── start # Main navigation page
|
|
├── readme # Repository README
|
|
├── documentation_audit_report # Recent audit results
|
|
├── operational_status # Current system status
|
|
├── gitops_deployment_guide # GitOps procedures
|
|
├── monitoring_architecture # Monitoring setup
|
|
└── docs:
|
|
├── index # Master documentation index
|
|
├── admin:
|
|
│ └── gitops_comprehensive_guide # Complete GitOps guide
|
|
├── infrastructure:
|
|
│ └── health_report # Infrastructure health
|
|
└── runbooks:
|
|
└── add_new_service # Service deployment runbook
|
|
```
|
|
|
|
### Key Pages Available
|
|
1. **[homelab:start](http://atlantis.vish.local:8399/doku.php?id=homelab:start)** - Main navigation hub
|
|
2. **[homelab:readme](http://atlantis.vish.local:8399/doku.php?id=homelab:readme)** - Repository overview
|
|
3. **[homelab:docs:index](http://atlantis.vish.local:8399/doku.php?id=homelab:docs:index)** - Complete documentation index
|
|
4. **[homelab:docs:admin:gitops_comprehensive_guide](http://atlantis.vish.local:8399/doku.php?id=homelab:docs:admin:gitops_comprehensive_guide)** - GitOps deployment guide
|
|
|
|
## 🔄 Synchronization Process
|
|
|
|
### Automated Upload Script
|
|
**Location**: `scripts/upload-to-dokuwiki.sh`
|
|
|
|
**Features**:
|
|
- Converts Markdown to DokuWiki syntax
|
|
- Maintains source attribution and timestamps
|
|
- Creates proper namespace structure
|
|
- Handles formatting conversion (headers, lists, code, links)
|
|
|
|
### Conversion Features
|
|
- **Headers**: `# Title` → `====== Title ======`
|
|
- **Bold/Italic**: `**bold**` → `**bold**`, `*italic*` → `//italic//`
|
|
- **Code**: `` `code` `` → `%%code%%`
|
|
- **Lists**: `- item` → ` * item`
|
|
- **Checkboxes**: `- [x]` → ` * ✅`, `- [ ]` → ` * ☐`
|
|
|
|
### Manual Sync Process
|
|
```bash
|
|
# Navigate to repository
|
|
cd /home/homelab/organized/repos/homelab
|
|
|
|
# Run upload script
|
|
./scripts/upload-to-dokuwiki.sh
|
|
|
|
# Verify results
|
|
curl -s "http://atlantis.vish.local:8399/doku.php?id=homelab:start"
|
|
```
|
|
|
|
## 📊 Current Status
|
|
|
|
### Upload Results (February 14, 2026)
|
|
- **Total Files**: 9 documentation files
|
|
- **Success Rate**: 100% (9/9 successful)
|
|
- **Failed Uploads**: 0
|
|
- **Pages Created**: 10 (including main index)
|
|
|
|
### Successfully Mirrored Documents
|
|
1. ✅ Main README.md
|
|
2. ✅ Documentation Index (docs/INDEX.md)
|
|
3. ✅ GitOps Comprehensive Guide
|
|
4. ✅ Documentation Audit Report
|
|
5. ✅ Infrastructure Health Report
|
|
6. ✅ Add New Service Runbook
|
|
7. ✅ GitOps Deployment Guide
|
|
8. ✅ Operational Status
|
|
9. ✅ Monitoring Architecture
|
|
|
|
## 🛠️ Maintenance
|
|
|
|
### Regular Sync Schedule
|
|
- **Frequency**: As needed after major documentation updates
|
|
- **Method**: Run `./scripts/upload-to-dokuwiki.sh`
|
|
- **Verification**: Check key pages for proper formatting
|
|
|
|
### Monitoring
|
|
- **Health Check**: Verify DokuWiki accessibility
|
|
- **Content Check**: Ensure pages load and display correctly
|
|
- **Link Validation**: Check internal navigation links
|
|
|
|
### Troubleshooting
|
|
```bash
|
|
# Test DokuWiki connectivity
|
|
curl -I "http://atlantis.vish.local:8399/doku.php?id=homelab:start"
|
|
|
|
# Check if pages exist
|
|
curl -s "http://atlantis.vish.local:8399/doku.php?id=homelab:readme" | grep -i "title"
|
|
|
|
# Re-upload specific page
|
|
curl -X POST "http://atlantis.vish.local:8399/doku.php" \
|
|
-d "id=homelab:test" \
|
|
-d "do=save" \
|
|
-d "summary=Manual update" \
|
|
--data-urlencode "wikitext=Your content here"
|
|
```
|
|
|
|
## 🔧 Technical Details
|
|
|
|
### DokuWiki Configuration
|
|
- **Version**: Standard DokuWiki installation
|
|
- **Theme**: Default template
|
|
- **Permissions**: Open editing (no authentication required)
|
|
- **Namespace**: `homelab:*` for all repository documentation
|
|
|
|
### Script Dependencies
|
|
- **curl**: For HTTP requests to DokuWiki
|
|
- **sed**: For Markdown to DokuWiki conversion
|
|
- **bash**: Shell scripting environment
|
|
|
|
### File Locations
|
|
```
|
|
scripts/
|
|
├── upload-to-dokuwiki.sh # Main upload script
|
|
└── md-to-dokuwiki.py # Python conversion script (alternative)
|
|
```
|
|
|
|
## 🎯 Benefits
|
|
|
|
### For Users
|
|
- **Web Interface**: Easy browsing without Git knowledge
|
|
- **Search**: Built-in DokuWiki search functionality
|
|
- **Collaborative Editing**: Multiple users can edit simultaneously
|
|
- **History**: DokuWiki maintains page revision history
|
|
|
|
### For Administrators
|
|
- **Dual Source**: Git repository remains authoritative
|
|
- **Easy Updates**: Simple script-based synchronization
|
|
- **Backup**: Additional copy of documentation
|
|
- **Accessibility**: Web-based access from any device
|
|
|
|
## 🔗 Integration with Repository
|
|
|
|
### Source of Truth
|
|
- **Primary**: Git repository at https://git.vish.gg/Vish/homelab
|
|
- **Mirror**: DokuWiki at http://atlantis.vish.local:8399
|
|
- **Sync Direction**: Repository → DokuWiki (one-way)
|
|
|
|
### Workflow
|
|
1. Update documentation in Git repository
|
|
2. Commit and push changes
|
|
3. Run `./scripts/upload-to-dokuwiki.sh` to sync to DokuWiki
|
|
4. Verify formatting and links in DokuWiki
|
|
|
|
### Cross-References
|
|
- Each DokuWiki page includes source file attribution
|
|
- Repository documentation links to DokuWiki when appropriate
|
|
- Master index available in both formats
|
|
|
|
## 📈 Future Enhancements
|
|
|
|
### Planned Improvements
|
|
1. **Automated Sync**: Git hooks to trigger DokuWiki updates
|
|
2. **Bidirectional Sync**: Allow DokuWiki edits to flow back to Git
|
|
3. **Enhanced Formatting**: Better table and image conversion
|
|
4. **Template System**: Standardized page templates
|
|
|
|
### Monitoring Integration
|
|
- **Health Checks**: Include DokuWiki in monitoring stack
|
|
- **Alerting**: Notify if DokuWiki becomes unavailable
|
|
- **Metrics**: Track page views and edit frequency
|
|
|
|
## 🎉 Conclusion
|
|
|
|
The DokuWiki integration provides an excellent complement to the Git-based documentation system, offering:
|
|
|
|
- ✅ **Easy Access**: Web-based interface for all users
|
|
- ✅ **Maintained Sync**: Automated upload process
|
|
- ✅ **Proper Formatting**: Converted Markdown displays correctly
|
|
- ✅ **Complete Coverage**: All major documentation mirrored
|
|
- ✅ **Navigation**: Organized namespace structure
|
|
|
|
The system is now fully operational and ready for regular use alongside the Git repository.
|
|
|
|
---
|
|
|
|
**Last Updated**: February 14, 2026
|
|
**Next Review**: March 14, 2026
|
|
**Maintainer**: Homelab Administrator |