firefrost-operations-manual/docs/tasks/pokerole-wikijs-deployment/deployment-plan.md

Pokerole Wiki.js Deployment Plan

Task: Deploy fresh Wiki.js instance for Aurelian Pokédex
Server: Ghost VPS (64.50.188.14)
Domain: pokerole.firefrostgaming.com
Estimated Time: 2-3 hours

---

Phase 1: Pre-Deployment Setup (15 minutes)

Step 1: Create Deployment Directory

ssh root@64.50.188.14
cd /opt
mkdir -p pokerole-wiki
cd pokerole-wiki

Step 2: Check Existing Wiki.js Installations

# Reference existing setups
ls -la /opt/ | grep wiki
docker ps | grep wiki

Purpose: Understand existing Wiki.js deployment pattern to replicate

Step 3: Verify Prerequisites

# Check Docker
docker --version

# Check Docker Compose
docker-compose --version

# Check available disk space
df -h /opt

# Check network ports
netstat -tulpn | grep :300

Expected: Docker/Compose installed, sufficient space (500MB+), ports available

---

Phase 2: DNS Configuration (5 minutes)

Step 4: Create DNS A Record

Action: Add DNS record (via registrar/DNS provider)

Type: A
Name: pokerole
Value: 64.50.188.14
TTL: 300 (5 minutes)

Step 5: Verify DNS Propagation

# Check DNS resolution
nslookup pokerole.firefrostgaming.com

# Alternative check
dig pokerole.firefrostgaming.com

Note: May take 5-15 minutes to propagate. Can proceed with IP testing while waiting.

---

Phase 3: Docker Deployment (30 minutes)

Step 6: Create docker-compose.yml

cd /opt/pokerole-wiki
nano docker-compose.yml

File contents:

version: "3"
services:
  pokerole-db:
    image: postgres:15-alpine
    container_name: pokerole-wiki-db
    environment:
      POSTGRES_DB: pokerole_wiki
      POSTGRES_USER: pokerole_user
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    restart: unless-stopped
    networks:
      - pokerole-network

  pokerole-wiki:
    image: ghcr.io/requarks/wiki:2
    container_name: pokerole-wiki
    depends_on:
      - pokerole-db
    environment:
      DB_TYPE: postgres
      DB_HOST: pokerole-db
      DB_PORT: 5432
      DB_USER: pokerole_user
      DB_PASS: ${DB_PASSWORD}
      DB_NAME: pokerole_wiki
    ports:
      - "3002:3000"
    volumes:
      - ./data/wiki:/wiki/data
      - ./data/content:/wiki/data/content
    restart: unless-stopped
    networks:
      - pokerole-network

networks:
  pokerole-network:
    driver: bridge

volumes:
  postgres-data:
  wiki-data:

Port 3002 - Different from existing wikis (likely 3000, 3001)

Step 7: Create Environment File

nano .env

File contents:

# Pokerole Wiki.js Environment
DB_PASSWORD=GENERATE_SECURE_PASSWORD_HERE

Action: Generate secure password:

openssl rand -base64 32

Copy result into .env file

Step 8: Create Data Directories

mkdir -p data/postgres
mkdir -p data/wiki
mkdir -p data/content
chmod -R 755 data/

Step 9: Deploy Containers

docker-compose up -d

Expected output: Two containers created (pokerole-db, pokerole-wiki)

Step 10: Verify Deployment

# Check container status
docker-compose ps

# Check logs
docker-compose logs -f pokerole-wiki

# Check database connection
docker-compose logs pokerole-db | grep "ready to accept"

Expected: Both containers running, no error messages, database accepting connections

Step 11: Test Local Access

# From Ghost VPS
curl http://localhost:3002

# Should return HTML (Wiki.js interface)

---

Phase 4: Nginx Reverse Proxy (30 minutes)

Step 12: Create Nginx Config

nano /etc/nginx/sites-available/pokerole.firefrostgaming.com

