Phase 2 Deployment Guide

Phase 2 Deployment Guide

Self-Hosted Documentation Website at docs.isutech.co.za

Last Updated: 08/11/2025 Version: 1.0 Estimated Time: 2-4 hours Difficulty: Intermediate (step-by-step guidance provided)

---

🎯 What We’re Deploying

Before Phase 2:

• Documentation in Git repository
• Team navigates markdown files in folders
• Good organization, but requires Git/file system knowledge

After Phase 2:

• Beautiful website at docs.isutech.co.za
• Searchable, mobile-friendly interface
• Auto-updates when you push to Git
• Professional appearance
• Zero ongoing cost (using your Hetzner server)

Technology: MkDocs Material (free, open source, looks like this: https://squidfunk.github.io/mkdocs-material/)

---

📋 Prerequisites Checklist

Before starting, ensure you have:

• SSH access to Hetzner server (46.224.40.5)
• Root or sudo access on the server
• Domain access (ability to add DNS record for docs.isutech.co.za)
• 30 minutes of uninterrupted time for initial setup
• Basic comfort with command line (we’ll guide you through every step)

Test your SSH access:

ssh root@46.224.40.5
# or
ssh your-username@46.224.40.5

If this works, you’re ready! ✅

---

🗺️ Deployment Overview

Phase 2 Steps:

Step 1: Server Preparation (15 min)
   ↓
Step 2: Install MkDocs Material (10 min)
   ↓
Step 3: Configure Documentation Site (20 min)
   ↓
Step 4: Set Up Web Server (Nginx) (20 min)
   ↓
Step 5: Configure Domain (docs.isutech.co.za) (15 min)
   ↓
Step 6: Set Up Auto-Updates (20 min)
   ↓
Step 7: Enable HTTPS (SSL) (15 min)
   ↓
Step 8: Test & Verify (15 min)

Total: ~2.5 hours

---

📝 Step-by-Step Instructions

Step 1: Server Preparation (15 minutes)

1.1 Connect to Your Hetzner Server

# Replace with your actual SSH credentials
ssh root@46.224.40.5

1.2 Update System Packages

# Update package lists
apt update

# Upgrade existing packages
apt upgrade -y

1.3 Install Required Dependencies

# Install Python 3, pip, and other essentials
apt install -y python3 python3-pip python3-venv git nginx certbot python3-certbot-nginx

# Verify installations
python3 --version  # Should show Python 3.x
pip3 --version     # Should show pip version
nginx -v           # Should show nginx version
git --version      # Should show git version

✅ Checkpoint: All commands should complete without errors

---

Step 2: Install MkDocs Material (10 minutes)

2.1 Create Dedicated User for Documentation (Security Best Practice)

# Create docs user
adduser --system --group --home /home/docs docs

# Create directory for documentation
mkdir -p /var/www/docs
chown docs:docs /var/www/docs

2.2 Set Up Python Virtual Environment

# Switch to docs directory
cd /var/www/docs

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Upgrade pip
pip install --upgrade pip

2.3 Install MkDocs Material

# Install MkDocs Material (includes MkDocs core)
pip install mkdocs-material

# Install additional useful plugins
pip install mkdocs-git-revision-date-localized-plugin
pip install mkdocs-minify-plugin
pip install mkdocs-redirects

# Verify installation
mkdocs --version

Expected output: mkdocs, version X.X.X

✅ Checkpoint: MkDocs Material installed successfully

---

Step 3: Configure Documentation Site (20 minutes)

3.1 Clone Your Documentation Repository

# Still in /var/www/docs
cd /var/www/docs

# Clone your mathew-goniwe repository
git clone https://github.com/gedeza/mathew-goniwe.git repo

# Change ownership
chown -R docs:docs /var/www/docs/repo

3.2 Create MkDocs Configuration

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

# Create mkdocs.yml configuration file
nano mkdocs.yml

Paste this configuration (I’ll provide the complete file in the next section):

# See mkdocs.yml file that will be created in the repo

Save and exit (Ctrl+X, then Y, then Enter)

3.3 Test Build Locally

# Activate virtual environment if not already active
source /var/www/docs/venv/bin/activate

# Build the documentation
cd /var/www/docs/repo
mkdocs build

# This creates a 'site/' folder with HTML files
ls site/  # Should show index.html and other files

✅ Checkpoint: Build completes without errors, site/ folder created

---

Step 4: Set Up Web Server (Nginx) (20 minutes)

4.1 Create Nginx Configuration

# Create nginx site configuration
nano /etc/nginx/sites-available/docs.isutech.co.za

Paste this configuration:

server {
    listen 80;
    server_name docs.isutech.co.za;

    root /var/www/docs/repo/site;
    index index.html;

    # Logging
    access_log /var/log/nginx/docs-access.log;
    error_log /var/log/nginx/docs-error.log;

    # Main location
    location / {
        try_files $uri $uri/ =404;
    }

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    # Cache static assets
    location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Save and exit (Ctrl+X, then Y, then Enter)

4.2 Enable the Site

# Create symbolic link to enable site
ln -s /etc/nginx/sites-available/docs.isutech.co.za /etc/nginx/sites-enabled/

# Test nginx configuration
nginx -t

# If test passes, reload nginx
systemctl reload nginx

# Check nginx status
systemctl status nginx

✅ Checkpoint: Nginx configuration test passes, service is running

---

Step 5: Configure Domain (docs.isutech.co.za) (15 minutes)

5.1 Add DNS Record

Go to your domain registrar (where you manage isutech.co.za DNS)

Add A Record:

• Type: A
• Name: docs (or docs.isutech)
• Value: 46.224.40.5 (your Hetzner server IP)
• TTL: 3600 (or default)

Example for common registrars:

Cloudflare:

1. Log in to Cloudflare
2. Select isutech.co.za domain
3. Go to DNS settings
4. Click “Add record”
5. Type: A, Name: docs, IPv4 address: 46.224.40.5
6. Click Save

Other registrars: Similar process - add A record pointing docs to 46.224.40.5

5.2 Test DNS Propagation

# Wait 5-10 minutes, then test (on your local machine, not server)
nslookup docs.isutech.co.za

# Or
ping docs.isutech.co.za

# Should resolve to 46.224.40.5

Note: DNS propagation can take 5 minutes to 24 hours (usually <30 minutes)

✅ Checkpoint: docs.isutech.co.za resolves to your server IP

---

Step 6: Set Up Auto-Updates (20 minutes)

We’ll set up automatic rebuilding when you push to GitHub.

6.1 Create Update Script

# Create script directory
mkdir -p /var/www/docs/scripts
cd /var/www/docs/scripts

# Create update script
nano update-docs.sh

Paste this script:

#!/bin/bash

# Documentation Auto-Update Script
# This script pulls latest changes from Git and rebuilds documentation

LOG_FILE="/var/log/docs-update.log"
REPO_DIR="/var/www/docs/repo"
VENV_DIR="/var/www/docs/venv"

echo "=== Documentation Update Started: $(date) ===" >> $LOG_FILE

# Navigate to repository
cd $REPO_DIR

# Pull latest changes
echo "Pulling latest changes from Git..." >> $LOG_FILE
git pull origin main >> $LOG_FILE 2>&1

if [ $? -eq 0 ]; then
    echo "Git pull successful" >> $LOG_FILE

    # Activate virtual environment and rebuild
    echo "Rebuilding documentation..." >> $LOG_FILE
    source $VENV_DIR/bin/activate
    mkdocs build --clean >> $LOG_FILE 2>&1

    if [ $? -eq 0 ]; then
        echo "Documentation rebuilt successfully" >> $LOG_FILE
        echo "=== Update Completed Successfully: $(date) ===" >> $LOG_FILE
        exit 0
    else
        echo "ERROR: MkDocs build failed" >> $LOG_FILE
        echo "=== Update Failed: $(date) ===" >> $LOG_FILE
        exit 1
    fi
else
    echo "ERROR: Git pull failed" >> $LOG_FILE
    echo "=== Update Failed: $(date) ===" >> $LOG_FILE
    exit 1
fi

Save and exit

# Make script executable
chmod +x /var/www/docs/scripts/update-docs.sh

# Change ownership
chown docs:docs /var/www/docs/scripts/update-docs.sh

# Test the script
/var/www/docs/scripts/update-docs.sh

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

6.2 Set Up Automatic Updates (Option A: Cron Job)

# Create cron job to check for updates every 10 minutes
crontab -e

# Add this line (choose your preferred editor if prompted)
*/10 * * * * /var/www/docs/scripts/update-docs.sh

This will check for updates every 10 minutes.

Alternative: Manual trigger - Just run the script when you want to update:

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

✅ Checkpoint: Update script runs successfully, documentation rebuilds

---

Step 7: Enable HTTPS (SSL) (15 minutes)

Secure your documentation site with free Let’s Encrypt SSL.

7.1 Obtain SSL Certificate

# Run certbot for automatic SSL setup
certbot --nginx -d docs.isutech.co.za

# Follow the prompts:
# - Enter email address (for renewal notifications)
# - Agree to terms
# - Choose whether to redirect HTTP to HTTPS (recommended: Yes)

Certbot will automatically:

• Obtain SSL certificate
• Update nginx configuration
• Set up auto-renewal

7.2 Test SSL

# Test SSL certificate
certbot certificates

# Test auto-renewal
certbot renew --dry-run

If dry-run succeeds, auto-renewal is configured! ✅

7.3 Access Your Site

Open browser and visit:

https://docs.isutech.co.za

You should see your beautiful documentation website! 🎉

✅ Checkpoint: Site loads with valid HTTPS certificate

---

Step 8: Test & Verify (15 minutes)

8.1 Functionality Tests

Test navigation:

• Homepage loads
• Can navigate to different sections
• Search works (type in search box)
• Mobile view works (resize browser)

Test content:

• Master Index displays correctly
• Marketing templates accessible
• Business Development section works
• All links work (no 404 errors)

8.2 Test Auto-Update

# On your local machine, make a small change to a doc
# For example, edit docs/00-INDEX/MASTER_INDEX.md
# Add a line: "Last verified: [today's date]"

git add docs/
git commit -m "Test auto-update functionality"
git push origin main

# Wait 10 minutes (or run update script manually on server)
# Then refresh https://docs.isutech.co.za

# Your change should appear!

✅ Checkpoint: Changes from Git appear on website

---

🎉 Deployment Complete!

You Now Have:

✅ Professional documentation website at https://docs.isutech.co.za ✅ Automatic updates every 10 minutes from Git ✅ Secure HTTPS with auto-renewing certificate ✅ Fast, searchable interface ✅ Mobile-friendly design ✅ Zero ongoing cost (using existing server)

---

🔐 Access Control (Optional - Phase 2b)

If you want to restrict access to certain sections:

Option 1: Basic Auth (Simple Password Protection)

# Install apache2-utils
apt install apache2-utils

# Create password file
htpasswd -c /etc/nginx/.htpasswd isutech

# Enter password when prompted

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

# Add auth to specific location:
location /business-development/ {
    auth_basic "Restricted Access";
    auth_basic_user_file /etc/nginx/.htpasswd;
    try_files $uri $uri/ =404;
}

# Reload nginx
nginx -t && systemctl reload nginx

Option 2: IP Whitelist (Office/VPN Only)

# In nginx config, add:
location /business-development/ {
    allow 102.x.x.x;  # Your office IP
    allow 10.0.0.0/8;  # Private network
    deny all;
    try_files $uri $uri/ =404;
}

---

📊 Monitoring & Maintenance

Daily/Weekly (Automatic)

• ✅ SSL renewal: Automatic (certbot)
• ✅ Documentation updates: Automatic (every 10 min via cron)
• ✅ Server updates: Monthly (set reminder)

Monthly Tasks (5 minutes)

# SSH to server
ssh root@46.224.40.5

# Update system packages
apt update && apt upgrade -y

# Check disk space
df -h

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

# Update MkDocs Material (optional, if new version available)
source /var/www/docs/venv/bin/activate
pip install --upgrade mkdocs-material

Monitoring Checklist

• Site loads properly (https://docs.isutech.co.za)
• SSL certificate valid (check browser padlock)
• Auto-updates working (check log: /var/log/docs-update.log)
• No errors in nginx logs
• Server disk space >20% free

---

🆘 Troubleshooting

Issue: Site Not Loading

Check nginx status:

systemctl status nginx
nginx -t  # Test configuration

Check logs:

tail -n 50 /var/log/nginx/docs-error.log

Restart nginx:

systemctl restart nginx

---

Issue: Documentation Not Updating

Check update log:

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

Manually trigger update:

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

Check Git status:

cd /var/www/docs/repo
git status
git log -n 5  # See recent commits

---

Issue: SSL Certificate Problems

Check certificate:

certbot certificates

Renew manually:

certbot renew

Check certificate expiry:

openssl s_client -connect docs.isutech.co.za:443 -servername docs.isutech.co.za < /dev/null 2>/dev/null | openssl x509 -noout -dates

---

Issue: Slow Performance

Enable gzip compression in nginx:

# Add to /etc/nginx/sites-available/docs.isutech.co.za

gzip on;
gzip_vary on;
gzip_types text/plain text/css text/xml text/javascript application/json application/javascript application/xml+rss;

Restart nginx:

systemctl restart nginx

---

📞 Support & Resources

Official Documentation

• MkDocs Material: https://squidfunk.github.io/mkdocs-material/
• MkDocs: https://www.mkdocs.org/
• Nginx: https://nginx.org/en/docs/

Quick Commands Reference

# Rebuild documentation manually
cd /var/www/docs/repo && source /var/www/docs/venv/bin/activate && mkdocs build --clean

# Update documentation from Git
/var/www/docs/scripts/update-docs.sh

# Check nginx status
systemctl status nginx

# View update logs
tail -f /var/log/docs-update.log

# View nginx error logs
tail -f /var/log/nginx/docs-error.log

# Renew SSL certificate
certbot renew

---

✅ Post-Deployment Checklist

After completing deployment:

• Site accessible at https://docs.isutech.co.za
• HTTPS working (green padlock in browser)
• Search functionality working
• Mobile view working
• Auto-updates configured and tested
• Team informed of new URL
• Bookmarks updated (if applicable)
• Old documentation access method retired (if applicable)

---

🎓 Training Your Team

Share This With Your Team:

New Documentation Access:

• Old way: Navigate folders in Git
• New way: Visit https://docs.isutech.co.za

Making Updates:

• Process unchanged: Edit markdown → Git push
• Bonus: Changes appear on website automatically (within 10 minutes)

No new skills needed!

• Non-technical users: Just browse the website
• Technical users: Same Git workflow as before

---

🎉 Congratulations!

You’ve successfully deployed a professional, self-hosted documentation system at:

https://docs.isutech.co.za

What you’ve achieved:

• ✅ Enterprise-grade documentation platform
• ✅ Beautiful, searchable interface
• ✅ Automatic updates from Git
• ✅ Secure HTTPS
• ✅ Mobile-friendly
• ✅ Zero ongoing costs

Total monthly cost: R0 (using existing server) Saved vs. Notion/Confluence: R600-1,000/month = R7,200-12,000/year

---

Phase 2 Deployment Guide - iSu Technologies Need help? Check troubleshooting section or contact technical lead Last Updated: 08/11/2025