[DrupalCon Prague] - Automatic Updates 8.x-2.x testing guide for local environments

Thank you for beta testing! These instructions describe how to install the Automatic Updates module into a Drupal site, and use it to update Drupal core.

Please report your test result when finished.

Pre-Requisites

1. Access to the command line.
2. PHP 7.3 or later: run php --version or visit /admin/reports/status/php in your Drupal site to confirm what version is installed.
3. Composer 2.3.5 or later. Run composer --version to find out what version of Composer you have. If it's older than 2.3.5, run composer self-update --2.

Once the pre-requisites are fulfilled, you can either test with a new Drupal site or install Automatic Updates in an existing site.

Testing with a new Drupal Project

The preferred method of creating a site for local development is our fully-automated script--instructions in DEVELOPING.md. If you can't and prefer not to use it, use the following instructions to set it up manually.

1. Open a terminal (command line).
2. Run the following commands, replacing TEST_DIR with your intended local test directory or your virtualhost directory on a remote test server.

   composer create-project drupal/recommended-project:9.4.0 TEST_DIR --no-install --no-interaction
   cd TEST_DIR
   composer config allow-plugins.composer/installers true
   composer config allow-plugins.drupal/core-project-message true
   composer config allow-plugins.drupal/core-composer-scaffold true
   composer require 'drupal/automatic_updates:^2' --no-interaction --with-all-dependencies

3. Rename the docroot (i.e., browsable site directory), if necessary. For example, on a remote test server, your hosting provider might use docroot or htdocs.

   mv web YOUR_DOCROOT

4. For local testing, use Drupal's built-in "quick-start" script to start a lightweight temporary server:

   cd YOUR_DOCROOT
   php ./core/scripts/drupal quick-start standard

   You should see a browser open and log you into the new Drupal site.

5. For testing on a remote test server, take whatever steps your hosting provider requires to make the new codebase "browseable" and navigate to the test address in your browser.
6. You can now take the next steps.

Testing with an existing Drupal Project

1. Open the command line and navigate to the directory of your Drupal project.
2. Run: composer require 'drupal/automatic_updates:^2' --with-all-dependencies
3. Log in to your Drupal site as an administrator. You can now take the next steps.
4. IMPORTANT: If you have Drush installed, please see this note.

Install the Automatic Updates module

1. Click "Extend" in the navigation menu.
2. Search for "Automatic Updates".
3. Select the checkbox for "Automatic Updates".
4. Click "Install" button at the bottom of the page.
5. You may be redirected to a page detailing additional modules will be enabled. Click the "Continue" button.
6. You should see a message telling you that Automatic Updates (and possibly other modules) have been enabled.

Use Automatic Updates to update Drupal

1. Ensure you're on the "Extend" page (/admin/modules) and click the "Update" tab.
2. You should see a newer version of Drupal as the recommended version. If you installed Automatic Updates into an existing Drupal site, you won't see this if you're already fully up to date. In that case, you may want to start again with a new Drupal project.
3. Click the "Update" button. You should be redirected to a page with a progress bar.
4. When you see a "Ready to update" screen, click the "Continue" button.
5. You should see an "Apply updates" screen with a progress bar.
6. You should be redirected to the "Available updates" page and see the message "Update complete!". If database updates are needed, you should be redirected to /update.php to run those; follow the instructions and you should get redirected to the "Available updates" page when finished.
7. You should see that Drupal core is fully up-to-date.

You may run into a known issue or limitation; see the project page for more information.

If you have Drush installed: There is a known issue where Drush installs a dependency that contains symbolic links, which can cause Automatic Updates to fail. To get around this, we recommend configuring Automatic Updates to use rsync, if you have it available; run which rsync or whereis rsync to determine its location, if it's installed. Then, run the following commands (replace /full/path/to/rsync with the actual path to rsync):

drush config:set package_manager.settings file_syncer rsync
drush config:set package_manager.settings executables.rsync /full/path/to/rsync

Thanks for testing! Please let us know how it went.

Were these instructions unclear or inaccurate? Please leave a comment on this issue to tell us about it.