File contents:

server {
    listen 80;
    listen [::]:80;
    server_name pokerole.firefrostgaming.com;

    # Redirect to HTTPS (after SSL setup)
    # return 301 https://$server_name$request_uri;

    # Temporary HTTP access for testing
    location / {
        proxy_pass http://localhost:3002;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Step 13: Enable Site

# Create symlink
ln -s /etc/nginx/sites-available/pokerole.firefrostgaming.com /etc/nginx/sites-enabled/

# Test Nginx config
nginx -t

# Reload Nginx
systemctl reload nginx

Step 14: Test HTTP Access

# From local machine (or curl)
curl http://pokerole.firefrostgaming.com

Expected: Wiki.js welcome/setup page

---

Phase 5: SSL Certificate (30 minutes)

Step 15: Install Certbot (if not present)

apt update
apt install certbot python3-certbot-nginx -y

Step 16: Obtain SSL Certificate

certbot --nginx -d pokerole.firefrostgaming.com

Prompts:

• Email: (Michael's email)
• Terms: Agree
• Newsletter: Optional
• Redirect: Yes (automatically configure HTTPS redirect)

Step 17: Verify SSL

# Test HTTPS access
curl https://pokerole.firefrostgaming.com

# Check certificate
certbot certificates | grep pokerole

Step 18: Test Auto-Renewal

certbot renew --dry-run

Expected: Renewal process works (actual renewal happens automatically)

---

Phase 6: Wiki.js Configuration (30 minutes)

Step 19: Access Wiki.js Setup

Browser: Navigate to https://pokerole.firefrostgaming.com

Expected: Wiki.js initial setup wizard

Step 20: Complete Setup Wizard

Administrator Account:

• Email: (Michael's email)
• Username: mkrause612
• Password: (Secure password - store in Vaultwarden)

Site Configuration:

• Site Title: "Aurelian Pokédex"
• Site Description: "Complete Pokédex for the Aurelian Region - Pokerole TTRPG"
• Company/Organization: "Firefrost Gaming"

Telemetry: Disable (privacy)

Step 21: Configure Authentication

Navigation: Administration → Authentication

Enable:

• Local authentication (for Michael & Holly)

Disable:

• Social logins (unless needed)

Step 22: Create Holly's Account

Navigation: Administration → Users

Add User:

• Email: (Holly's email)
• Username: Unicorn20089 (or Holly's preference)
• Role: Editor (full editing rights)
• Group: Editors

Step 23: Configure Permissions

Navigation: Administration → Groups

Editors group:

• Read: All pages
• Write: All pages
• Upload: Images/files
• Manage: Own pages

Guest group (public):

• Read: All pages (after public launch)
• Write: None
• Upload: None

Step 24: Configure Theme & Appearance

Navigation: Administration → Theme

Recommended Settings:

• Theme: Default (or Dark if preferred)
• Code Injection: None initially
• Logo: Upload Firefrost Gaming logo (optional)

Step 25: Enable Markdown Editor

Navigation: Administration → Editors

Enable:

• Markdown editor (primary)

Disable:

• Visual editor (optional, can enable if preferred)

Step 26: Configure Storage

Navigation: Administration → Storage

Verify:

• Local storage enabled for uploads
• Path: /wiki/data/content (from docker volume)

---

Phase 7: Initial Structure Setup (Optional, 15 minutes)

Step 27: Create Home Page

Content:

# Aurelian Pokédex

Welcome to the complete Pokédex for the Aurelian Region!

## Quick Navigation

- [Tier 3 Pokémon](/tier3)
- [Tier 4 Pokémon](/tier4)
- [Tier 5 Regional Forms](/tier5)

## About This Pokédex

This Pokédex documents all Pokémon native to the Aurelian region for the Pokerole Tabletop RPG system.

### Statistics

- **Total Pokémon:** 76 unique entries
- **Regional Forms:** 19 Aurelian variants
- **Custom Abilities:** 19 unique abilities
- **Custom Moves:** 2 signature moves

### Tiers

- **Tier 3:** Rookie-tier Pokémon (26 entries)
- **Tier 4:** Advanced-tier Pokémon (31 entries)
- **Tier 5:** Regional variants of existing Pokémon (19 entries)

---

*This Pokédex is maintained by Firefrost Gaming for the Pokerole TTRPG community.*

Step 28: Create Tier Index Pages

Create 3 pages:

1. /tier3 - Tier 3 index
2. /tier4 - Tier 4 index
3. /tier5 - Tier 5 Regional Forms index

Template for each:

# Tier [X] Pokémon

[Description of tier]

## Pokémon List

[Claudius will populate during migration]

---

*Navigation:* [Home](/) | [Tier 3](/tier3) | [Tier 4](/tier4) | [Tier 5](/tier5)

Step 29: Create Pokémon Entry Template

Purpose: Give Claudius a consistent format for migration

Create page: /template/pokemon-entry

Content:

# [Pokémon Name] (#[Dex Number])

![Sprite](/images/[filename]-normal.png) ![Shiny](/images/[filename]-shiny.png)

## Basic Information

| Attribute | Value |
|-----------|-------|
| **Type** | [Type1] / [Type2] |
| **Rank** | [Rank] |
| **Evolution** | [Evolution line] |

## Stats

| HP | Str | Dex | Vit | Spe | Ins | Total |
|----|-----|-----|-----|-----|-----|-------|
| X  | X   | X   | X   | X   | X   | XX    |

## Abilities

- **Ability 1:** [Name] - [Description]
- **Ability 2:** [Name] - [Description]
- **Hidden Ability:** [Name] - [Description]

## Pokédex Entry

"[Flavor text]"

## Move Pool

[Table with moves by rank]

## Evolution

[Evolution method and line]

---

*Navigation:* [Home](/) | [Tier Index](/tier[X])

---

Phase 8: Handoff to Migration Team (5 minutes)

Step 30: Create Access Document

Create file: /opt/pokerole-wiki/ACCESS.md

Contents:

# Pokerole Wiki.js Access Information

**URL:** https://pokerole.firefrostgaming.com

## Admin Account
- **Username:** mkrause612
- **Password:** [In Vaultwarden: Pokerole Wiki Admin]

## Editor Account (Holly)
- **Username:** Unicorn20089
- **Password:** [Provided to Holly separately]

## Technical Details
- **Server:** Ghost VPS (64.50.188.14)
- **Port:** 3002 (internal)
- **Database:** PostgreSQL (pokerole-wiki-db container)
- **Data:** /opt/pokerole-wiki/data/

## Backup Locations
- **Database:** /opt/pokerole-wiki/data/postgres/
- **Uploads:** /opt/pokerole-wiki/data/content/
- **Config:** /opt/pokerole-wiki/docker-compose.yml

## Useful Commands

# View logs
cd /opt/pokerole-wiki
docker-compose logs -f pokerole-wiki

# Restart wiki
docker-compose restart pokerole-wiki

# Full restart (if needed)
docker-compose down && docker-compose up -d

# Backup database
docker exec pokerole-wiki-db pg_dump -U pokerole_user pokerole_wiki > backup.sql

Step 31: Notify Michael & Claudius

Message template:

🎉 Pokerole Wiki.js Deployment COMPLETE!

✅ URL: https://pokerole.firefrostgaming.com
✅ Admin account created
✅ SSL certificate active
✅ Holly's editor account created
✅ Basic structure template ready

📋 Access details: /opt/pokerole-wiki/ACCESS.md
📋 Admin password: (in Vaultwarden)

🚀 Ready for content migration!

Next steps:
1. Michael: Log in and verify access
2. Claudius: Begin Tier 3 migration (26 Pokémon)
3. Upload sprites to /images/
4. Link evolution chains

The chronicle awaits! 💙🔥❄️

---

Phase 9: Verification Checklist

Deployment Verification

• Wiki accessible at https://pokerole.firefrostgaming.com
• SSL certificate valid (green lock)
• Admin account works (can log in)
• Holly's account created and works
• Markdown editor functional
• Can create new pages
• Can upload images
• Tables render correctly
• Search functionality works
• No errors in docker logs

Security Verification

• HTTP redirects to HTTPS
• Strong passwords set
• Public access read-only
• Database password secured
• Certbot auto-renewal configured

Handoff Verification

• Access document created
• Credentials stored in Vaultwarden
• Michael notified
• Claudius ready to begin migration
• Holly has access credentials

---

Troubleshooting Guide

Issue: Can't access wiki via domain

Check DNS:

nslookup pokerole.firefrostgaming.com

Check Nginx:

nginx -t
systemctl status nginx

Check Docker:

docker-compose ps
docker-compose logs pokerole-wiki

Issue: SSL certificate fails

Check DNS propagation first:

dig pokerole.firefrostgaming.com

Try manual certificate:

certbot certonly --standalone -d pokerole.firefrostgaming.com

Issue: Database connection errors

Check database container:

docker-compose logs pokerole-db

Verify environment variables:

cat .env
docker-compose exec pokerole-wiki env | grep DB_

Issue: Can't upload images

Check volume permissions:

ls -la /opt/pokerole-wiki/data/content/
chmod -R 755 /opt/pokerole-wiki/data/content/

Check storage config in Wiki.js admin panel

---

Rollback Procedure (If Needed)

If deployment fails catastrophically:

cd /opt/pokerole-wiki
docker-compose down
rm -rf data/  # CAREFUL - only if starting fresh
# Remove Nginx config
rm /etc/nginx/sites-enabled/pokerole.firefrostgaming.com
systemctl reload nginx
# Revoke SSL cert (optional)
certbot revoke --cert-name pokerole.firefrostgaming.com

Restore from backup (if re-deploying):

# Database restore
docker exec -i pokerole-wiki-db psql -U pokerole_user pokerole_wiki < backup.sql

---

Post-Deployment Maintenance

Daily Backups (Recommended)

#!/bin/bash
# /opt/pokerole-wiki/backup.sh

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR=/opt/pokerole-wiki/backups

# Create backup directory
mkdir -p $BACKUP_DIR

# Backup database
docker exec pokerole-wiki-db pg_dump -U pokerole_user pokerole_wiki > $BACKUP_DIR/pokerole_db_$DATE.sql

# Backup uploads
tar -czf $BACKUP_DIR/pokerole_content_$DATE.tar.gz /opt/pokerole-wiki/data/content/

# Keep only last 7 days
find $BACKUP_DIR -name "pokerole_*" -mtime +7 -delete

echo "Backup complete: $DATE"

Schedule with cron:

crontab -e
# Add: 0 3 * * * /opt/pokerole-wiki/backup.sh

Monitoring

Add to Uptime Kuma:

• URL: https://pokerole.firefrostgaming.com
• Check interval: 5 minutes
• Alert on downtime

---

Success Criteria

✅ Deployment Complete:

• Wiki accessible via HTTPS
• Admin account functional
• SSL certificate valid
• Database operational
• No errors in logs

✅ Migration Ready:

• Michael can create pages
• Holly can edit pages
• Images can be uploaded
• Markdown renders correctly
• Search works

✅ Production Ready (After Migration):

• 76 Pokémon entries published
• 225 sprites uploaded
• Evolution chains linked
• Custom mechanics documented
• Public access enabled

---

Estimated Total Time: 2-3 hours

Expected Completion: Evening of February 26, 2026

Next Phase: Content migration begins February 27, 2026

---

💙🔥❄️ "The infrastructure is forged. The chronicle awaits." 🔥❄️💙