SIGNALS Docs
Reader View

Updates

Update a self-hosted installation from the CLI with verified backups and journaled recovery.

Self-hosted updates

Self-hosted updates run from the server CLI. Admin → System → Updates (/admin/settings/system) remains owner-only and shows the durable journal status and CLI instructions. Web install actions return 404 while SIGNALS_WEB_UPDATER_ENABLED=false (the default); web installation is not a supported self-hosted update path. Signals Cloud installations are updated for you.

Run as the user that owns vendor/, composer.lock and storage/. Put PHP, Composer, pg_dump, pg_restore and psql on its PATH. These self-host commands refuse Cloud mode. Use PostgreSQL client tools supported by the server version (prefer matching major versions). Recovery reads the live server version and neutralises the generated transaction_timeout setting on PostgreSQL 15/16 before restoring; PostgreSQL 17+ keeps it. Provision space for a complete database dump, and verify access to repo.packagist.org. A CLI update does not need a queue worker to execute the updater.

php artisan signals:update --check
php artisan signals:update
# Or select a published stable release:
php artisan signals:update --to=X.Y.Z

The command lists installed and published stable releases and asks for confirmation. --force skips that prompt; --no-refresh uses cached release metadata. --check exits 0 when an update is available and 1 when current. Read release notes for every intervening version and check plugin version support first.

Backup and update phases

Every update takes a backup, including updates whose source checkout has no pending migrations: the target's migrations cannot be inventoried before installing its code. The updater:

  1. Validates the target release and protected-data key readiness, then starts the durable journal.
  2. Enables maintenance mode, then runs pg_dump -Fc, encrypts the nonempty archive into storage/app/update-backups/{operation_id}.dump, decrypts it to a private temporary file for pg_restore --list verification, and saves the path as backup_reference. It preserves the source composer.lock and composer.json beside the dump, with .composer.lock and .composer.json suffixes. Backup metadata records host, port, database, application schemas, username, migration rows and extension versions in the durable journal; it contains no database password. The files are mode 0600; credentials are passed through process environment variables, not command arguments.
  3. Installs the release with Composer, runs migrations, clears caches and restarts queue workers. Every post-Composer command runs in a fresh PHP process.
  4. Runs signals:update:readiness in a fresh process. All application and package migrations must have run, and SystemHealthService::checkReadiness() must pass its database, Redis and queue probes. Boot failures fail the gate too. migrate:status alone is insufficient.
  5. Runs artisan up only after the gate passes, then marks the journal completed.

The migration step automatically registers missing scan identities for existing assets in the database being updated. A collision skips that asset and records a warning plus an asset.scan_identity_backfill_skipped audit entry; the update continues. Resolve the conflicting asset number or barcode using the asset ID and label in that entry, then run if the migration reported collisions:

php artisan signals:scan-identifiers:backfill --no-interaction

Run the repair against each affected tenant database after its migrations. It is safe to repeat and returns a nonzero exit code while conflicts remain. Retired labels remain reserved to their original owner, so choose a distinct label for another asset. No historical asset values or money are changed by registration.

A failed backup aborts before Composer or migration mutations and leaves maintenance on. Correct the backup failure and use signals:update:recover --resume. An operator can explicitly accept the risk with signals:update --without-backup; the journal records backup_waived=true and terminal output records the waiver. --force alone never waives backups. Recovery preserves the original waiver and never invents a replacement snapshot after mutation.

Stop in-flight queue workers, scheduler tasks and other writers before starting the update; maintenance mode prevents new application requests and normal queue consumption but does not cancel already running work. Dump, verification and transactional restore use SIGNALS_UPDATE_BACKUP_TIMEOUT (seconds, default 21600 / six hours; 0 means no deadline). Allow space for both the archive and temporary restore SQL; temporary files are private and removed after each attempt.

The connection's search_path must list explicit application schema identifiers, such as public or public,app_data. Dynamic entries such as "$user", quoted names and wildcard patterns are refused; correct the connection configuration before updating. Only those listed schemas are backed up and eligible for automatic restore.

The journal and fencing lock live outside application cache, at storage/app/update-journal.json and storage/app/update.lock. SIGNALS_UPDATE_JOURNAL_PATH, SIGNALS_UPDATE_LOCK_PATH and SIGNALS_UPDATE_BACKUP_PATH can relocate them. Keep them on durable local storage with working flock. Cache clearing cannot resolve or erase recovery state. An unresolved journal blocks a new ordinary update; a live updater or surviving child blocks recovery through the same process lock.

A failed or killed update after maintenance/mutation leaves traffic held. It never automatically lifts maintenance. Keep the journal and backup; do not delete the journal, run a blind artisan up, or run migrate:rollback as a recovery shortcut.

Failed-update decision table

Start with:

