🚀 MediaWiki Migration Tools

🏠 Back to Overview

Complete Azure DevOps to MediaWiki Migration Guide

This guide walks you through the entire process of migrating your Azure DevOps wiki to MediaWiki, from initial planning to final validation.

Guide Details

Estimated Time: 2-8 hours (depending on wiki size and complexity)
Difficulty: Intermediate
Prerequisites: Basic command line knowledge, admin access to both systems

📋 Phase 1: Pre-Migration Planning (30-60 minutes)

Step 1.1: Set Up Your Migration Environment

  1. Clone the migration tools repository:
    git clone https://github.com/development-toolbox/development-toolbox-mediawiki-tools.git
    cd development-toolbox-mediawiki-tools
  2. Set up Python environment:
    # Install dependencies
    cd migration
    pip install -r requirements.txt
  3. Configure your environment:
    # Copy environment template
    cp .env.template .env

    # Edit .env with your credentials
    notepad .env # Windows
    nano .env # Linux/Mac
  4. Required credentials:
    • Azure DevOps PAT: Go to Azure DevOps → Settings → Personal Access Tokens → New Token. Scopes needed: Wiki (Read)
    • MediaWiki credentials: Admin user with page creation permissions

Step 1.2: Analyze Your Current Wiki

  1. Run the pre-migration analysis:
    python migration_planner.py
  2. Review the generated report: Open migration_analysis_report.md and note pages requiring special attention, estimate time, and identify manual work.
  3. Key things to look for: Pages with high complexity, number of images/attachments, pages with tables or HTML, and internal links.

Step 1.3: Preview Content Conversion

  1. Run content preview tool:
    python content_previewer.py
  2. Review the preview report: Open content_preview_report.md to check if the conversion is acceptable.
✅ Phase 1 Checkpoint: You should now have a clear understanding of your migration scope and complexity.

🛠️ Phase 2: MediaWiki Preparation (30-45 minutes)

Step 2.1: Set Up MediaWiki Test Environment

Use Docker (Recommended for testing) or an existing MediaWiki instance. For Docker:

cd ../examples
docker-compose up -d
# MediaWiki will be available at http://localhost:8080

Step 2.2: Configure MediaWiki

Enable extensions like SyntaxHighlight_GeSHi, ParserFunctions, and WikiEditor. Test basic functionality by creating a test page.

Step 2.3: Prepare for Images and Attachments

Create directories for assets and plan your image handling strategy (e.g., which images to migrate, optimization).

mkdir -p ../assets/images
mkdir -p ../assets/attachments
✅ Phase 2 Checkpoint: Your MediaWiki is ready and you have a plan for handling multimedia content.

🚀 Phase 3: Test Migration (45-90 minutes)

Run a small test migration with low-complexity pages, verify the results on your test MediaWiki, and document any issues. Handle images and attachments by downloading them from Azure DevOps and uploading them to MediaWiki, then updating the links.

✅ Phase 3 Checkpoint: You've successfully tested the migration process and resolved any major issues.

🎯 Phase 4: Production Migration (1-4 hours)

Back up your production MediaWiki, update your .env file with production credentials, and run the full migration. Monitor the process and handle any failed pages. Conduct a post-migration review of complex pages and update all internal and image links.

python azure_devops_migrator.py > migration.log 2>&1
✅ Phase 4 Checkpoint: Your complete wiki has been migrated to MediaWiki.

✅ Phase 5: Validation & Cleanup (30-60 minutes)

Spot-check migrated content, set up user accounts and permissions, and create documentation for your users about the new wiki and any changes.

✅ Phase 5 Checkpoint: Migration complete and validated!

🎉 Phase 6: Go-Live & Support (Ongoing)

Announce the migration to stakeholders, provide training if necessary, and establish a process for ongoing monitoring and support.

🚨 Common Issues & Troubleshooting

Troubleshooting Tips
  • Authentication Issues: Verify PAT permissions and API access. Use bot passwords for SSO.
  • Content Conversion Issues: Ensure required MediaWiki extensions are installed. Complex tables may need manual adjustment.
  • Performance Issues: Add delays between requests or process in batches to avoid rate limiting.
  • Image Issues: Images must be uploaded manually to MediaWiki, and links updated accordingly.

🔗 Additional Resources

🏠