ITL Documentation Hub

A modern, dual-service documentation platform that provides a central landing page for all ITlusions documentation sites. The hub consists of a MkDocs Material frontend and a Node.js REST API backend, enabling automatic discovery and aggregation of distributed documentation sites.

🎯 Purpose

The ITL Documentation Hub serves as:

• Central Landing Page - Single entry point for all ITL documentation with live statistics
• Service Registry - REST API for automatic registration and discovery of documentation sites
• Health Monitoring - Real-time monitoring of registered documentation sites with uptime tracking
• Statistics Dashboard - Visual insights into documentation usage and site availability
• Unified Search - Cross-documentation search and navigation (planned)

🏗️ Architecture

The hub consists of two main services working together:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MkDocs Site   │    │   MkDocs Site   │    │   MkDocs Site   │
│   (Identity)    │    │  (Kubernetes)   │    │  (Monitoring)   │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          │ Registration API     │ Registration API     │ Registration API
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────▼───────────┐
                    │    Documentation Hub    │
                    │                         │
                    │  ┌─────────────────┐   │
                    │  │   Frontend      │   │  Port 8080
                    │  │  MkDocs+nginx   │   │  ├─ Landing page
                    │  │  Material Theme │   │  ├─ Site registry
                    │  └─────────────────┘   │  └─ Statistics
                    │           │             │
                    │  ┌─────────▼───────┐   │
                    │  │   API Backend   │   │  Port 3000
                    │  │   Node.js/      │   │  ├─ Site registration
                    │  │   Express       │   │  ├─ Health checks
                    │  └─────────────────┘   │  └─ Statistics API
                    └─────────────────────────┘

Service Components

1. Frontend Service (docs-hub-frontend)

   • Technology: MkDocs Material + nginx
   • Port: 8080
   • Purpose: Serves the documentation landing page with dynamic site registry
   • Features: Statistics dashboard, responsive design, real-time updates

2. API Backend (docs-api)

   • Technology: Node.js + Express
   • Port: 3000
   • Purpose: REST API for site registration and health monitoring
   • Features: JWT authentication, rate limiting, comprehensive testing

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm (for API backend)
• Python 3.11+ and pip (for frontend)
• Docker and Docker Compose (recommended)
• Git

Local Development with Docker Compose (Recommended)

1. Clone and setup:

   git clone https://github.com/ITlusions/ITL.Docs.Hub.git
   cd ITL.Docs.Hub

2. Start both services:

   # Start both frontend and API
   docker-compose up -d
   
   # View logs
   docker-compose logs -f

3. Access the services:

   • Frontend: http://localhost:8080 (Documentation hub)
   • API: http://localhost:3000/api (REST endpoints)
   • Health checks:
     • Frontend: http://localhost:8080/health
     • API: http://localhost:3000/api/health

Manual Development Setup

Frontend Service

# Install Python dependencies
pip install -r requirements.txt

# Start MkDocs development server  
mkdocs serve --dev-addr=0.0.0.0:8080

API Service

# Navigate to API directory
cd api

# Install Node.js dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Start API server
npm start
# or for development with auto-reload
npm run dev

📋 Features

✅ Implemented Features

For Documentation Authors

• ✅ REST API Registration - Simple API endpoint to register documentation sites
• ✅ JWT Authentication - Secure API access with token-based authentication
• ✅ Health Monitoring - API endpoints for site health checking
• ✅ Version Tracking - Track documentation versions and deployments
• ✅ Comprehensive Testing - Full Jest test suite with 17+ test cases

For Documentation Readers

• ✅ Modern Landing Page - Material Design documentation hub
• ✅ Live Statistics - Real-time statistics dashboard showing registered sites
• ✅ Site Registry - Dynamic listing of all registered documentation sites
• ✅ Responsive Design - Mobile-friendly interface with dark/light mode
• ✅ Health Status - Visual indicators for site availability

Technical Features