php artisan signals:update:recover --status

It inspects the journal under the durable lock. An incomplete journal with a free lock is classified as an interrupted owner; an active owner or surviving child is refused. Inspect/stop any surviving process before attempting recovery again. Maintenance stays on for interrupted mutations.

Situation Safe action Traffic condition
Release validation failed before maintenance Correct the cause and start signals:update again. No update mutation has occurred; existing maintenance is not lifted.
Backup failed after maintenance started Correct the cause, inspect --status, then use signals:update:recover --resume. Maintenance remains on until the verified backup, update and readiness complete.
Composer or a later phase failed; forward repair is appropriate Repair the cause, then signals:update:recover --resume. The original target and backup are retained; completed mutation phases are skipped and an interrupted phase is retried. A completed Composer phase requires matching recorded code and migration inventory. Readiness must pass again before up.
Source code rollback is supported and no schema change occurred Reinstate the recorded source release and source lock, run composer install, and independently confirm the database schema matches the release requirements. Use the confirmed --mark-restored path only after verifying that no database restore is needed. Source lock and migration inventory must match; readiness must pass.
Schema or data changed and rollback is necessary Keep maintenance on, reinstate the recorded source release and its saved composer.lock, then use --restore below. Restore, source Composer install, cache/worker refresh and readiness must succeed before up.
Backup missing, partial migration needs investigation, or the database may not match the release signals:update:recover --hold; repair/rehearse manually before choosing a recovery path. Maintenance remains on. No blind schema rollback.

Before your first update, rehearse restoring a dump into a separate disposable database. Archive inventory verification is required by the updater; it does not replace a restore rehearsal. Preserve backups securely according to your retention policy because they contain tenant data. Automated pruning keeps the protected recovery archives described below.

Restoring a recorded backup

Restoring loses writes since the snapshot. Stop other writers first and preserve the current failed database for investigation. Reinstall the source release identified by source_version, copy its saved composer.lock and composer.json into place, and keep maintenance on. The command refuses source lock or migration inventory mismatches. Reinstating source files must not overwrite storage/ or the journal.

php artisan signals:update:recover --restore

After explicit confirmation, recovery refuses any mismatch in the recorded host, port, database, application schemas or username. It verifies the archive and extension inventory, then uses pg_restore to prepare SQL and psql --single-transaction with error-stop enabled to clear application objects, load the archive and verify that the migration rows exactly match the recorded backup. All three operations commit together; any failure rolls back the schema and data changes. Target-only objects and internal FKs are removed. Schema containers, their existing grants and installed extension objects are preserved. Application objects are recreated by the recorded database user. Grants to other roles, such as a separate reporting role, are not restored; record and reapply those grants manually. Schema-scoped dumps also exclude PostgreSQL large objects. Installations using large objects need a separate complete backup and manual restore; the application itself does not use them. Dependencies that could affect other user schemas cause refusal or rollback; other schemas and databases are never cleared. Recovery then installs the source lock with Composer, clears caches, restarts workers, and runs readiness before up. Unattended operators must explicitly supply --force to confirm the destructive restore. A failure leaves maintenance on and the journal unresolved. Restore requires the source extension names, schemas and versions to be present. Extension configuration tables inside application schemas require a manual backup/restore; automated backup refuses these installations. Original backups without recorded connection/migration metadata also require manual restoration.

For a manual restore, keep maintenance on and stop all other writers. Preserve the failed database for investigation. Read <backup>.metadata.json (or backup_metadata in the journal) before starting: record every application schema and each extension's name, schema and version. Install the matching extension packages on the PostgreSQL server first. Use supported client tools, preferably the same major version as the server; this direct manual sequence does not apply the automated recovery's PostgreSQL 15/16 SQL syntax adjustment.

The following is a worked manual restore sequence. Replace RESTORE_DATABASE, HOST and USER with the recovery connection, and /secure with an existing private directory. Supply the port through PGPORT if it is not 5432, and credentials through your protected PostgreSQL environment or password file. Use a new database; this procedure does not clear or merge an existing one. Create any additional recorded schemas before installing extensions because the TOC filter excludes all schema containers. The extension SQL below is an example inventory: btree_gist 1.8, pg_trgm 1.6 and vector 0.8.1 in public, with plpgsql 1.0 already in pg_catalog. Replace it with the backup's recorded inventory when that differs; do not substitute newer versions or ignore a mismatch.

Reinstate the original APP_KEY or SIGNALS_UPDATE_BACKUP_KEY before decrypting. Encrypted archives cannot be passed directly to pg_restore. Run this block in Bash; it stops on the first error and removes the private plaintext and TOC files on success or failure:

