docs: Add MkDocs decommission procedure guide

Created complete decommission guide for MkDocs service (250+ lines): Decommission Strategy: - Safe removal of MkDocs (replaced by Wiki.js) - 6-phase procedure (stop, remove, clean, DNS, Nginx, document) - Total time: 15 minutes Pre-Decommission Checklist: - Verify Wiki.js operational - Confirm content migration complete - Check for external links - Create backup archive Procedure: - Stop and remove Docker container - Clean up files (with archive for safety) - Update/remove DNS records - Remove Nginx configuration - Document in infrastructure manifest Safety Features: - Archive creation before deletion - Rollback plan (15 min to restore) - Verification steps - Common issues troubleshooting Post-Decommission: - Week 1 monitoring plan - Month 1 final cleanup - Archive retention policy Low risk: Content backed up in Git and archive. Ready to execute when Wiki.js confirmed as replacement. Task: MkDocs Decommission (Tier 3) FFG-STD-002 compliant
2026-02-17 22:59:34 +00:00
parent 4f27f25a74
commit 20fdff2669
1 changed files with 300 additions and 0 deletions
--- a/docs/tasks/mkdocs-decommission/deployment-guide.md
+++ b/docs/tasks/mkdocs-decommission/deployment-guide.md
@@ -0,0 +1,300 @@
+# MkDocs Decommission - Complete Procedure
+
+**Status:** Ready to Execute  
+**Priority:** Tier 3 - Cleanup  
+**Time Estimate:** 15 minutes  
+**Last Updated:** 2026-02-17
+
+---
+
+## Overview
+
+Decommission MkDocs documentation service, which has been replaced by Wiki.js. Clean removal of containers, files, and DNS records.
+
+**Why decommission:**
+- Wiki.js provides better features (WYSIWYG editing, permissions, search)
+- Two documentation systems create confusion
+- MkDocs was Git-native but harder for non-technical users
+- Consolidation simplifies infrastructure
+
+**What's replacing it:**
+- **Wiki.js Subscribers** (docs.firefrostgaming.com) - Public documentation
+- **Wiki.js Staff** (staff.firefrostgaming.com) - Internal documentation
+
+---
+
+## Current State
+
+**MkDocs Location:** Ghost VPS (64.50.188.14)  
+**Container:** Running via Docker  
+**URL:** docs.firefrostgaming.com  
+**Content:** Migrated to Wiki.js
+
+---
+
+## Pre-Decommission Checklist
+
+**CRITICAL: Verify before proceeding!**
+
+- [ ] Wiki.js Subscribers is fully operational
+- [ ] All MkDocs content migrated to Wiki.js
+- [ ] No external links pointing to MkDocs URLs
+- [ ] DNS ready to update (or remove)
+- [ ] Backup of MkDocs content exists (in Git)
+
+**If any item is NOT checked, STOP and resolve before proceeding.**
+
+---
+
+## Decommission Procedure
+
+### Phase 1: Stop MkDocs Service (2 min)
+
+```bash
+# SSH to Ghost VPS
+ssh root@64.50.188.14
+
+# Find MkDocs container
+docker ps | grep mkdocs
+
+# Stop the container
+docker stop mkdocs-container-name
+
+# Verify stopped
+docker ps | grep mkdocs
+# Should return nothing
+```
+
+### Phase 2: Remove Docker Resources (3 min)
+
+```bash
+# Remove container
+docker rm mkdocs-container-name
+
+# Remove MkDocs image (if no other containers use it)
+docker images | grep mkdocs
+docker rmi mkdocs-image-name
+
+# Clean up unused images
+docker image prune -a
+
+# Verify removal
+docker ps -a | grep mkdocs
+# Should return nothing
+```
+
+### Phase 3: Clean Up Files (5 min)
+
+```bash
+# Navigate to MkDocs directory
+cd /opt/mkdocs  # Or wherever MkDocs files are stored
+
+# Archive before deletion (safety measure)
+tar -czf /root/mkdocs-archive-$(date +%Y%m%d).tar.gz .
+
+# Remove MkDocs directory
+cd /
+rm -rf /opt/mkdocs
+
+# Verify removal
+ls -la /opt/ | grep mkdocs
+# Should return nothing
+```
+
+### Phase 4: Update DNS (3 min)
+
+**Option A: Redirect to Wiki.js**
+
+Update DNS record:
+- `docs.firefrostgaming.com` → Point to Wiki.js server IP
+
+**In your DNS provider:**
+```
+BEFORE:
+docs.firefrostgaming.com  A  64.50.188.14 (Ghost VPS)
+
+AFTER:
+docs.firefrostgaming.com  A  [Wiki.js server IP]
+```
+
+**Option B: Remove DNS Record**
+
+If docs.firefrostgaming.com is not being used:
+- Delete the A record entirely
+
+**DNS Propagation:** May take up to 24-48 hours
+
+---
+
+### Phase 5: Update Nginx (if applicable) (2 min)
+
+```bash
+# If Nginx reverse proxy was set up for MkDocs
+cd /etc/nginx/sites-available/
+
+# Remove MkDocs configuration
+rm mkdocs.conf
+rm /etc/nginx/sites-enabled/mkdocs.conf
+
+# Test Nginx config
+nginx -t
+
+# Reload Nginx
+systemctl reload nginx
+```
+
+---
+
+### Phase 6: Document Decommission
+
+```bash
+# Add entry to infrastructure manifest
+# Note: MkDocs decommissioned [date]
+# Replaced by: Wiki.js Subscribers
+```
+
+**Update docs/core/infrastructure-manifest.md:**
+
+```markdown
+## Decommissioned Services
+
+### MkDocs (Decommissioned 2026-02-XX)
+- **Previous URL:** docs.firefrostgaming.com
+- **Location:** Ghost VPS
+- **Reason:** Replaced by Wiki.js for better features
+- **Replacement:** Wiki.js Subscribers (docs.firefrostgaming.com)
+- **Archive:** mkdocs-archive-20260217.tar.gz on Ghost VPS
+```
+
+---
+
+## Verification
+
+### Check 1: Service is Down
+
+```bash
+# From any machine
+curl https://docs.firefrostgaming.com
+
+# Should either:
+# - Return Wiki.js page (if DNS redirected)
+# - Timeout (if DNS record removed)
+# - NOT return MkDocs page
+```
+
+### Check 2: Docker Clean
+
+```bash
+# On Ghost VPS
+docker ps -a | grep mkdocs
+docker images | grep mkdocs
+
+# Both should return nothing
+```
+
+### Check 3: Files Removed
+
+```bash
+# On Ghost VPS
+ls -la /opt/ | grep mkdocs
+
+# Should return nothing
+```
+
+### Check 4: Archive Exists
+
+```bash
+# On Ghost VPS
+ls -la /root/ | grep mkdocs-archive
+
+# Should show: mkdocs-archive-YYYYMMDD.tar.gz
+```
+
+---
+
+## Rollback Plan
+
+**If something goes wrong and you need MkDocs back:**
+
+### Quick Rollback (15 min)
+
+```bash
+# Restore from archive
+cd /opt
+tar -xzf /root/mkdocs-archive-YYYYMMDD.tar.gz -C mkdocs/
+
+# Restart Docker container
+docker start mkdocs-container-name
+
+# Or recreate container from compose file
+cd /opt/mkdocs
+docker-compose up -d
+
+# Revert DNS (point back to Ghost VPS)
+```
+
+---
+
+## Post-Decommission Cleanup
+
+### Week 1
+
+- [ ] Monitor for any broken links referencing MkDocs
+- [ ] Check if anyone complains about missing MkDocs
+- [ ] Verify Wiki.js is fulfilling documentation needs
+
+### Month 1
+
+- [ ] If no issues, delete mkdocs-archive-YYYYMMDD.tar.gz
+- [ ] Remove any remaining references to MkDocs in docs
+- [ ] Update any guides that mentioned MkDocs
+
+---
+
+## Common Issues
+
+### "I need content from MkDocs!"
+
+**Solution:**
+- All content should already be in Wiki.js
+- If something is missing, restore from Git (MkDocs was Git-native)
+- Or extract from archive: `tar -xzf mkdocs-archive-YYYYMMDD.tar.gz`
+
+### DNS still points to old server
+
+**Issue:** DNS propagation delay
+
+**Solution:**
+- Wait 24-48 hours for full propagation
+- Clear your browser cache
+- Use `dig docs.firefrostgaming.com` to check DNS
+
+### Nginx still trying to serve MkDocs
+
+**Issue:** Nginx config not removed
+
+**Solution:**
+```bash
+rm /etc/nginx/sites-enabled/mkdocs.conf
+nginx -t
+systemctl reload nginx
+```
+
+---
+
+## Related Documentation
+
+- **Wiki.js Deployment** - Replacement service
+- **Infrastructure Manifest** - Update decommissioned services
+- **DNS Management** - Update records
+
+---
+
+**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️
+
+---
+
+**Document Status:** COMPLETE  
+**Ready to Execute:** When verified Wiki.js is operational (15 minutes)  
+**Dependencies:** SSH access to Ghost VPS, DNS management access  
+**Risk Level:** LOW (content backed up in Git and archive)