Enabling Automatic Updates

Enabling and configuring secure automatic updates in Varbase 9.1.x using Drupal 10.5's Package Manager module and The Update Framework (TUF).

Overview

This guide walks you through integrating Drupal 10.5's experimental automatic updates functionality into your Varbase 9.1.x projects. With automatic updates enabled, your site will be able to:

  • Stage and apply Drupal core updates through the admin interface

  • Update contributed modules securely with cryptographic verification

  • Protect against supply chain attacks during package downloads

  • Validate system requirements before applying updates

The automatic updates system consists of three main components working together to provide secure, reliable updates for your Varbase site.

Prerequisites

Before you begin, ensure you have:

  • Varbase 9.1.x installed

  • Drupal 10.5 or higher

  • PHP 8.3 or higher

  • Composer 2.7 or higher

  • DDEV or equivalent development environment

  • Write access to (settings.php or settings.ddev.php)and composer.json

Important: Automatic updates should always be configured and tested in a local or development environment first. DO NOT enable automatic updates directly on a production site.

Understanding the Components

Package Manager Module

Package Manager ~3.0 is an experimental sub module in Automatic Update module that provides the API functionality for staging package installations and updates using Composer.

Repository: https://git.drupalcode.org/project/automatic_updates/-/tree/3.0.x/package_manager

Package Manager acts as the "engine" that powers automatic updates by:

  • Validating system requirements before staging updates

  • Creating isolated staging areas for Composer operations

  • Checking for file system compatibility

  • Ensuring composer.lock and composer.json are synchronized

Automatic Updates Module

Automatic Updates is a contributed module that builds on top of Package Manager to provide user interface and automation for managing updates.

Repository: https://www.drupal.org/project/automatic_updates

This module is included by default in Varbase 9.1.x. It provides:

  • Administrative interface for viewing and applying updates

  • Support for both core and contributed module updates

  • Staging and rollback capabilities

  • Integration with Drupal's update status system

The Update Framework (TUF)

The Update Framework provides cryptographic verification of package metadata to ensure packages haven't been tampered with during download.

Website: https://theupdateframework.io/

TUF protects your site by:

  • Verifying cryptographic signatures on all packages

  • Preventing man-in-the-middle attacks

  • Detecting malicious package substitution

  • Ensuring timestamp validation for timely updates

Setup Process

Follow these steps in order to enable automatic updates on your Varbase 9.1.x project.

Phase 1: Enable Package Manager

Since Package Manager is experimental, it requires explicit configuration before it can be enabled.

Step 1: Configure Settings

Edit your settings file:

Add the following line at the end of the file:

This setting allows the experimental Package Manager module to be enabled on your site.

Step 2: Enable the Module

You should see:

Troubleshooting: If you receive an "unmet requirements" error, verify the testing_package_manager setting was saved correctly, then clear cache with ddev drush cr

Step 3: Configure Package Manager Settings

Edit the Package Manager configuration:

Add the following configuration:

What this does:

  • additional_trusted_composer_plugins: Tells Package Manager which Composer plugins are safe to use during automatic updates

  • include_unknown_files_in_project_root: Prevents updates if unexpected files appear in the project root (security measure)

Check all allow-plugins in the root composer.json file, which they must be added into the list in additional_trusted_composer_plugins in the package_manager.settings config.

Save and exit the editor.

Tip: If your project uses additional custom Composer plugins, add them to the additional_trusted_composer_plugins list.

Phase 2: Configure Drupal Scaffold

Drupal scaffold files (such as .htaccess, index.php, robots.txt) need special handling during automatic updates.

Update composer.json Scaffold Configuration

Edit your project's composer.json file, then locate the "drupal-scaffold" section and update it to match:

Why restrict to drupal/core?

  • Reduces complexity during automatic updates

  • Prevents conflicts with Varbase-specific customizations

  • Most scaffold files should only originate from Drupal core

Phase 3: Set Up The Update Framework (TUF)

The Update Framework provides cryptographic verification to ensure downloaded packages are authentic and haven't been tampered with.

Step 1: Create TUF Cache Directory

This directory will store TUF metadata (repository signing keys and timestamps).

Step 2: Download Initial Root Metadata

Download the root metadata files containing public keys for package verification:

You should see two .json files created in the tuf/ directory.

Step 3: Allow TUF Composer Plugin

Step 4: Install TUF Integration

Note: This step may take 2-3 minutes as it downloads and verifies the initial metadata.

Step 5: Configure Repositories with TUF

Open your project's composer.json file and update the "repositories" section to enable TUF verification:

Key points:

  • "tuf": true enables signature verification for that repository

  • TUF is only enabled for Drupal repositories (they support it)

  • Asset repositories don't support TUF yet

Step 6: Verify Security Configuration

Ensure TLS and secure HTTP are properly configured:

Validate your Composer configuration:

You should see:

Step 7: Update Composer Lock File

Regenerate your composer.lock file with TUF-verified package signatures:

Phase 4: Enable Automatic Updates Modules

