# Enabling Automatic Updates

Enabling and configuring secure automatic updates in **Varbase 10.1.x** using **Drupal 11, Automatic Updates**, **Package Manager** module and **The Update Framework (TUF)**.

Integrating Drupal 11's experimental automatic updates functionality into your Varbase 10.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 10.1.x installed
* Drupal 11.0 or higher
* PHP 8.3 or higher
* Composer 2.8 or higher
* DDEV or equivalent development environment
* Write access to (`settings.php` or `settings.ddev.php`)and `composer.json`

{% hint style="warning" %}
**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.
{% endhint %}

### Understanding the Components

#### Package Manager Module

An experimental module bundled with Drupal 11 that provides the API functionality for staging package installations and updates using Composer.

**Location:** `docroot/core/modules/package_manager`

**Repository:** <https://git.drupalcode.org/project/drupal/-/tree/11.x/core/modules/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

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 10.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 10.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:

```bash
vim docroot/sites/default/settings.php
```

Add the following line at the end of the file:

```php
/**
 * Enable Package Manager for automatic updates.
 */
$settings['testing_package_manager'] = TRUE;
```

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

**Step 2: Enable the Module**

```bash
ddev drush en package_manager -y
```

You should see:

```
[success] Successfully enabled: package_manager
```

**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:

```bash
ddev drush config:edit package_manager.settings
```

Add the following configuration:

```yaml
additional_trusted_composer_plugins:
  - vardot/varbase
  - composer/installers
  - cweagans/composer-patches
  - oomphinc/composer-installers-extender
  - drupal/core-composer-scaffold
  - drupal/core-project-message
  - dealerdirect/phpcodesniffer-composer-installer
  - phpstan/extension-installer
  - php-http/discovery
  - tbachert/spi
include_unknown_files_in_project_root: false
```

**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)

{% hint style="info" %}
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.
{% endhint %}

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:

```json
"drupal-scaffold": {
  "allowed-packages": [
    "drupal/core"
  ],
  ...
  ...
}
```

**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**

```bash
mkdir -p tuf
```

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:

```bash
curl -o tuf/packages.drupal.org.json \
  https://packages.drupal.org/8/metadata/1.root.json

curl -o tuf/packagist-signed.drupalcode.org.json \
  https://packagist-signed.drupalcode.org/metadata/1.root.json
```

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

**Step 3: Allow TUF Composer Plugin**

```bash
ddev composer config allow-plugins.php-tuf/composer-integration true
```

**Step 4: Install TUF Integration**

```bash
ddev composer require php-tuf/composer-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:

```json
"repositories": {
  "drupal-core": {
    "type": "composer",
    "url": "https://packagist-signed.drupalcode.org",
    "tuf": true
  },
  "drupal": {
    "type": "composer",
    "url": "https://packages.drupal.org/8",
    "tuf": true
  }
}
```

**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:

```bash
ddev composer config --unset disable-tls
ddev composer config --unset secure-http
```

Validate your Composer configuration:

```bash
ddev composer validate
```

You should see:

```
./composer.json is valid
```

**Step 7: Update Composer Lock File**

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

```bash
ddev composer update --lock
```

#### Phase 4: Enable Automatic Updates Modules

**Step 1: Enable Automatic Updates**

**Automatic Updates** is included by default in Varbase 10.1.x.

Enable the module:

```bash
ddev drush en automatic_updates -y
```

**Step 2: Enable Automatic Updates Extensions**

This module provides support for updating contributed modules:

```bash
ddev drush en automatic_updates_extensions -y
```

**Step 3: Rebuild Cache**

```bash
ddev drush cr
```

#### Phase 5: Verification and Testing

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:

```json
{
  "repositories": {
    "drupal-core": {
      "type": "composer",
      "url": "https://packagist-signed.drupalcode.org",
      "tuf": true
    },
    "drupal": {
      "type": "composer",
      "url": "https://packages.drupal.org/8",
      "tuf": true
    }
  },
  "config": {
    "allow-plugins": {
      "php-tuf/composer-integration": true,
      "composer/installers": true,
      "cweagans/composer-patches": true,
      "drupal/core-composer-scaffold": true,
      "oomphinc/composer-installers-extender": true,
      "tbachert/spi": true,
      "vardot/varbase-updater": true,
      "dealerdirect/phpcodesniffer-composer-installer": true,
      "phpstan/extension-installer": true
    }
  },
  "drupal-scaffold": {
    "allowed-packages": [
      "drupal/core"
    ],
    "gitignore": true,
    "locations": {
      "web-root": "docroot/"
    }
  }
}
```

#### Package Manager Configuration

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

```yaml
additional_trusted_composer_plugins:
  - vardot/varbase
  - cweagans/composer-patches
  - oomphinc/composer-installers-extender
  - tbachert/spi
  - dealerdirect/phpcodesniffer-composer-installer
  - phpstan/extension-installer
