Upgrading TAS 5.19 to 5.21 – Guide for DevOps

Technical procedure for upgrading a customer instance from 5.19 to 5.21 for DevOps and administrators: preparation, the upgrade procedure, infrastructure changes and rollback.

Summary

The upgrade from 5.19 to 5.21 adds a third backend process (queue), and the database migrations are one-way. The only way back is restoring from a backup. Therefore: backup, a dress rehearsal on a copy of the production DB, and only then production.

What DevOps must always do:

1. Add a queue container (or service) with the same image and env as the backend, command npm run start:queue.
2. Run the migrations (npm run mig).
3. Install the 5.21 versions of the plugins. A plugin for 5.19 will not load.
4. After startup, hand the instance over to the consultant, who runs validation.checkMigration() and fixes the template code.

The other changes are in the Infrastructure changes section. For each one, the Relevant if… column states when it applies to you. If it does not apply to you, skip it.

Before the upgrade

• Plugins: list the installed plugins and their versions (Administration → Plugins). You must have a 5.21 version of each one, and a rebuilt version of each custom plugin. Relevant if the customer has any plugin installed.
• Dress rehearsal on a copy: before production, upgrade a copy of the production DB and measure how long the migrations take. Plan the downtime accordingly. During the dress rehearsal, the consultant runs validation.checkMigration() and fixes the templates, so on production they only need to check.

Upgrade procedure

From 5.21, three backend processes run from the same image: backend (npm run start), cron (npm run start:cron) and the new queue (npm run start:queue). Without the queue process, service operations, archiving, manager rights synchronization and image processing wait indefinitely.

1. Announce the downtime and turn on maintenance mode. Crons now do not run in maintenance mode.
2. Stop the backend, cron and frontend.
3. Take a full backup of the database and storage (DMS, shared files, plugins). Verify that the backup can be restored.
4. Adjust the env according to the Infrastructure changes section. For the migration run, temporarily increase TAS_DB_REQUEST_TIMEOUT (the default 120 s is not enough for large tables) and, on MSSQL, also TAS_DB_LOCK_TIMEOUT.
5. Add a queue container with the same image, env file and network as the backend, only with the command npm run start:queue. Docker example (adjust the names to your installation):

   docker run -d --name tas-backend-queue \
     --restart unless-stopped \
     --network TAS \
     --env-file /opt/tas/config/tas-backend.env \
     <backend image>:5.21 \
     npm run start:queue

   After startup, the container log contains the line Background process running as queue.
6. Deploy the 5.21 image and run the migrations: npm run mig. Wait for the message Migration tool finished successfully.
7. If the migration fails, restore the backup. Do not run 5.19 or 5.21 on a partially migrated DB.
8. Reset the timeouts to their usual values and start the backend, cron, queue and frontend.
9. Install the 5.21 versions of the plugins.
10. Perform the manual steps from the Infrastructure changes section that apply to you (e.g. MS Graph).
11. Turn off maintenance mode and hand the instance over to the consultant.

Infrastructure changes

The first two rows apply to every installation. For the others, check the Relevant if… column, and skip the item if it does not apply to you.

Processes and runtime

Environment variables

Custom fonts

Consultants can now upload custom fonts for prints themselves in Administration → Shared files → Fonts. Nothing is required from DevOps.

Mail via MS Graph

Convert the configuration of the old MS Graph crons into a connection in Email processing. The new Email processing cron is not created automatically on an upgraded DB.

Relevant if TAS reads or sends mail via Microsoft 365 (MsGraph* crons).

1. In the service console, run sys.mail.migrateMsGraphToNewEmailStuff(). It prints a preview and changes nothing.
2. If the preview is correct, run sys.mail.migrateMsGraphToNewEmailStuff(true).
3. Create and activate the Email processing cron and delete the old MsGraph* rows.
4. Secret values (client secret) must be references to the vault.
5. Verify incoming email in Administration → Email ledger.

exposeDb with an external database

Relevant if the exposeDb plugin reads from a database other than the TAS one.

The migration rewrites the knex block in the configuration to externalDb. After the upgrade, check that the plugin configuration contains externalDb and the client mssql or postgresql. If a query returns UNMIGRATED_DB_CONNECTION, fix the configuration manually.

After the upgrade

The technical check takes about 15 minutes and is done right after startup, before handing over to the consultant.

• GET /status/liveness responds on the backend, cron and queue.
• GET /queue/workflow/get-workers returns running workers.
• Administration → Plugins: no plugin is in an error state ("Incompatible plugin version").
• Administration → Crons: crons are running and none reports "not found in cron container" (old MS Graph crons).
• A test service operation or archiving completes. If it hangs, the queue process is not running.
• Login works through every authority in use (password, LDAP, SAML, Entra ID, SSO).
• Printing to PDF and DOCX conversion succeed (this verifies LibreOffice and Chromium).
• In the migration log, go through the lines [Migration20260722184302] (task forms to review), [Migration20260817182114] (skipped parts of the diagram), unresolved dynamic table references and discontinued custom dynamic lists, and pass them on to the consultant.

Handover to the consultant

The consultant runs validation.checkMigration() in the service console and fixes the template code according to the guide for consultants. Give them the excerpt from the migration log and the list of items from this article that applied to the instance (plugins, MS Graph).

Rollback