Step 1: Enable Automatic Updates

Automatic Updates is included by default in Varbase 9.1.x.

Enable the module:

Step 2: Enable Automatic Updates Extensions

This module provides support for updating contributed modules:

Step 3: Rebuild Cache

Phase 5: Verification and Testing

Step 1: Configure User Permissions

Grant administrator users the required permissions:

Step 2: Access Update Pages

Generate a one-time login link:

Copy the generated URL and open it in your browser.

Navigate to the following pages to verify everything is working:

  1. Core updates page: Navigate to Administration \ Reports \ Available updates \ Update Direct URL: /admin/reports/updates/update

  2. Extension updates page: Navigate to Administration \ Reports \ Available updates \ Automatic Update Extensions Direct URL: /admin/reports/updates/automatic-update-extensions

Success indicators:

  • Both pages load without errors (HTTP 200)

  • You see available updates or "All projects are up to date"

  • "Stage update" or "Apply update" buttons appear for available updates

Step 3: Test Staging an Update (Optional)

If updates are available, test the staging process:

  1. Click "Stage update" on the updates page

  2. Wait for staging to complete (progress bar will show status)

  3. Review the staged changes

  4. Click "Apply staged update" to apply the update

  5. Verify your site functions correctly after the update

Best Practice: Always test updates on a development environment before applying them to staging or production sites.

Configuration Reference

Complete composer.json Structure

After completing the setup, your composer.json should include these key sections:

Package Manager Configuration

The Package Manager configuration should include all trusted Composer plugins used in your Varbase project:

Troubleshooting

Issue: Lock File Is Not Up to Date

Symptoms: Automatic updates fail with a Composer lock file validation error.

Cause: Your composer.lock file doesn't match changes made to composer.json.

Solution:

Update the lock file:

Verify the issue is resolved:

Issue: 403 Forbidden on Update Pages

Symptoms: Cannot access the updates pages at /admin/reports/updates/update.

Cause: User account lacks required permissions.

Solution:

Grant the necessary permissions:

Issue: TUF Rate Limit (1024 Root Files Error)

Symptoms: Running composer update fails with "DoS protection triggered" error.

Cause: Excessive TUF metadata refreshes during development, typically from running many composer update commands in succession.

Impact: This is a development-only issue. Normal automatic updates through the admin interface are not affected.

Solution:

Clear all TUF caches:

Re-download root metadata:

Run the update again:

Prevention: Minimize manual composer update commands during active development.

Issue: Package Manager Validation Errors

Symptoms: Updates fail with "unsupported plugin" or "scaffold configuration" errors.

Cause: Missing plugins in the trusted list or incorrect scaffold configuration.

Solution:

Check which plugins are causing issues:

Add any untrusted plugins to the Package Manager configuration:

Issue: Codebase Not Writable Error

Symptoms: Cannot stage updates due to file permission errors.

Cause: Incorrect file permissions on project directories.

Solution:

Fix permissions on your project directory:

Verify the vendor directory is writable:

Security Considerations

TUF Protection Benefits

The Update Framework provides multiple layers of security:

  • Signature verification: Every package is cryptographically signed and verified before installation

  • Timestamp checks: Prevents rollback attacks by ensuring metadata freshness

  • Metadata validation: Ensures repository integrity and detects tampering

  • Man-in-the-middle protection: Cryptographic verification detects modified packages during download

Package Manager Safeguards

Before allowing any update, Package Manager validates:

  • Composer lock file is synchronized with composer.json

  • All Composer plugins are explicitly trusted

  • Scaffold configuration is correct and secure

  • File system has proper write permissions

  • No unknown files exist in the project root

Safety Feature: If any validation check fails, the update is blocked automatically. This prevents potentially breaking changes from being applied.

Project File Structure

After completing the setup, your Varbase 9.1.x project should include these files:

Testing and Validation Commands

Use these commands to verify your automatic updates setup:

Check module status:

Validate Composer configuration:

Check for available updates:

View Package Manager status:

Test TUF functionality:

Verify file permissions:

Integration Into New Varbase 9.1.x Projects

When starting a new Varbase 9.1.x project, you can set up automatic updates with the following commands:

Step 1: Add Package Manager testing flag

Step 2: Create TUF cache directory and download metadata

Step 3: Configure Composer for TUF

Step 4: Enable required modules

Step 5: Set administrator permissions

After completing these steps, your Varbase 9.1.x site will be configured for secure automatic updates.

Maintenance Schedule

Weekly Tasks

Monthly Tasks

  • Verify TUF metadata is updating correctly:

  • Run validation checks:

Quarterly Tasks

  • Review and update the trusted plugin list

  • Test the update process on a staging environment

  • Update project documentation with any lessons learned

Version Compatibility

Recommended Versions: For the best experience, use PHP 8.3 and the latest stable version of Composer 2.8+

Additional Resources

Official Documentation

Community Support

Post-Setup Checklist

After completing the setup, verify the following:

PreviousUpdating from Varbase 8.x to 9.xNextVarbase Patches

Last updated