firefrost-operations-manual/docs/tasks/mkdocs-decommission/deployment-guide.md

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)

# 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)

# 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)

# 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)

# 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

# Add entry to infrastructure manifest
# Note: MkDocs decommissioned [date]
# Replaced by: Wiki.js Subscribers

Update docs/core/infrastructure-manifest.md:

## 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

# 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

# On Ghost VPS
docker ps -a | grep mkdocs
docker images | grep mkdocs

# Both should return nothing

Check 3: Files Removed

# On Ghost VPS
ls -la /opt/ | grep mkdocs

# Should return nothing

Check 4: Archive Exists

# 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)

# 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:

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)