(
set -euo pipefail
umask 077
test ! -e /secure/restore.dump
test ! -e /secure/restore.toc
test ! -e /secure/restore.list
php artisan signals:update:decrypt-backup /secure/update.dump --output=/secure/restore.dump
trap 'rm -f /secure/restore.dump /secure/restore.toc /secure/restore.list' EXIT

createdb -h HOST -U USER --template=template0 RESTORE_DATABASE
psql -X -h HOST -U USER -d RESTORE_DATABASE --set=ON_ERROR_STOP=1 <<'SQL'
CREATE EXTENSION btree_gist WITH SCHEMA public VERSION '1.8';
CREATE EXTENSION pg_trgm WITH SCHEMA public VERSION '1.6';
CREATE EXTENSION vector WITH SCHEMA public VERSION '0.8.1';
SQL

pg_restore --list /secure/restore.dump > /secure/restore.toc
python3 -c 'import re; from pathlib import Path; source = Path("/secure/restore.toc").read_text(); Path("/secure/restore.list").write_text(re.sub(r"^\d+;\s+\d+\s+\d+\s+(?:EXTENSION\b|SCHEMA\b|COMMENT - (?:EXTENSION|SCHEMA)\b).*\n?", "", source, flags=re.M))'
pg_restore -h HOST -U USER --dbname=RESTORE_DATABASE \
  --no-owner --no-privileges --exit-on-error --single-transaction \
  --use-list=/secure/restore.list /secure/restore.dump

psql -X -h HOST -U USER -d RESTORE_DATABASE --set=ON_ERROR_STOP=1 <<'SQL'
SELECT e.extname AS name, n.nspname AS schema, e.extversion AS version
FROM pg_extension e JOIN pg_namespace n ON n.oid = e.extnamespace
ORDER BY e.extname;
SELECT id, migration, batch FROM public.migrations ORDER BY migration, batch, id;
SQL
)

The filter removes only SCHEMA, EXTENSION and their COMMENT entries, preserving the pre-created containers and extension objects. --exit-on-error --single-transaction makes the archive load atomic; do not add parallel jobs. See the PostgreSQL restore options. A failed attempt must stay held for investigation; do not continue to verification or attest success. The decrypt command refuses an existing output path and authentication failures, publishes only authenticated mode 0600 plaintext, and removes partial temporary output itself. For a plaintext archive, replace the decrypt line with a private copy to the fresh /secure/restore.dump path; retain the original backup.

Before accepting the restore, compare every returned extension name/schema/version and migration row (ID, name and batch) with the backup metadata, adjusting public.migrations to the recorded application schema if needed. Also compare recorded application row counts and monetary totals by currency, and check representative application reads against the source release. A matching migration count alone is insufficient. Reapply any required schema grants and application-object grants separately: --no-privileges does not restore them, and --no-owner makes the restoring user own application objects. Complete the restore erasure admission checklist before releasing traffic.

Reinstate the exact source release, composer.lock and composer.json, and run composer install. A disposable rehearsal does not complete recovery of the installation: arrange the database cutover so the verified restored data is available under the journal’s recorded host, port, database, application schemas and username. Merely pointing the application back at the failed database is not a restore. Only then attest completion:

php artisan signals:update:recover --mark-restored

This requires confirmation that the manual work is complete and the same source-code/readiness checks. It never applies a reverse migration. With no recorded backup (for example, a waived backup), restoration is manual only. If neither path is safe, use --hold and follow the decision table until repaired.

Update backup encryption and expiry

Automated self-host update backups are encrypted using authenticated AES-256-GCM chunks. SIGNALS_UPDATE_BACKUP_KEY supplies the dedicated key (at least 32 random bytes, optionally prefixed with base64:); otherwise the installer uses APP_KEY. Keep the original key securely outside the database backup. Each archive header and metadata record its format version and key ID. Reinstating the original key is required to restore an archive after key rotation. Composer copies and metadata remain private companion files.

SIGNALS_UPDATE_BACKUP_RETENTION_DAYS defaults to 30 and must be at least 1. After readiness passes and maintenance ends, the updater prunes expired backups and their companions. A pruning failure is reported without failing the update. Run php artisan signals:update:prune-backups --dry-run to inspect the count, then omit --dry-run to prune; --days=30 overrides retention for that run. The durable update lock prevents concurrent updates and pruning. Regardless of age, pruning keeps the current or latest completed journal backup, the preceding protected backup until a replacement has completed and verified, and the newest verifiable archive. If no archive verifies, pruning refuses without deleting anything.

Plaintext .dump archives remain readable and expire under the same rule; existing files are never rewritten in place. Verification and restore decrypt to private temporary files beside the archive and remove them even on failure. Allow disk space for the decrypted dump and restore SQL. Erased subjects remain in backup bytes until those backups are pruned. Before admitting restored data, follow the account restore erasure checklist.