README

A command-line tool for automating Drupal 8+ site updates with the following features:

• Fully automated updates for multiple sites
• Option to automatically commit and push to a git repository
• Automatic download of production database (if a drush alias is present)
• Backup of database prior to updates
• Function to rollback a site so you can test the update deployment manually prior to production deployment
• Detailed summary of updates used in git commit
• Option to send email notifications with the detailed summary
• Options for handling scaffold files that may have been overriden in the project (if you are not already taking care of that another way)
• Nicely formatted logging and a log display command to quickly review any messages generated by the last run command
• Proper handling of multisite configurations

NOTE: This project is still in beta. If you are interested in contributing to the project, you are welcome to fork it and submit a pull request with changes. I would just ask that you create an issue first that you can link to your pull request.

WANTED: Somebody to write automated tests! I'm not sure what kind of tests to write and don't have lots of time to work on it, so help is appreciated on this.

Installation

The only thing you actually need to use this script is the compiled binary. Head over to the latest release and under the assets download the drupalup.phar file. Place this file somewhere in your path (e.g. /usr/local/bin), rename it to remove the .phar extension, and make sure it has execute permission.

You then just need to setup the configuration files, as per the instructions below. You may choose to configure a cron job to run updates regularly, so long as the user running the cron job has access to push to your git remote repository.

Compiling the Binary

The codebase does not include code for compiling the binary. Instead, I chose to make my life simple and use the excellent clue/phar-composer library. Just install that on your system somewhere and then you can run:

phar-composer build [/path/to/this/script/root] [/path/to/this/script/root/build/drupalup.phar]

Configuration

The updater will look for it's configuration files in the following directories, using the first one it finds in this order of preference:

• ~/drupalup
• ~
• /usr/local/etc/drupalup
• /usr/local/etc

The primary configuration file must be named drupalup.settings.yml and placed in one of the above locations. The secondary configuration file required is drupalup.sites.yml, which must also be in one of the above locations, ideally in the same place as drupalup.settings.yml to make it easier to maintain.

Browse into the sample-config folder in the source code and download them to use as a starting point. They are fully documented with comments and as such are not detailed here.

Pre-requisites

Git

Git must be installed on the system as it will be used to check the current state of the codebase, as well as perform any git operations if not running updates in dry-run mode.

When running one of the commands, it needs to ensure that the codebase has no new or modified files and that it is currently on the appropriate branch. This is to prevent breaking something in case the site currently has some other work in progress.

When running updates and not using dry-run mode, it will also be used to commit the updates to the updates branch and push them to the remote repository.

Composer

Composer must be installed on the system since that is what is used to install updates with. It will require the minimum version of composer specified at https://www.drupal.org/docs/system-requirements/composer-requirements.

Drush

The script will expect to find the drush binary in vendor/bin within the codebase of each site. If it is not found, the site will be skipped and an error notification generated. If you have specified drush under require-dev in the composer file, then the system running this script needs to have the sites all installed with the dev dependencies.

This requirement also automatically prevents it from working on typical Drupal 7 site installations.

Usage

You can run the script by calling drupalup or /direct/path/to/drupalup, depending on whether or not it's in your path.

Run drupalup list to see all commands or run drupalup help for detailed usage instructions.

This project uses the Symfony console component, which provides the following default commands and options:

NOTE: All commands have a common --debug option that writes additional data to the log file for troubleshooting purposes. Using level 3 verbosity also enables debug, but using debug does not increase verbosity.

Run Drupal Updates

Command: drupalup or drupalup update

Runs the drupal updates on all the sites in the drupalup.sites.yml file. This is the default command and does not have to be supplied as an argument when calling the script. This is the default command.

Options:

• <uri> - Optional. Specify a single site to update. Must match a URI in the drupalup.sites.yml file. If omitted, all sites will be updated.
• --select, -s - Optional. Lists all available sites allowing the user to select one to be updated. Only works if <uri> is not supplied, otherwise ignored.
• --notify, -N - Optional. Send an email notification on completion. Only needed if the always_notify config setting is false or omitted.
• --dry-run, -d - perform a dry-run, meaning run all the updates, send a notification (if enabled), but perform git commits and pushes in dry-run mode and log the results.
• --skip-db-sync - skip syncing the database(s) from production. This is useful if you need to re-run the update multiple times and the database was already synced the first time.

Rollback Updates

Command: drupalup rollback

Rolls back updates for a single site. This will reset the site back to the main branch, restore the database from the backup and then run composer install to restore the composer libraries to their previous state.

The purpose of this command is so you can test deployment of the updates prior to production deployment. It does not perform any git operations or send any email notifications. It only works if the site was updated already by the update command.

Options:

• <uri> - Optional. Must match a URI in the drupalup.sites.yml file. If not supplied, all available sites will be listed for the user to choose the one to rollback.

The rollback process will fail if the source is not currently on either the updates or master branch or there is no database backup file found.

Display Log Entries

Command: drupalup log

Displays log entries (if any) for the last run command in a table format. If anything is logged while a command is running, it will notify you of that upon completion.