webksde / drowl_upsi
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
Type:drupal-module
pkg:composer/webksde/drowl_upsi
Requires
- drupal/backup_migrate: ^5.1
Requires (Dev)
- davidrjonas/composer-lock-diff: ^1
- drush/drush: ^13 || ^14
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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--urinoroptions.uriindrush.ymlis needed. On multisite installations--uriis still needed to select the site. system.site:mailmust be set (sender of the mails).A composer update history in
<composer-root>/log/composer-update-history.md(the directory ofcomposer.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, alsodate -Iseconds), and the English or German output ofdatewithout 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]
- 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 variablesDROWL_UPSI_OPERATORandDROWL_UPSI_PASSWORD. There is no command line option, and the password should never be typed on the command line either (shell history); set it withread -rs DROWL_UPSI_PASSWORD && export DROWL_UPSI_PASSWORD. Failed attempts only log the e-mail address if it is a valid address. - Lock, preflight (see below).
- 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.
- New run: run ID, token, start time.
update_check: list available updates, security updates first (red). Informative only.url_check: every URL must return exactly 200, otherwise abort.config_export:drush config:export -y.git_commit:git add -Aand 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.gitignorebefore pushing.backup: database backup "BEFORE".maintenance_mode: enable maintenance mode, clear the page cache.mail: show recipients, ask, send the start mail.- 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.
- Lock, preflight.
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.git_commit_composer: commit "DROWL Updateservice #ID: composer update".updb:drush updatedb -y. Abort on error.config_export.git_commit_config: commit "DROWL Updateservice #ID: database updates and config export".backup: database backup "AFTER".cache_rebuild:drush cache:rebuild.locale_update:drush locale:checkandlocale:update(only if locale is enabled; errors are warnings).requirements_check: errors of the status report (informative only).url_checkwith maintenance mode bypass. On failure: abort (default), retry or continue.update_check: remaining updates.module_count: active modules / included modules.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.mail: question for the success mail. If declined: question for a notice mail with a single-line note (empty input: no mail).- 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.
| Check | Result |
|---|---|
| Directory is a git repository | Error |
| Current branch (detached HEAD) | Warning |
| Private file system (including the backups) ignored by git, if inside the repository | Error |
Private file system, backup destination and profile drowl_upsi | Error |
Base URL (site_url) set | Error |
Drush URI (--uri) differs from site_url | Warning |
system.site:mail set | Error |
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
| Command | Alias | Description |
|---|---|---|
drowl_upsi:start [--no-mail] | upsi-start | Start, see above |
drowl_upsi:finish [--no-mail] | upsi-finish | Finish, see above |
drowl_upsi:status | upsi-status | Active run, duration, maintenance mode, module count |
drowl_upsi:abort | upsi-abort | Abort the active run |
drowl_upsi:preflight | Run all preflight checks without changing anything | |
drowl_upsi:url-check | Check 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 VALUE | Change 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-count | Active 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)
| Key | Description |
|---|---|
site_url | Base URL of the site (required), e.g. https://www.example.com |
recipients | Customer e-mail address(es) (contract) |
module_limit | Number of modules included in the Updateservice (contract) |
urls | URLs to check, must return 200 (contract) |
bcc | BCC recipients, also used by mail-test |
reply_to | Reply-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.
| Variable | Content |
|---|---|
site_name, site_url | Site name and absolute front page URL (based on the site_url setting) |
changes | Production 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_date | Date of the last of these entries |
module_count, module_limit | Active modules and included modules |
module_limit_exceeded | Whether the limit is exceeded |
backup_before, backup_after | Whether the backup steps are enabled |
start_date, finish_date | Start and end of the run |
reply_to | Reply-To address |
note | Note 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 forcache_*,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.