• ✅ Dual-Service Architecture - Separate frontend and API services
• ✅ Docker Containerization - Full Docker Compose setup
• ✅ Kubernetes Deployment - Production-ready Helm charts
• ✅ CI/CD Pipeline - GitHub Actions with security scanning
• ✅ Rate Limiting - API protection against abuse
• ✅ Comprehensive Logging - Structured logging for debugging

🚧 Planned Features

• Unified Search - Cross-documentation search functionality
• Analytics Dashboard - Usage and performance metrics
• Notification System - Health alerts and status updates
• Content Aggregation - Cross-site content indexing

🔗 API Integration

The REST API provides endpoints for managing documentation sites. All endpoints require JWT authentication.

Authentication

First, obtain an authentication token:

curl -X POST http://localhost:3000/api/auth \
  -H "Content-Type: application/json" \
  -d '{"password": "admin123"}'

Register Documentation Site

curl -X POST http://localhost:3000/api/sites \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "name": "My Documentation",
    "description": "Description of my documentation",
    "url": "https://docs.itlusions.com/my-docs/",
    "icon": "material/book",
    "category": "Platform",
    "tags": ["platform", "guide"],
    "version": "v1.0.0"
  }'

Available API Endpoints

Method	Endpoint	Description	Auth Required
GET	/api/health	API health check	❌
GET	/api/sites	List all registered sites	❌
GET	/api/stats	Get statistics dashboard data	❌
POST	/api/auth	Authenticate and get JWT token	❌
POST	/api/sites	Register new documentation site	✅
PUT	/api/sites/:id	Update existing site	✅
DELETE	/api/sites/:id	Remove site from registry	✅

GitHub Actions Integration

Add to your deployment workflow:

- name: Register with Documentation Hub
  run: |
    # Get authentication token
    TOKEN=$(curl -s -X POST http://docs-hub.internal/api/auth \
      -H "Content-Type: application/json" \
      -d '{"password": "${{ secrets.DOCS_HUB_PASSWORD }}"}' | \
      jq -r '.token')
    
    # Register the site
    curl -X POST http://docs-hub.internal/api/sites \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $TOKEN" \
      -d '{
        "name": "${{ env.SITE_NAME }}",
        "description": "${{ env.SITE_DESCRIPTION }}",
        "url": "${{ env.DEPLOYMENT_URL }}",
        "version": "${{ github.ref_name }}",
        "repository": "${{ github.repository }}",
        "commit": "${{ github.sha }}"
      }'

Testing the API

Use the provided testing scripts:

# PowerShell (Windows)
.\test-api.ps1

# Bash (Linux/macOS)  
./test-api.sh

Or run the automated test suite:

cd api
npm test

📚 Project Structure

ITL.Docs.Hub/
├── docs/                          # MkDocs frontend content
│   ├── index.md                   # Landing page with dynamic registry
│   ├── registry.md                # Site registry page  
│   ├── statistics.md              # Statistics dashboard
│   └── getting-started.md         # Integration guide
├── api/                           # Node.js API backend
│   ├── server.js                  # Express server
│   ├── package.json               # Node.js dependencies
│   ├── data/                      # JSON data storage
│   │   └── sites.json             # Registered sites database
│   ├── __tests__/                 # Jest test suite
│   │   └── api.test.js            # Comprehensive API tests
│   └── Dockerfile                 # API container image
├── charts/                        # Helm chart for Kubernetes
│   └── docs-hub/                  # Production deployment
├── .github/workflows/             # CI/CD pipeline
│   └── ci.yml                     # GitHub Actions workflow
├── docker-compose.yml             # Local development setup
├── Dockerfile.frontend            # Frontend container image
├── mkdocs.yml                     # MkDocs configuration
└── test-api.ps1 / test-api.sh     # API testing scripts

🔧 Configuration

Environment Variables

Frontend Service