include_unknown_files_in_project_root: false
```

### 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:

```bash
ddev composer update --lock
```

Verify the issue is resolved:

```bash
ddev composer validate --check-lock
```

#### 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:

```bash
ddev drush role:perm:add administrator "administer software updates"
ddev drush role:perm:add administrator "administer site configuration"
ddev drush cr
```

#### 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:

```bash
rm -rf tuf/* vendor/composer/tuf/*
ddev exec bash -c "rm -rf ~/.cache/composer-tuf"
```

Re-download root metadata:

```bash
curl -o tuf/packages.drupal.org.json \
  https://packages.drupal.org/8/metadata/1.root.json
curl -o tuf/packagist-signed.drupalcode.org.json \
  https://packagist-signed.drupalcode.org/metadata/1.root.json
```

Run the update again:

```bash
ddev composer update --lock
```

**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:

```bash
ddev drush automatic-updates:check
```

Add any untrusted plugins to the Package Manager configuration:

```bash
ddev drush config:edit package_manager.settings
```

#### 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:

bash

```bash
ddev exec sudo chown -R $(whoami):$(whoami) /var/www/html
```

Verify the vendor directory is writable:

```bash
ls -la vendor/
```

### 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 10.1.x project should include these files:

```
your-project/
├── composer.json           # Updated with TUF repositories and scaffold config
├── composer.lock           # Regenerated with TUF signatures
├── tuf/                    # TUF metadata cache directory
│   ├── packages.drupal.org.json
│   └── packagist-signed.drupalcode.org.json
├── docroot/
│   └── sites/default/
│       └── settings.php    # Contains testing_package_manager flag
└── vendor/
    └── composer/
        └── tuf/            # Additional TUF cache (auto-generated)
```

### Testing and Validation Commands

Use these commands to verify your automatic updates setup:

**Check module status:**

```bash
ddev drush pm:list | grep -E "(package_manager|automatic_updates)"
```

**Validate Composer configuration:**

```bash
ddev composer validate --strict
```

**Check for available updates:**

```bash
ddev drush pm:security
```

**View Package Manager status:**

```bash
ddev drush automatic-updates:check
```

**Test TUF functionality:**

```bash
ddev composer update --dry-run
```

**Verify file permissions:**

```bash
ddev exec ls -la vendor/ | head -n 5
```

### Integration Into New Varbase 10.1.x Projects

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

**Step 1: Add Package Manager testing flag**

```bash
echo "\$settings['testing_package_manager'] = TRUE;" >> docroot/sites/default/settings.php
```

**Step 2: Create TUF cache directory and download metadata**

```bash
mkdir -p tuf
curl -o tuf/packages.drupal.org.json https://packages.drupal.org/8/metadata/1.root.json
curl -o tuf/packagist-signed.drupalcode.org.json https://packagist-signed.drupalcode.org/metadata/1.root.json
```

**Step 3: Configure Composer for TUF**

```bash
ddev composer config allow-plugins.php-tuf/composer-integration true
ddev composer require php-tuf/composer-integration
```

**Step 4: Enable required modules**

```bash
ddev drush en package_manager automatic_updates automatic_updates_extensions -y
```

**Step 5: Set administrator permissions**

```bash
ddev drush role:perm:add administrator "administer software updates"
ddev drush cr
```

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

### Maintenance Schedule

#### Weekly Tasks

* Check for available updates via the administrative interface
* Review Drupal security advisories at <https://www.drupal.org/security>

#### Monthly Tasks

* Verify TUF metadata is updating correctly:

```bash
  ls -lt tuf/
```

* Run validation checks:

```bash
  ddev drush automatic-updates:check
```

#### 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

* [Automatic Updates Project](https://www.drupal.org/project/automatic_updates) - Contributed module page
* [The Update Framework](https://theupdateframework.io/) - TUF specification and security details
* [PHP-TUF Composer Integration Plugin](https://github.com/php-tuf/composer-integration)
* [PHP-TUF](https://github.com/php-tuf/php-tuf)  is a PHP implementation of [The Update Framework (TUF)](https://theupdateframework.io/)&#x20;
* [PHP-TUF Composer Stager](https://github.com/php-tuf/composer-stager) makes long-running Composer commands safe to run on a codebase in production by "staging" them--performing them on a non-live copy of the codebase and syncing back the result for the least possible downtime. ( required in Drupal Core 11.2 )

#### Community Support

* [Drupal Slack](https://drupal.slack.com) - #automatic-updates channel for community support
* [Varbase Issue Queue](https://www.drupal.org/project/issues/varbase) - Report Varbase-specific issues
* [Drupal Automatic Updates Documentation](https://www.drupal.org/docs/8/update/automatic-updates) - Additional technical documentation

### Post-Setup Checklist

After completing the setup, verify the following:

* [ ] **Package Manager** module is enabled
* [ ] **Automatic Updates** and **Automatic Updates Extensions** modules are enabled
* [ ] TUF metadata files downloaded in `tuf/` directory
* [ ] `composer.json` repositories have `"tuf": true` configuration
* [ ] Trusted plugins configured in **Package Manager** settings
* [ ] Drupal scaffold limited to `drupal/core` only
* [ ] `$settings['testing_package_manager'] = TRUE;` in the **`settings.php`** file ( or other local `settings.ddev.php` )
* [ ] Administrator role has "administer software updates" permission
* [ ] Update pages accessible at `/admin/reports/updates/update`
* [ ] `composer.lock` file synchronized with `composer.json`
* [ ] No validation errors from `ddev drush automatic-updates:check`
* [ ] Successfully tested staging and applying an update (if available)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.varbase.vardot.com/10.1.x/developers/updating-varbase/enabling-automatic-updates.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.