Skip to content

Wagtail Transfer Setup

This document describes how to use Wagtail Transfer to migrate page content between environments.

Overview

Wagtail Transfer is configured to allow transferring content between environments for: - SchoolsResourcePage (from tate.schools) - All Kids pages (KidsGeneralPage, KidsArticlePage, KidsLandingPage, KidsArticleCategoryPage, KidsGalleryPage) - Related images and documents

Available Source Environments

Three source environments are configured: - production: Always https://www.tate.org.uk - pre_production: Always https://wagtail-preprod.tate.org.uk - railway: Configurable via WAGTAILTRANSFER_RAILWAY_URL environment variable

Installation

The package has been added to pyproject.toml. Run: 

fab start
docker compose exec -T web poetry install --no-root

Configuration

Environment Variables

Add these to your .env file:

# Secret key for Wagtail Transfer (generate a secure random string)
WAGTAILTRANSFER_SECRET_KEY=your-secret-key-here

# Railway environment URL (optional - only for Railway transfers)
WAGTAILTRANSFER_RAILWAY_URL=https://your-railway-environment.up.railway.app

For Railway/Azure deployments, set WAGTAILTRANSFER_RAILWAY_URL in your environment configuration to the URL of the Railway environment you want to pull content from.

Settings

Configuration is in tate/settings/base.py: - WAGTAILTRANSFER_SOURCES: Defines source environments - WAGTAILTRANSFER_UPDATE_RELATED_MODELS: Images and documents that get transferred - WAGTAILTRANSFER_CHOOSER_API_MODELS: Specific page models configured for transfer

Usage

Via Admin Interface

  1. Navigate to /admin/wagtail-transfer/choose/ in your Wagtail admin
  2. Or find "Wagtail Transfer" in the admin menu (if visible)
  3. Select a source environment (if configured)
  4. Browse or search for pages to import
  5. Select pages and click "Import"

Note: You must be logged in as a Wagtail admin user with the "Can import" permission to access this interface.

Via Fabric Commands

List available models

fab list-transferable-models

Transfer specific content

# Transfer all SchoolsResourcePage from production
fab transfer-content --model=SchoolsResourcePage --source-env=production

# Transfer from pre-production
fab transfer-content --model=KidsArticlePage --source-env=pre_production

# Transfer from Railway environment (requires WAGTAILTRANSFER_RAILWAY_URL)
fab transfer-content --model=KidsGalleryPage --source-env=railway --page-id=123

Export/Import via files

# Export pages to JSON
fab export-pages --model=SchoolsResourcePage
fab export-pages --page-id=123

# Import from JSON file
fab import-pages --file-path=export.json

How It Works

  1. Page Selection: You select which pages to transfer from the source
  2. Dependency Resolution: Wagtail Transfer automatically includes: - Child pages (if transferring a parent) - Referenced images (CustomImage) - Referenced documents - StreamField content
  3. Import Process: - Creates new pages if they don't exist - Updates existing pages based on their UUID - Maintains page hierarchy - Preserves internal links

Important Notes

  1. User Permissions: Imported pages retain references to users. Ensure matching usernames exist or pages will be assigned to the importing user.

  2. Site Configuration: Pages are imported to the current site. You may need to update the site root page after import.

  3. Media Files: Images and documents are imported, but the actual files need to be accessible. Use fab prod.pull-media to sync media files if needed.

  4. Unique Fields: Some models may have unique constraints that prevent imports. Review errors carefully.

Troubleshooting

Common Issues

  1. "Secret key mismatch": Ensure WAGTAILTRANSFER_SECRET_KEY matches between environments

  2. "Page not found": The page might not exist in the source or might be unpublished

  3. "Permission denied": Ensure your user has permission to create/edit the page types being imported

  4. Media not showing: Run fab prod.pull-media to sync media files from production

  5. Railway source not showing: - Ensure WAGTAILTRANSFER_RAILWAY_URL is set in your environment - The Railway option only appears when this environment variable is configured

Testing

To test the setup:

  1. Start your local environment: 

    fab start

  2. Create a test page in the admin

  3. Export it: 

    fab export-pages --page-id=<page_id>

  4. Import to another environment or delete and re-import locally

Security Considerations

  • Keep WAGTAILTRANSFER_SECRET_KEY secure and different per environment
  • Use HTTPS for all transfer URLs
  • Restrict access to /admin/wagtail-transfer/ via permissions
  • Audit transfer logs regularly

Further Information