• DOCS_HUB_API_URL - API backend URL (default: http://docs-api:3000/api)

API Service

• NODE_ENV - Environment mode (development, production, test)
• PORT - API server port (default: 3000)
• JWT_SECRET - Secret key for JWT token signing (⚠️ Change in production!)
• ADMIN_PASSWORD - Admin password for authentication (⚠️ Change in production!)

Docker Compose Configuration

The docker-compose.yml file includes:

# Frontend on port 8080
docs-hub-frontend:
  build: 
    dockerfile: Dockerfile.frontend
  ports: ["8080:8080"]

# API on port 3000  
docs-api:
  build: 
    context: ./api
  ports: ["3000:3000"]
  environment:
    - JWT_SECRET=your-secret-key
    - ADMIN_PASSWORD=your-admin-password

Security Configuration

🔒 Important: Change default credentials before deployment:

1. Generate secure JWT secret:

   node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

2. Set strong admin password in environment variables

3. Use HTTPS in production with proper TLS certificates

🚢 Deployment

Production Deployment with Docker Compose

For production deployment, create a production docker-compose file:

# Create production compose file
cp docker-compose.yml docker-compose.prod.yml

# Update environment variables for production
# Edit docker-compose.prod.yml:
# - Change JWT_SECRET and ADMIN_PASSWORD
# - Set NODE_ENV=production  
# - Configure proper volumes for data persistence

# Deploy to production
docker-compose -f docker-compose.prod.yml up -d

Kubernetes Deployment with Helm

Use the included Helm chart for production Kubernetes deployment:

# Add custom values
helm install docs-hub ./charts/docs-hub \
  --set frontend.image.repository=ghcr.io/itlusions/docs-hub-frontend \
  --set frontend.image.tag=latest \
  --set api.image.repository=ghcr.io/itlusions/docs-hub-api \
  --set api.image.tag=latest \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=docs.itlusions.com \
  --set api.auth.jwtSecret="your-secure-jwt-secret" \
  --set api.auth.adminPassword="your-secure-admin-password"

Single Container Deployment (Not Recommended)

For simple single-service deployment:

# Frontend only (without API)
docker run -d \
  --name docs-hub-frontend \
  -p 8080:8080 \
  ghcr.io/itlusions/docs-hub-frontend:latest

# API only (without frontend)  
docker run -d \
  --name docs-hub-api \
  -p 3000:3000 \
  -e JWT_SECRET=your-secret \
  -e ADMIN_PASSWORD=your-password \
  ghcr.io/itlusions/docs-hub-api:latest

🧪 Testing

Automated Testing

The project includes comprehensive Jest tests covering all API functionality:

# Run all tests
cd api && npm test

# Run tests with coverage
cd api && npm test -- --coverage

# Run tests in watch mode (for development)
cd api && npm test -- --watch

Manual API Testing

Use the provided testing scripts to verify API functionality:

# PowerShell script (Windows)
.\test-api.ps1

# Bash script (Linux/macOS)
./test-api.sh

Both scripts test:

• API health checks
• Authentication
• Site registration and management
• Statistics endpoint
• Error handling

Integration Testing

Test the full application stack:

# Start services
docker-compose up -d

# Wait for services to be ready
sleep 10

# Test frontend
curl -f http://localhost:8080/health

# Test API  
curl -f http://localhost:3000/api/health

# Run API integration tests
.\test-api.ps1

# Cleanup
docker-compose down

📊 Monitoring and Health Checks

Built-in Health Monitoring

Both services include comprehensive health checks:

Frontend Health Check

# Check frontend status
curl http://localhost:8080/health

# Response: "OK" (nginx health check)

API Health Check

# Check API status
curl http://localhost:3000/api/health

# Response:
{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "version": "1.0.0",
  "uptime": "00:05:30",
  "environment": "development"
}

Statistics Dashboard

Access real-time statistics:

# Get hub statistics
curl http://localhost:3000/api/stats

# Response:
{
  "totalSites": 3,
  "activeSites": 2, 
  "categories": ["Platform", "Infrastructure", "Monitoring"],
  "recentActivity": [...],
  "systemInfo": {
    "uptime": "2 days",
    "version": "1.0.0"
  }
}

Docker Health Checks

Docker Compose includes automated health monitoring:

• Frontend: HTTP check on port 8080/health every 30s
• API: HTTP check on port 3000/api/health every 30s
• Restart Policy: Automatic restart on failure

Production Monitoring

The application includes built-in Prometheus metrics support for comprehensive monitoring:

Prometheus Metrics

The API exposes metrics at /metrics endpoint for Prometheus scraping:

# Access metrics endpoint
curl http://localhost:3000/metrics

Available Metrics:

• HTTP Metrics:

  • http_requests_total - Total number of HTTP requests by method, route, and status
  • http_request_duration_seconds - Request duration histogram

• Application Metrics:

  • docs_hub_sites_total - Total number of registered documentation sites
  • docs_hub_sites_healthy - Number of healthy sites
  • docs_hub_sites_by_category{category} - Sites count per category
  • docs_hub_site_pages_total - Total documentation pages
  • docs_hub_health_check_duration_seconds - Health check duration histogram
  • docs_hub_health_check_errors_total - Health check errors counter

• Node.js Metrics (default):

  • Process CPU usage, memory, event loop lag, etc.

Integration with Prometheus

The Helm chart includes a ServiceMonitor resource for automatic Prometheus discovery:

# Enable Prometheus monitoring
serviceMonitor:
  enabled: true
  interval: 30s
  scrapeTimeout: 10s

For manual Prometheus configuration, add this scrape config:

scrape_configs:
  - job_name: 'docs-hub-api'
    static_configs:
      - targets: ['docs-hub-api:3000']
    metrics_path: '/metrics'
    scrape_interval: 30s

Additional Monitoring Tools

For production deployments, consider integrating with:

• Grafana - Visualize Prometheus metrics with dashboards
• ELK Stack - Log aggregation and analysis
• Uptime monitoring - External health monitoring (UptimeRobot, Pingdom)
• Alert Manager - Incident notifications and alerting

Grafana Dashboards

The ITL Documentation Hub includes comprehensive Grafana dashboards for monitoring API performance, health metrics, and system resources.

Dashboard: ITL Documentation Hub - API Monitoring

Overview Dashboard - Complete monitoring view of the documentation hub:

The dashboard provides monitoring for:

• HTTP Status Codes - Track 200, 304, and error responses with 5-minute rate monitoring
• Documentation Sites - Monitor total and healthy registered sites
• HTTP Request Rate - Request volume by HTTP method (GET, POST, PUT, DELETE)
• Response Time Metrics - Average response times with multiple percentile tracking
• Request Patterns - Traffic analysis for key endpoints like /api/health, /api/sites, /metrics

Performance Metrics - System resource monitoring:

Resource monitoring includes:

• Memory Usage - Resident memory, heap used, and heap total tracking
• CPU Usage - User CPU %, System CPU %, and Total CPU % monitoring
• Response Time Percentiles - 50th, 95th, and 99th percentile response time analysis

Dashboard Features

• Real-time Updates - 30-second refresh interval for live monitoring
• Time Range Controls - Configurable time windows (1 hour default)
• Interactive Navigation - Direct links to Documentation Hub, Metrics Endpoint, and Monitoring Guide
• Data Source Integration - Connected to ITL Prometheus instance
• Performance Baselines - Historical trend analysis for capacity planning

Access Information

• Dashboard URL: https://grafana.dev.itlusions.nl/d/itl-docs-hub-api/itl-documentation-hub-api-monitoring
• Tags: api, docs-hub, itlusions, monitoring
• Refresh Rate: 30 seconds
• Time Zone: Europe/Amsterdam (CEST)

For additional monitoring setup and configuration, see the Monitoring Guide.

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

1. Fork and clone the repository:

   git clone https://github.com/YOUR_USERNAME/ITL.Docs.Hub.git
   cd ITL.Docs.Hub

2. Setup development environment:

   # Backend setup
   cd api
   npm install
   cp .env.example .env
   
   # Frontend setup  
   cd ..
   python -m venv venv
   source venv/bin/activate  # Windows: venv\Scripts\activate
   pip install -r requirements.txt

3. Start development services:

   # Option 1: Use Docker Compose (recommended)
   docker-compose up -d
   
   # Option 2: Manual startup
   # Terminal 1: Start API
   cd api && npm run dev
   
   # Terminal 2: Start frontend
   mkdocs serve --dev-addr=0.0.0.0:8080

Development Workflow

1. Create feature branch: git checkout -b feature/your-feature-name
2. Make your changes to frontend (docs/, mkdocs.yml) or backend (api/)
3. Test your changes:

   # Test API changes
   cd api && npm test
   
   # Test frontend changes
   mkdocs serve
   
   # Test integration
   .\test-api.ps1

4. Commit and push: Follow conventional commit messages
5. Submit pull request with clear description

Code Standards

• Backend: Follow Node.js best practices, add tests for new endpoints
• Frontend: Use Material for MkDocs conventions, ensure responsive design
• Documentation: Update README.md and API docs for any changes
• Testing: Maintain test coverage above 80%

Reporting Issues

Please use GitHub Issues with:

• Clear description of the problem
• Steps to reproduce
• Expected vs actual behavior
• Environment details (OS, Docker version, etc.)

Security

Report security vulnerabilities privately to security@itlusions.com

📝 Integration Examples

Quick Start for Documentation Sites

1. Add to your CI/CD pipeline:

   # .github/workflows/deploy.yml
   - name: Register with Docs Hub
     run: |
       TOKEN=$(curl -s -X POST $DOCS_HUB_URL/api/auth \
         -H "Content-Type: application/json" \
         -d '{"password": "${{ secrets.DOCS_HUB_PASSWORD }}"}' | \
         jq -r '.token')
       
       curl -X POST $DOCS_HUB_URL/api/sites \
         -H "Content-Type: application/json" \
         -H "Authorization: Bearer $TOKEN" \
         -d '{
           "name": "My Docs",
           "description": "My documentation site",
           "url": "${{ env.DEPLOYMENT_URL }}",
           "category": "Platform",
           "version": "${{ github.ref_name }}"
         }'

