From 20fdff26693e634a66a5216fee00ff547e1ca46f Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Feb 2026 22:59:34 +0000 Subject: [PATCH] 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 --- .../mkdocs-decommission/deployment-guide.md | 300 ++++++++++++++++++ 1 file changed, 300 insertions(+) create mode 100644 docs/tasks/mkdocs-decommission/deployment-guide.md diff --git a/docs/tasks/mkdocs-decommission/deployment-guide.md b/docs/tasks/mkdocs-decommission/deployment-guide.md new file mode 100644 index 0000000..abdd79e --- /dev/null +++ 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)