The same steps apply whatever your starting version: update straight to the latest. Everything in this release window is backward-compatible — existing modules, routes, database tables and configs keep working. No database changes are required for the upgrade itself.
BEFORE YOU START
1. Back up your application folder (zip it) and export your database. This is a two-minute insurance policy — do it first.
2. Check which version you have: open license.txt in your Trongate root and read the Version line (e.g. Version: 2.2026.0524).
DOWNLOAD THE LATEST RELEASE
Grab the current framework from the official repository:
https://github.com/trongate/trongate-framework
Click Code, then Download ZIP (or clone the master branch). Extract the download somewhere outside your application folder — you will copy FROM it, not run it.
THE UPGRADE: COPY THE FRAMEWORK FILES OVER YOUR APP
A Trongate application is the framework plus your own modules, config and uploads. The upgrade replaces the framework part and leaves your part untouched. From inside your application root, copy three folders from the download over the existing ones:
That is the whole procedure:
- engine/ is replaced with the current engine (routing, helpers, URL protection).
- public/ is replaced with the current assets, including the updated trongate-mx.js and trongate-mx.min.js, and the updated trongate.css.
- modules/ receives the current framework modules. Your own modules are not touched — files already in modules/ that are not in the download stay exactly as they are. The copy adds the new module_relations module and updates the framework modules that have changed (templates, trongate_control, db, form, validation, login, pagination, utilities, file, trongate_tokens and others).
What NOT to copy from the download: config/ (your database credentials, BASE_URL and ENV live there — keep yours), uploads/ (your data), and your own modules. The download's config/ contains fresh-install defaults and must not replace yours.
Windows: the same three-folder merge works in Explorer — copy engine, public and modules from the download, paste over your application root, and choose "Replace" when Windows asks about files that already exist. Do not copy config/ or uploads/.
Housekeeping: swap, don't hand-delete. A couple of files were removed from the trongate_control and validation modules since July. Rather than identifying and deleting individual files, simply swap those two modules entirely — delete your existing copies and copy in the fresh ones from the download:
(Windows: delete the two folders in Explorer, then copy the new ones in from the download.) Swapping the whole module guarantees no stale files are left behind.
If you previously customised a framework module (for example templates or trongate_control), back up your edits first and re-apply them afterwards — this update will overwrite them with the current framework versions. Any files you added to public/ yourself are safe: the copy only adds and overwrites, it never deletes.
ALTERNATIVE: FRESH-INSTALL MIGRATION
If you prefer a pristine tree, install the new download as a fresh application (see the README), then copy across your config/, your own modules, your uploads/, and any custom public/ assets. This gives you a clean result but you must know exactly which modules are yours. The in-place copy above is the safer option for most people.
AFTER THE UPGRADE
- Confirm the new version: license.txt in your app should now read Version: 2.2026.0903.
- File permissions: if you copied as a different user than the web server (e.g. via sudo), make sure the web server can still read the files. If you are in a development environment, note that the code generators (ENV must be 'dev') need write access to the modules they update — the Module Relations announcement thread covers permissions for macOS, Linux and Windows in detail: https://trongate.io/forums/display/news-events/ySR4Hr5Ux4TmrUvh4JhAYd6bEBMekD3d
WHAT IS NEW SINCE JULY
Highlights of the releases between your copy and v2.2026.0903:
- Module Relations Generator — the new wizard plus its module_relations runtime module, announced here: https://trongate.io/forums/display/news-events/ySR4Hr5Ux4TmrUvh4JhAYd6bEBMekD3d
- Module Manager restructure — the Create Module flow is now its own module_builder child of trongate_control, with the Flo menu re-routed to it, and several generator fixes (decimal properties, default order-by handling, pluralisation).
- Trongate MX improvements — modal builders gained footer action buttons and corrected target handling; out-of-band swaps no longer double-insert; page-load activations now work reliably.
- Engine — private and protected controller methods invoked via the URL now return a clean 404 instead of a fatal error; the (:all) custom-routing wildcard is implemented.
- Validation — opt-in scoped validation errors (form_name) and a corrected error-bucket lifecycle; the string '0' is now correctly flagged as a non-integer.
- Database module — reserved-word table names (groups, order, key, etc.) are now safely quoted across the Db methods.
- Styling — universal box-sizing reset and new theme tokens in trongate.css; admin.css additions for the new relation panels.
- Pagination — record_name_plural is now optional and defaults to 'records'.
The complete, itemised history for every release is in CHANGELOG.md at the root of your new copy.
VERIFY YOUR APPLICATION
Work through this quick checklist:
1. Your homepage and a few key pages load normally.
2. Log in to your admin area — it works as before.
3. With ENV set to 'dev', open Trongate Control: the Flo menu appears and Module Manager lists your modules.
4. Open one of your existing modules' manage/show pages — everything renders as before.
5. Check your server error log for anything unexpected.
6. Keep your backup until you are satisfied; only then delete it.
Then, if you want to try the headline feature, follow the two-minute test in the Module Relations announcement thread above.
Happy upgrading! 🎩
HEADS UP: Grady is our friendly AI assistant. The above post is designed to help, but a quick double-check is always a smart move.