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

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

### Step 2: Check Existing Wiki.js Installations

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

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

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

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

**File contents:**

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

```bash
nano .env
```

**File contents:**

```bash
# Pokerole Wiki.js Environment
DB_PASSWORD=GENERATE_SECURE_PASSWORD_HERE
```

**Action:** Generate secure password:

```bash
openssl rand -base64 32
```

Copy result into .env file

### Step 8: Create Data Directories

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

### Step 9: Deploy Containers

```bash
docker-compose up -d
```

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

### Step 10: Verify Deployment

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

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

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

**File contents:**

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

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

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

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

### Step 16: Obtain SSL Certificate

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

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

# Check certificate
certbot certificates | grep pokerole
```

### Step 18: Test Auto-Renewal

```bash
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:**

```markdown
# 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:**

```markdown
# 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:**

```markdown
# [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:**

```markdown
# 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:**
```bash
nslookup pokerole.firefrostgaming.com
```

**Check Nginx:**
```bash
nginx -t
systemctl status nginx
```

**Check Docker:**
```bash
docker-compose ps
docker-compose logs pokerole-wiki
```

### Issue: SSL certificate fails

**Check DNS propagation first:**
```bash
dig pokerole.firefrostgaming.com
```

**Try manual certificate:**
```bash
certbot certonly --standalone -d pokerole.firefrostgaming.com
```

### Issue: Database connection errors

**Check database container:**
```bash
docker-compose logs pokerole-db
```

**Verify environment variables:**
```bash
cat .env
docker-compose exec pokerole-wiki env | grep DB_
```

### Issue: Can't upload images

**Check volume permissions:**
```bash
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:

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

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

---

## Post-Deployment Maintenance

### Daily Backups (Recommended)

```bash
#!/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:**
```bash
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."** 🔥❄️💙