Updates

Total CMS includes a built-in update system that checks for new versions and applies them with minimal downtime.

How Updates Work

  1. Total CMS periodically checks the license server for new versions (cached for 24 hours)
  2. When an update is available, a notification appears in the admin dashboard
  3. You can apply the update with one click or via the CLI
  4. During the update, the site briefly enters maintenance mode
  5. The previous version is backed up for rollback if needed

Updates only replace the application files (tcms/). Your content in tcms-data/ is never touched.

Checking for Updates

Dashboard

Go to Utilities > Update Manager to see your current version and check for available updates. Click "Check for Updates" to force a fresh check.

CLI

# Check for available updates
tcms update:check

# JSON output for scripting
tcms update:check --json

Applying Updates

Dashboard

  1. Go to Utilities > Update Manager
  2. Review the available version, severity, and changelog
  3. Click "Update to X.X.X"
  4. Confirm the update
  5. Wait for the update to complete — the page reloads automatically

CLI

# Apply the update (interactive confirmation)
tcms update:apply

# Skip confirmation
tcms update:apply --force

# JSON output
tcms update:apply --json

Update Process

When an update is applied:

  1. The update zip is downloaded from the update server
  2. The zip is verified as a valid archive
  3. The site enters maintenance mode — visitors see a "Updating..." page
  4. The current application directory is backed up (e.g., tcms.backup-3.2.2-20260410-143022/)
  5. The new files are extracted into place
  6. All caches are cleared
  7. Maintenance mode is disabled
  8. The update is logged to tcms-data/.system/logs/totalcms.log (channel update)

The entire process typically takes a few seconds.

Maintenance Mode

During an update, non-admin visitors see a static "Updating Total CMS" page with a 503 status code. The page auto-refreshes after 10 seconds.

Admin routes continue to work during maintenance so the update action can complete.

Rollback

If an update causes issues, you can roll back to the previous version:

CLI

# Roll back to the previous version
tcms update:rollback

# Skip confirmation
tcms update:rollback --force

Rollback restores the backup directory that was created during the update. Only the most recent backup is available.

Manual Rollback

If the CLI isn't working after a failed update, you can manually swap directories:

# From the parent directory of your tcms installation
mv tcms tcms-failed
mv tcms.backup-3.2.2-20260410-143022 tcms
php tcms/resources/bin/tcms cache:clear

Version Severity

Updates are classified by severity:

  • Patch (e.g., 3.2.1 → 3.2.2) — Bug fixes and minor improvements. Safe to apply immediately.
  • Minor (e.g., 3.2.x → 3.5.0) — New features and enhancements. Review the changelog before applying.
  • Major (e.g., 3.x → 4.0) — Significant changes that may require attention. Read the upgrade guide.

Troubleshooting

"Already up to date" — The update check is cached for 24 hours. Use tcms update:check to force a fresh check from the CLI.

Update download fails — Verify the server can make outbound HTTPS connections to license.totalcms.co. Check firewall rules and DNS resolution.

Update fails mid-process — The previous version is automatically backed up before the swap. Use tcms update:rollback or manually restore the backup directory.

Site stuck in maintenance mode — The maintenance flag is at cache/maintenance.flag. Delete it manually: rm cache/maintenance.flag

Permission errors during update — The PHP process needs write access to the application directory to perform the swap. Check file ownership and permissions.

Version-Specific Upgrade Notes

Route shapes are stable across patch releases, but new minor versions occasionally consolidate endpoints or rearrange storage paths. Review the notes for any version you skip over.

3.2 → 3.5

3.5 consolidated several namespaces. The changes below are not auto-rewritten in your own templates, scripts, or WAF rules — review each.

Content APIs moved under /api/. Every content endpoint that used to live at the root (/collections/..., /schemas/..., /upload/..., /cache/..., /report/..., etc.) now lives under /api/{same path}. Update API clients, integrations, and webhook URLs.

A few previously-API endpoints intentionally moved out of /api/ — /sitemap, /feeds, ImageWorks download/ and stream/ — because they're public-facing surfaces that don't fit the API auth/CORS model.

Auth routes moved under /admin/. Login, logout, register, forgot-password, and reset-password endpoints used to live at the root. They now live under /admin/ (e.g. /admin/login, /admin/logout, /admin/register/{collection}). Update any custom login forms or links that posted to the old paths.

Twig {% include %} paths now need a templates/ prefix. The Twig loader for stored templates was re-rooted from tcms-data/templates/ to tcms-data/builder/ so it can resolve both designer templates and Site Builder templates from one loader. Includes that used to resolve relative to the old root must add the new subdirectory:

{# 3.2 #}
{% include 'header.twig' %}

{# 3.5 #}
{% include 'templates/header.twig' %}

Templates referenced inside a collection schema's template field, or rendered through the public-API template parameter, follow the same rule.

Whitelabel templates must live under whitelabel/. During the upgrade, T3 migrates tcms-data/templates/* into tcms-data/builder/templates/*, except for files already under a whitelabel/ subfolder, which move to tcms-data/builder/whitelabel/*. If you had whitelabel overrides saved outside that subfolder, the auto-migration won't pick them up — open them in the admin Templates UI and re-save under the whitelabel/ folder so they take effect against the whitelabel chrome.