Search by

webksde / drowl_upsi

webksde

Supports the DROWL Drupal Updateservice: Drush-driven start/finish workflow with backups, git commits, maintenance mode, URL checks and customer notifications.

Package info

gitlab.com/webksde-public/drupal/drowl_upsi

Homepage

Issues

Type:drupal-module

pkg:composer/webksde/drowl_upsi

Statistics

Installs: 29

Dependents: 0

Suggesters: 0

Stars: 0

0.0.2 2026-11-17 18:21 UTC

This package is not auto-updated.

Last update: 2026-11-18 16:34:30 UTC


README

Supports the DROWL Drupal Updateservice. Updates are done with composer and Drush via SSH. This module performs the Drupal side tasks before and after composer update:

drush upsi-start   →   composer update   →   drush upsi-finish

The Updateservice is controlled via Drush. The admin page (/admin/config/development/drowl-upsi, permission administer drowl_upsi) shows the settings, the mail templates and the protocol (see Admin page).

Requirements

  • Drupal ^11.4, Drush 13 (or 14), Backup and Migrate ^5.1.
  • A configured and writable private file system ($settings['file_private_path']). The module cannot be installed without.
  • The base URL of the site must be set (site_url, e.g. drush drowl_upsi:config-set site_url https://www.example.com). All commands of the module use it for URLs (mails, URL check, Drush subprocesses), so neither --uri nor options.uri in drush.yml is needed. On multisite installations --uri is still needed to select the site.
  • system.site:mail must be set (sender of the mails).
  • A composer update history in <composer-root>/log/composer-update-history.md (the directory of composer.json): composer-lock-diff tables, each entry starting with a heading written by a composer script. Recommended script (locale independent date):

    "echo \"# `date +%FT%T%z` (`whoami`):\" >> log/composer-update-history.md"
    

    Supported dates: ISO 8601 (2026-11-17T10:14:32+0100, also date -Iseconds), and the English or German output of date without format (Tue Nov 17 10:14:32 AM CET 2026, Fr 21. Mär 17:10:33 CET 2025).

  • The project root must be a git repository. If the backup directory (private://backup_migrate/drowl_upsi) is inside the repository, it must be excluded via .gitignore.
  • Optional: the core module update (Update Status) for the list of available updates. Without it, the update check steps are skipped.

Run the commands in an interactive SSH session (ssh -t). Without a terminal, all questions are answered with their default (like --no-interaction).

Workflow

drush upsi-start [--no-mail]

  1. Welcome message and login: the operator's e-mail address and the password (known to the DROWL team). Three attempts; every attempt is logged (never the password). The e-mail address is logged as user of all entries of the run. The login is asked even with -y, as long as there is a terminal. Without a terminal, set the environment variables DROWL_UPSI_OPERATOR and DROWL_UPSI_PASSWORD. There is no command line option, and the password should never be typed on the command line either (shell history); set it with read -rs DROWL_UPSI_PASSWORD && export DROWL_UPSI_PASSWORD. Failed attempts only log the e-mail address if it is a valid address.
  2. Lock, preflight (see below).
  3. If a run is already active: question "Restart?". A restart creates a new run; the maintenance mode state from before the first start is kept.
  4. New run: run ID, token, start time.
  5. update_check: list available updates, security updates first (red). Informative only.
  6. url_check: every URL must return exactly 200, otherwise abort.
  7. config_export: drush config:export -y.
  8. git_commit: git add -A and commit "DROWL Updateservice #ID: state before update" (no push). New, untracked files are listed before the commit, so unexpected files (dumps, credentials) are noticed; check them and the .gitignore before pushing.
  9. backup: database backup "BEFORE".
  10. maintenance_mode: enable maintenance mode, clear the page cache.
  11. mail: show recipients, ask, send the start mail.
  12. Shows the next steps.

Then run composer update via SSH.

drush upsi-finish [--no-mail]

Requires an active run. After an error the whole workflow is started again; all steps can be repeated.

  1. Lock, preflight.
  2. history_check: all entries of the composer update history written since the start of the run, with their combined production changes. Warning and question if there is none or the date of the last entry cannot be read.
  3. git_commit_composer: commit "DROWL Updateservice #ID: composer update".
  4. updb: drush updatedb -y. Abort on error.
  5. config_export.
  6. git_commit_config: commit "DROWL Updateservice #ID: database updates and config export".
  7. backup: database backup "AFTER".
  8. cache_rebuild: drush cache:rebuild.
  9. locale_update: drush locale:check and locale:update (only if locale is enabled; errors are warnings).
  10. requirements_check: errors of the status report (informative only).
  11. url_check with maintenance mode bypass. On failure: abort (default), retry or continue.
  12. update_check: remaining updates.
  13. module_count: active modules / included modules.
  14. maintenance_disable: question whether to disable the maintenance mode. If the site was already in maintenance mode before the start, the default is "no" and the maintenance mode is kept with -y.
  15. mail: question for the success mail. If declined: question for a notice mail with a single-line note (empty input: no mail).
  16. End of run, total duration. Push the commits manually (git push).

If upsi-finish fails to bootstrap after composer update (stale container), run drush cache:rebuild and then drush upsi-finish again.

Questions, -y, --no-interaction and --no

  • -y / --yes: all questions are answered with "yes", including the mails. Exceptions: the URL failure choice (default "abort") and the maintenance mode if it was enabled before the start (it stays enabled).
  • --no-interaction: all questions take their default. The defaults are "yes", except for the two exceptions above, so the result is the same as -y.
  • --no: all questions are answered with "no": no mails, the maintenance mode stays enabled.

Preflight

Runs at the beginning of start and finish and as drush drowl_upsi:preflight. Errors abort; on warnings you are asked whether to continue.

CheckResult
Directory is a git repositoryError
Current branch (detached HEAD)Warning
Private file system (including the backups) ignored by git, if inside the repositoryError
Private file system, backup destination and profile drowl_upsiError
Base URL (site_url) setError
Drush URI (--uri) differs from site_urlWarning
system.site:mail setError
URL list not empty (if url_check is enabled)Error
Recipient list empty (mail steps are skipped)Warning
log/composer-update-history.md missing (normal before the first update)Warning
log/composer-update-history.md inside the web root (may be readable via the web)Warning

Errors and abort

On an error the workflow stops and the run stays active (maintenance mode included). Fix the problem and run the command again (upsi-start restarts, upsi-finish repeats all steps), or abort with drush upsi-abort.

upsi-abort asks whether to disable the maintenance mode (same rules as in finish), ends the run and logs run_abort.

The module does not restore databases. The backups are regular Backup and Migrate backups and can be restored with Backup and Migrate. Note that restoring the BEFORE backup also restores the active run (State); end it with drush upsi-abort afterwards.

Drush commands

CommandAliasDescription
drowl_upsi:start [--no-mail]upsi-startStart, see above
drowl_upsi:finish [--no-mail]upsi-finishFinish, see above
drowl_upsi:statusupsi-statusActive run, duration, maintenance mode, module count
drowl_upsi:abortupsi-abortAbort the active run
drowl_upsi:preflightRun all preflight checks without changing anything
drowl_upsi:url-checkCheck the URLs (with bypass header during a run)
drowl_upsi:config-get [KEY]Show all settings or one (dot notation)
drowl_upsi:config-set KEY VALUEChange a setting
drowl_upsi:mail-preview TYPE [--note=]Render start, success or notice without sending
drowl_upsi:mail-test TYPE [--note=]Send to the BCC addresses only, subject [TEST] …
drowl_upsi:log [--limit=50] [--run=ID]Protocol including user, system user and git user
drowl_upsi:module-countActive modules / included (-v lists them)

start, finish and abort use a lock (drowl_upsi.command), so they cannot run in parallel.

Configuration (drowl_upsi.settings)

KeyDescription
site_urlBase URL of the site (required), e.g. https://www.example.com
recipientsCustomer e-mail address(es) (contract)
module_limitNumber of modules included in the Updateservice (contract)
urlsURLs to check, must return 200 (contract)
bccBCC recipients, also used by mail-test
reply_toReply-To address (empty: none)
steps.start.*, steps.finish.*Enable/disable each step (true/false)

A disabled step is shown as "skipped (disabled)" and logged.

Every change of the settings is logged (type config) with the old and new values, the source (settings form, YAML import, drush, config import) and the user, whatever way the settings were changed.

config-set accepts the keys above in dot notation and validates them against the configuration schema (URLs, e-mail addresses, integers, booleans). On an error nothing is saved. Lists are comma separated:

drush drowl_upsi:config-set urls "https://example.com/,https://example.com/kontakt"
drush drowl_upsi:config-set recipients "kunde@example.com, chef@example.com"
drush drowl_upsi:config-set recipients ""            # empty list
drush drowl_upsi:config-set reply_to drupal@webks.de
drush drowl_upsi:config-set module_limit 200
drush drowl_upsi:config-set steps.finish.locale_update false

Admin page

Everybody with the permission administer drowl_upsi sees the status, the settings (collapsed), the mail templates and the protocol (collapsed, 50 entries per page). The user column combines the Drupal user or Drush operator, the system user and the git user. The data of an entry (e.g. complete mails) opens in a dialog.

Everybody with the permission can also edit the settings and import the contract data. Until the initial configuration is set (recipients not empty), the form is shown directly; afterwards only if the page is opened with a specific query parameter (known to the DROWL team).

The query parameter and the password of drowl_upsi:start are the same key. It is a simple hurdle against accidental use, not a security measure: it is stored as an unsalted hash in this public code and can easily be recovered. The actual protection is the restricted permission administer drowl_upsi for the admin page and shell access for Drush.

Contract import (YAML)

Only the contract data can be imported, no technical settings. The keys are the configuration keys; only the given keys are changed:

recipients:
  - kunde@example.com
module_limit: 150
urls:
  - https://www.example.com/
  - https://www.example.com/kontakt

Mails

The mail texts are part of the module (German, plain text): templates/mail/start.txt.twig, success.txt.twig and notice.txt.twig. Each template provides the blocks subject and body. They are rendered directly with Twig, not through the theme layer: themes cannot override them and Twig debug output never ends up in mails. Escaping is disabled ({% autoescape false %}), because the mails are plain text. Changes to the texts reach all sites with the next module update.

VariableContent
site_name, site_urlSite name and absolute front page URL (based on the site_url setting)
changesProduction changes of all history entries since the start of the run, combined into one table (first "From", last "To" per package; dev changes left out); empty if none
changes_dateDate of the last of these entries
module_count, module_limitActive modules and included modules
module_limit_exceededWhether the limit is exceeded
backup_before, backup_afterWhether the backup steps are enabled
start_date, finish_dateStart and end of the run
reply_toReply-To address
noteNote of the notice mail

Mails are sent through the active mail system. Avoid text in angle brackets (<…>) in the templates: core mail plugins convert the body with htmlToText(), which removes it. Long table lines may be wrapped by the mail system.

Modules counted: all installed modules except core modules, the installation profile and drowl_upsi itself.

Maintenance mode

While a run is active, the maintenance page shows a fixed text (German for de, English otherwise). The configured maintenance message is never changed, so it cannot end up in a config export; it is active again as soon as the run ends.

During a run, the URL check sends the header X-Drowl-Upsi-Token (random token of the run) to URLs with exactly the scheme, host and port of site_url only, never to other hosts. Requests with a valid token bypass the maintenance mode and are never served from or stored in the page cache or the dynamic page cache. Visitors still get the maintenance page. The token is replaced at the end of upsi-start, at the beginning and end of upsi-finish and after drowl_upsi:url-check, so a token from a log or a backup is useless.

Installation and uninstallation

Installing creates:

  • the directory private://backup_migrate/drowl_upsi,
  • the Backup and Migrate destination drowl_upsi (directory, unlimited retention),
  • the Backup and Migrate settings profile drowl_upsi (gzip, no data for cache_*, search_api_db_*, cachetags, semaphore, sessions, watchdog).

Existing destination or profile entities with these IDs are reused.

Uninstalling removes the protocol table. The destination, the profile and all backups are kept.