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)

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