Deploy and Update TruCMS

How a TruCMS site comes to life, how your own code reaches it, and what happens when the site owner installs a core update. Knowing this keeps your plugin's data and files safe across all three.

Installation is done in the browser

TruCMS is always installed through its built-in web installer; there is no supported command-line installation. Until APP_INSTALLED is true, every request is redirected to /install/pre-installation. The installer then:

Checks the serverPHP version, extensions and writable folders.
Verifies the purchaseThe licence is registered with the vendor service.
Configures the siteWrites the database connection, runs the migrations and seeders, creates the administrator account, generates the application key, links storage and writes the site name, URL and mail sender to .env.
CompletesSets APP_INSTALLED=true and optimises the application.

Step-by-step instructions for site owners, including server preparation and cron, are in the end-user installation guide that ships with TruCMS. The installer writes production values (APP_ENV=production, APP_DEBUG=false); on a development copy, switch them back in .env afterwards and run php artisan optimize:clear.

What must keep running

Process	Why
`php artisan schedule:run` every minute (cron)	Bound-section refresh, Booking intent cleanup and calendar renewals, TruCommerce stock holds and intent expiry, and your plugin's scheduled tasks
A queue worker, only if the site uses a real queue	With the default `sync` connection there is nothing to run. If an owner picks Database, Redis, Beanstalkd or SQS, a worker (`php artisan queue:work`, supervised) must run or queued mail and syncs never happen

Deploying your own changes

When you deploy code to a site you manage (a custom plugin, a child theme, a fix), follow the same order every time:

terminal — on the server, from the project root

php artisan down --secret="choose-a-token"     # or Settings > Maintenance
# copy the new code (git pull, rsync, upload ...)
composer dump-autoload --optimize                # picks up new or renamed module classes
php artisan migrate --force
php artisan optimize:clear
php artisan dotartisan:optimize                   # caches config and routes, compiles views
php artisan up

Run composer install only when you changed PHP dependencies; a plugin that needs extra Composer packages must say so in its installation notes.
Build front-end assets before deploying (npm run build locally or in CI) and deploy public/build; most servers that run TruCMS have no Node.
If the build changed Echo's styles, regenerate the theme CSS afterwards (Theme options → Advanced).
If you changed template-library sources, run the template seeders again; they are idempotent: php artisan db:seed --class=PageTemplatesSeeder (and the module's *PageTemplatesSeeder).
Installing a plugin through the Plugin Manager instead? See Package, install and update for the extra autoload and migration steps.

Core updates and patches

Site owners update TruCMS from the admin (Updates and Patches, permissions manage updates and application operations). App\Services\UpdatesManager handles both:

Checks the vendor service for a newer version or a patch for the installed version.
Downloads the package and extracts it over the installation (the project root).
For full updates, runs resources/cleanup.php when the package contains one (to remove obsolete files).
Runs the update pipeline: optimize:clear and dotartisan:optimize, migrate --force, rebuilds the theme manifest cache, writes the new version to .env and settings, optimises again and clears the update notice.

Updates overwrite core files

Anything shipped by TruCMS is replaced on update: app/, config/, routes/, resources/themes/echo, resources/themes/admin and the bundled modules in Modules/. Edits there are lost. Your plugin in its own Modules/{Name} folder, a child theme in its own folder, settings, theme options and the database survive. This is the practical reason for the "use hooks, not edits" rule.

The update does not run seeders. If a release adds permissions your plugin depends on, ship them in a migration so migrate --force picks them up.

Making your plugin update-safe

Keep every file inside your module folder (and, for a theme, inside your theme folder).
Declare the versions of other plugins you need in requires so activation fails clearly if an update removes or changes them.
After a core update, run your plugin's tests against the new version before updating production sites.

Caches after any change

You changed	Then
PHP code, routes or config on a site with cached config/routes	`php artisan optimize:clear` (then `dotartisan:optimize` in production)
`.env` by hand	`php artisan optimize:clear`
A `theme.json`	`php artisan theme:refresh-cache`
Echo's Sass, after a build	Regenerate the theme CSS
Content seen through the full-page cache	Nothing if invalidation is wired; otherwise Settings → Cache or `php artisan responsecache:clear`