Comprehensive Deployment Documentation

This document provides a complete overview of the deployment architecture, processes, and environments for the Missbrauch Kath Info Wiki MediaWiki instance.

Table of Contents

  1. System Architecture & Pipeline
  2. Workflows
  3. Infrastructure Components
  4. Security and Access
  5. Troubleshooting
  6. Command Reference

System Architecture & Pipeline

The MediaWiki instance follows a containerized microservices architecture with a clear separation between development, staging, and production environments. The pipeline ensures code quality through staging verification before reaching production, while data can be synchronized back from production to staging for realistic testing.

graph TB
    subgraph "Workstations"
        Dev[👨‍💻 Developer]
    end

    subgraph "Version Control"
        GitHub[📂 GitHub Repository]
    end

    subgraph "Environments"
        subgraph "Development – Local"
            DevEnv[🛠️ Dev Container<br/>Live Reload]
        end

        subgraph "Staging – Server"
            StagingEnv[🧪 Staging Container]
            StagingDB[🗄️ Staging DB]
        end

        subgraph "Production – Server"
            ProdEnv[🚀 Production Container]
            ProdDB[🗄️ Production DB]
            Backup[💾 Backups]
        end
    end

    %% Development Flow
    Dev -->|Code & Test| DevEnv
    Dev -->|Commit & Push| GitHub

    %% Deployment Flow
    GitHub -->|Deploy| StagingEnv
    StagingEnv -->|Validate| ProdEnv

    %% Data Flow
    ProdEnv -->|Read / Write| ProdDB
    ProdDB -->|Backup| Backup
    ProdDB -.->|Sync Data| StagingDB
    StagingEnv -->|Read / Write| StagingDB

    %% Access
    User[👤 End Users] --> ProdEnv
    Dev -->|SSH / Maintenance| ProdEnv

    style DevEnv fill:#e3f2fd
    style StagingEnv fill:#fff3e0
    style ProdEnv fill:#e8f5e8

Environment Summary

Environment Port Purpose Docker Compose Database
Development 8080 Local dev & testing docker-compose.dev.yml db_data (vol)
Staging 8081 Pre-prod testing docker-compose.prod.yml staging_db_data
Production 8080 Live research docker-compose.prod.yml db_data

Workflows

Development Workflow

  1. Setup: Clone the repo and configure .env.
  2. Run: Start the environment with live reload. See Start Development Environment.
  3. Iterate: Make changes, test locally. Logs are available via View Logs.
  4. Update: If schema changes are needed, run Update Schema.

Staging & Testing

Staging mirrors production. Before deploying new features:

  1. Sync Data: Pull fresh data from production to staging using Sync Prod to Staging.
  2. Deploy Code: Update the staging container with the new image.
  3. Test: Verify functionality on port 8081.

Production Deployment

  1. Build: Create the Docker image locally. See Build Image.
  2. Transfer: Move the image to the production server.
  3. Deploy: Load the image and restart services. See Deploy to Production.
  4. Post-Deploy: Run maintenance scripts. See Post-Deployment Tasks.

Infrastructure Components

The system is built on a custom Dockerfile (Dockerfile) extending MediaWiki 1.43.1.

  • Web Services: MediaWiki (Prod/Staging), phpMyAdmin, Caddy File Server.
  • Database: MariaDB 11.
  • Storage: Local volumes for DB data and images; Shared storage for cluster work.

See the Dockerfile for details.

Security and Access

  • Network: Access via Jump Server + SSH Key.
  • Application: MediaWiki auth, Admin access control.
  • Data: Encrypted connections, regular backups.

Troubleshooting

Common issues (Service Down, DB Error, Storage Full) can be diagnosed by checking logs and resources.

Command Reference

Development Commands

Start Environment

docker-compose -f docker-compose.dev.yml up -d --build

View Logs

docker-compose -f docker-compose.dev.yml logs -f

Operations Commands (Prod/Staging)

Build Image (Local)

docker build -f Dockerfile -t mediawiki:latest .
docker image save mediawiki -o mediawiki_image.tar

Deploy to Production

# Transfer (replace user/host)
rsync -av -e "ssh -J user@jump-server" ./mediawiki_image.tar user@prod-server:/path/

# Load & Restart
docker load < mediawiki_image.tar
docker-compose -f docker-compose.prod.yml up -d

Sync Prod to Staging

./src/maintenance/sync_prod_to_staging.sh

Post-Deployment Tasks

docker exec mediawiki php maintenance/update.php --quick
docker exec mediawiki php maintenance/runJobs.php --maxjobs=1000

Database Management

Backup & Restore

# Backup
./src/maintenance/backup_db.sh

# Restore
./src/maintenance/restore_db.sh backups/prod_backup_YYYY-MM-DD.sql

Maintenance

# Update Schema
docker-compose -f docker-compose.dev.yml exec mediawiki php maintenance/update.php --quick

# Run Jobs
docker-compose -f docker-compose.dev.yml exec mediawiki php maintenance/runJobs.php --maxjobs=1000

Troubleshooting Commands

Service Status

docker-compose -f docker-compose.prod.yml ps
docker ps -a

View Detailed Logs

docker logs mediawiki --tail 100
docker logs db --tail 100

Restart Services

docker-compose -f docker-compose.prod.yml restart

Check Connectivity

docker exec -it db mariadb -u wikiuser -p -e "SHOW DATABASES;"

Cleanup

docker system prune -f
docker volume prune -f

Server Information

  • Server: server.domain.ltdh
  • Jump Server: jump-server.domain.ltd
  • Web Access: http://server.domain.ltdh:8080

Template and Form Import Procedures

⚠️ Note: Import XML files into Semantic MediaWiki with Cargo and PageForms.

Recreate Data

php maintenance/runJobs.php
php extensions/Cargo/maintenance/recreateData.php --table Faelle
php extensions/Cargo/maintenance/recreateData.php --table Betroffene
php extensions/Cargo/maintenance/recreateData.php --table Beschuldigte
php extensions/Cargo/maintenance/recreateData.php --table Kirchliche_Institutionen
php extensions/Cargo/maintenance/recreateData.php --table Strafverfolgungsbehoerden
php extensions/Cargo/maintenance/recreateData.php --table Fachgremien
Back to top