Skip to main content
Version: Current (3.x)

Updating the Data Viz WordPress Blocks

This guide explains how to update the data-viz-wordpress blocks and use different Docker images (test, build, or production) from the WordPress repository when releasing.

Overview​

The data-viz-wordpress blocks are provided through Docker images from the data-viz-wordpress repository. When releasing updates, you can use different image tags depending on your needs:

  • Snapshot images: For testing release candidates (format: v<version>-snapshot-<YYYYMMDD>.<build-number>)
  • Production images: For stable releases (version tags or latest)

Prerequisites​

  • Access to the Docker registry (registry.developmentgateway.org)
  • Understanding of Docker image tags and versions
  • Access to the data-viz-wordpress repository

Understanding WordPress Image Tags​

The WordPress Docker images are published with different tags based on the release type:

Production Images​

  • registry.developmentgateway.org/data-viz/wordpress:latest - Latest stable release
  • registry.developmentgateway.org/data-viz/wordpress:v1.0.1 - Specific version tag

Pre-release/Test Images (Snapshots)​

  • registry.developmentgateway.org/data-viz/wordpress:v0.0.11-snapshot-20251010.0 - Snapshot tags for release candidates
  • Format: v<version>-snapshot-<YYYYMMDD>.<build-number>
    • v0.0.11 - Version number
    • snapshot - Indicates this is a snapshot/RC build
    • 20251010 - Date in YYYYMMDD format
    • 0 - Build number for that day (increments for multiple builds on the same day)
  • Example: v0.0.11-snapshot-20251010.0, v0.0.11-snapshot-20251010.1, v0.0.11-snapshot-20251011.0

Updating WordPress Blocks​

When a new stable version of the WordPress blocks is released:

  1. Check available versions:
# List available tags (requires Docker registry access)
docker pull registry.developmentgateway.org/data-viz/wordpress:latest
# Or check the data-viz-wordpress repository releases
  1. Update docker-compose.yml:
wordpress:
  image: registry.developmentgateway.org/data-viz/wordpress:latest
  # Or use a specific version:
  # image: registry.developmentgateway.org/data-viz/wordpress:v1.0.1
  ports:
    - "8080:80"
  environment:
    WORDPRESS_DB_HOST: mysql
    WORDPRESS_DB_USER: wordpress
    WORDPRESS_DB_PASSWORD: wordpress
    WORDPRESS_DB_NAME: wordpress
  volumes:
    - wordpress:/var/www/html
    - ./custom/wp-customizer:/var/www/html/wp-content/plugins/wp-customizer-blocks
  networks:
    - backend
    - frontend
  1. Pull and restart the service:
docker-compose pull wordpress
docker-compose up -d wordpress

Method 2: Using Test/Build Images (For Testing Releases)​

When testing release candidates or pre-release builds:

  1. Identify the snapshot image tag:

    • Check the data-viz-wordpress repository for snapshot tags
    • Snapshot tags follow the format: v<version>-snapshot-<YYYYMMDD>.<build-number>
    • Example: v0.0.11-snapshot-20251010.0 (version 0.0.11, snapshot from October 10, 2025, build 0)

  2. Update docker-compose.yml with snapshot image:

wordpress:
  # Use snapshot tag for testing
  image: registry.developmentgateway.org/data-viz/wordpress:v0.0.11-snapshot-20251010.0
  # Format: v<version>-snapshot-<YYYYMMDD>.<build-number>
  ports:
    - "8080:80"
  environment:
    WORDPRESS_DB_HOST: mysql
    WORDPRESS_DB_USER: wordpress
    WORDPRESS_DB_PASSWORD: wordpress
    WORDPRESS_DB_NAME: wordpress
  volumes:
    - wordpress:/var/www/html
    - ./custom/wp-customizer:/var/www/html/wp-content/plugins/wp-customizer-blocks
  networks:
    - backend
    - frontend
  1. Pull and test the image:
docker-compose pull wordpress
docker-compose up -d wordpress

  1. Verify the blocks are updated:

    • Access WordPress admin at http://localhost:8080/wp
    • Check that the blocks appear correctly in the block editor
    • Test block functionality

  2. Switch back to production image when ready:

wordpress:
  image: registry.developmentgateway.org/data-viz/wordpress:latest

Release Workflow​

Testing with Snapshot Tags​

When a new snapshot (release candidate) is available:

  1. Create or update a feature branch:
git checkout -b feature/update-wordpress-blocks
  1. Update docker-compose.yml with the snapshot image tag:
wordpress:
  image: registry.developmentgateway.org/data-viz/wordpress:v0.0.11-snapshot-20251010.0

The snapshot tag format is: v<version>-snapshot-<YYYYMMDD>.<build-number>

  • v0.0.11 - The version number
  • snapshot - Indicates this is a snapshot/RC build
  • 20251010 - Date in YYYYMMDD format (October 10, 2025)
  • 0 - Build number for that day
  1. Test the snapshot version:
docker-compose pull wordpress
docker-compose up -d wordpress
# Test WordPress blocks functionality
  1. Create an RC tag on your feature branch:
git add docker-compose.yml
git commit -m "chore: update WordPress blocks to v0.0.11-snapshot-20251010.0"
git tag -a 1.0.1-rc1 -m "Test WordPress blocks snapshot 20251010.0"
git push origin feature/update-wordpress-blocks
git push origin 1.0.1-rc1

  1. Deploy and verify:

    • The Jenkins pipeline will deploy using the snapshot image
    • Verify blocks work correctly in the testing environment
    • If issues are found, you can test a newer snapshot (e.g., v0.0.11-snapshot-20251010.1 or v0.0.11-snapshot-20251011.0)

Production Release​

When the snapshot is approved and a stable release is available:

  1. Update docker-compose.yml with the production version:
wordpress:
  image: registry.developmentgateway.org/data-viz/wordpress:v1.0.1
  # Or use latest for the most recent stable release
  # image: registry.developmentgateway.org/data-viz/wordpress:latest
  1. Merge to main:
git checkout main
git pull origin main
git merge feature/update-wordpress-blocks
git push origin main
  1. Create a production tag (optional):
git tag -a 1.0.1 -m "Release WordPress blocks v1.0.1"
git push origin 1.0.1

Using Environment Variables for Image Selection​

You can use environment variables to make image selection more flexible:

  1. Set environment variables:
# For testing with snapshot
export WORDPRESS_IMAGE_TAG=v0.0.11-snapshot-20251010.0

# For production
export WORDPRESS_IMAGE_TAG=latest
  1. Update docker-compose.yml:
wordpress:
  image: registry.developmentgateway.org/data-viz/wordpress:${WORDPRESS_IMAGE_TAG:-latest}
  # The :-latest provides a default value if the variable is not set
  ports:
    - "8080:80"
  environment:
    WORDPRESS_DB_HOST: mysql
    WORDPRESS_DB_USER: wordpress
    WORDPRESS_DB_PASSWORD: wordpress
    WORDPRESS_DB_NAME: wordpress
  volumes:
    - wordpress:/var/www/html
    - ./custom/wp-customizer:/var/www/html/wp-content/plugins/wp-customizer-blocks
  networks:
    - backend
    - frontend
  1. Use in deployment:
# For testing with snapshot
WORDPRESS_IMAGE_TAG=v0.0.11-snapshot-20251010.0 docker-compose up -d wordpress

# For production
WORDPRESS_IMAGE_TAG=latest docker-compose up -d wordpress

Updating Custom Blocks​

If you have custom blocks in custom/wp-customizer/blocks, they will continue to work alongside the updated WordPress blocks:

  1. Custom blocks are mounted as volumes:
volumes:
  - ./custom/wp-customizer:/var/www/html/wp-content/plugins/wp-customizer-blocks
  1. Rebuild custom blocks if needed:
cd custom/wp-customizer/blocks
pnpm install
pnpm run build
  1. Restart WordPress:
docker-compose restart wordpress

Verifying Updates​

After updating the WordPress image, verify the update:

  1. Check WordPress version:
docker exec <wordpress-container> wp core version
  1. Check installed plugins:
docker exec <wordpress-container> wp plugin list

  1. Verify blocks in editor:

    • Access WordPress admin
    • Create or edit a post/page
    • Check that data-viz blocks are available in the block inserter
    • Test block functionality

  2. Check browser console:

    • Open browser developer tools
    • Check for any JavaScript errors related to blocks
    • Verify block assets are loading correctly

Troubleshooting​

Image Not Found​

If you get an error that the image cannot be found:

# Verify you're logged into the registry
docker login registry.developmentgateway.org

# Check if the tag exists
docker pull registry.developmentgateway.org/data-viz/wordpress:<tag>

Blocks Not Appearing​

If blocks don't appear after updating:

  1. Clear WordPress cache:
docker exec <wordpress-container> wp cache flush

  1. Regenerate block registry:

    • Go to WordPress admin → Plugins
    • Deactivate and reactivate plugins if needed
    • Clear browser cache

  2. Check block registration:

docker exec <wordpress-container> wp block list

Version Conflicts​

If you encounter version conflicts:

  1. Check current image version:
docker inspect registry.developmentgateway.org/data-viz/wordpress:latest | grep -i version

  1. Verify compatibility:

    • Check the data-viz-wordpress repository for compatibility notes
    • Review release notes for breaking changes

  2. Rollback if needed:

wordpress:
  image: registry.developmentgateway.org/data-viz/wordpress:v1.0.0
  # Use previous stable version

Best Practices​

  1. Always test snapshot images before using production images
  2. Use snapshot tags for testing release candidates (format: v<version>-snapshot-<YYYYMMDD>.<build-number>)
  3. Check for newer snapshots if testing reveals issues - multiple builds may be created on the same day (incrementing build number) or on different days
  4. Use specific version tags in production instead of latest for better reproducibility
  5. Document version changes in commit messages and release notes
  6. Test custom blocks after WordPress block updates
  7. Monitor WordPress logs after updates for any errors:
docker-compose logs wordpress
  1. Keep custom blocks updated to ensure compatibility with new WordPress block versions
  2. Review release notes from the data-viz-wordpress repository before updating