2. Add health check to your MkDocs site:

   <!-- docs/health.md -->
   # Health Check
   
   ✅ **Status**: Online  
   📄 **Version**: v1.0.0  
   🕒 **Last Updated**: 2024-01-01

3. Configure MkDocs for integration:

   # mkdocs.yml
   nav:
     - Home: index.md
     - Health: health.md
   
   extra:
     docs_hub:
       enabled: true
       url: https://docs.itlusions.com

🎯 Roadmap

✅ Completed (v1.0)

• ✅ Dual-Service Architecture - Frontend + API backend
• ✅ Site Registration API - Full CRUD operations
• ✅ Statistics Dashboard - Real-time metrics
• ✅ Authentication System - JWT-based security
• ✅ Docker Deployment - Production-ready containers
• ✅ Comprehensive Testing - 17+ automated test cases
• ✅ Health Monitoring - Service health checks

🚧 In Progress (v1.1)

• 🚧 Search Integration - Cross-site search functionality
• 🚧 Enhanced Statistics - Advanced metrics and analytics
• 🚧 API Documentation - Interactive API docs with Swagger

📋 Planned (v1.2+)

• ⏳ Notification System - Health alerts and status updates
• ⏳ Theme Customization - Organization-specific branding
• ⏳ Content Aggregation - Cross-site content indexing
• ⏳ Advanced Analytics - Usage patterns and insights
• ⏳ Multi-tenant Support - Organization-based access control

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

• 📧 Email: support@itlusions.com
• 🐛 Issues: GitHub Issues
• 📖 Documentation: docs.itlusions.com
• 💬 Discussions: GitHub Discussions

---

Made with ❤️ by the ITlusions Team

Bringing order to distributed documentation, one API call at a time. 🚀