Updating Thelia
This guide covers updating an existing Thelia 3 site to a newer Thelia 3 release. How long each series receives fixes is on Release cycle and support.
Thelia 3 cannot update a Thelia 2 database in place. The updater refuses any database below
3.0.0, and moving a 2.x shop to 3.0 is a guided migration. Follow
Migrating from Thelia 2.
Before you start
Back up your files and your database. mysqldump is enough for the database:
mysqldump -u <user> -p <database> > backup.sql
Read the release notes of the version you move to, and the matching page in
Notes for each version. A release can change behaviour a shop
relies on, and a module or a template you depend on may need its own bump in
composer.json.
If the shop runs background workers, stop them before you start and restart them at the end, as described in Deploying.
1. Update the code
A project installed with composer create-project thelia/thelia-project depends on
thelia/thelia-skeleton, which brings in the core packages and the themes. Updating it pulls
the whole set:
composer update thelia/thelia-skeleton --with-all-dependencies
To move the packages one by one instead, name them explicitly. thelia/core, thelia/setup
and thelia/config are the core, and the themes follow it:
composer update thelia/core thelia/setup thelia/config thelia/flexy \
thelia/backoffice-default-twig-template thelia/email-default-template \
thelia/pdf-default-template --with-all-dependencies
Drop from the list any theme your project does not use, and add the themes you replaced them with.
2. Update the database
A release can ship an SQL script that alters the schema, so new files on an old database
will break. Run the update script from the root of your project. thelia/setup installs
under local/, so the script is at local/setup/update.php:
php local/setup/update.php
It starts by removing the compiled container and the generated Propel models of the release
you are leaving, so the new schema is the one it reads. There is nothing to purge by hand
beforehand. From 3.2, the script also purges var/cache/<env> and var/propel/<env> itself,
accepts -n or --no-interaction, and exits with code 0 when the database is already up to
date. It then reports the version it starts from and the one it moves to, and applies
each database migration in order. Several versions at once are applied in a single run. The
script offers to back the database up first and restores that backup if a migration fails; on
a large database, take the manual mysqldump above instead.
The script writes that backup to local/backup/update.sql: the whole database, customers
included. Keep it out of version control. Projects created from thelia/thelia-project 3.2.2
ignore it; in an older project, add these lines to .gitignore, the first one for the JWT keys
bin/install writes:
/config/jwt/*.pem
/local/backup/*
!/local/backup/.gitkeep
The web server user often owns var/cache/<env> and var/propel/<env>. From 3.2.1, when the
script cannot delete some of their files, it moves the directory aside
(var/cache/<env>.previous-…), where nothing loads it, prints the command that deletes it as
its owner, and goes on. When it cannot even move the directory, it stops with code 8 before
touching the database and prints that command: run it, or run the script as the web server
user, then start again.
This does not cover a shop that keeps serving requests during the update: the web server can
recreate var/cache/prod between the move and the boot, and the script then dies before
touching the database (#4055). Until that is
fixed, put the shop in maintenance or stop the web server while update.php runs, or run it
as the web server user.
thelia:install on an existing shopThat command is the initial installer, not a migration tool. It replays thelia.sql, which
starts by dropping every table.
3. Rebuild the cache
Do not run cache:clear in production: it empties the cache without rebuilding it, and the
first request then compiles it under load. Remove the compiled cache and the Propel runtime,
then warm the cache back up:
rm -rf var/cache/prod var/propel/prod
php Thelia cache:warmup --env=prod
In development, var/cache/dev and var/propel/dev are the ones to remove.
Do not skip the warmup. The production kernel does not build the LiveComponent template map on demand, and every back-office page that renders a live component returns a 500 without it.
4. Rebuild the assets
Composer reinstalls the template packages, so whatever they had compiled is gone. Rebuild the assets:
php Thelia importmap:install
php Thelia tailwind:build
php Thelia sass:build
The first two rebuild the front-office assets, the last one the back-office stylesheet. Skip any command the console does not carry: each comes from a package the corresponding template requires.
In production, also run php Thelia asset-map:compile. It writes the files served from
public/assets/, with the minified CSS and the precompressed .br, .zst and .gz copies.
Install brotli (and optionally zstd) on the machine that runs it to get those formats, and
see Nginx configuration for the
server side.
5. Update the modules
Modules keep their own version numbers, so they update separately:
composer update thelia/module-name
Then let Thelia compare the version in module.xml with the one stored in the database and
run the module's own update() method:
php Thelia module:refresh
Then rebuild the cache as in step 3, workers stopped.
Notes for each version
Each release can ask for something the generic procedure above does not cover: a setting to change, a module to bump, a behaviour that moves. Read the page for every minor version you cross, in order:
- Updating from 3.0 to 3.1, patch releases 3.1.1, 3.1.2, 3.1.3 and 3.1.4 included.
- Updating from 3.1 to 3.2, patch releases 3.2.1 to 3.2.5 included.
- Updating from 3.2 to 3.3: the background jobs, the AI layer, behaviour changes and constructor changes for modules.
- Updating from 3.3 to 3.4: a long database script, new rights to grant, scheduled tasks, new settings and the prices that change.
Recommendations
- Back up your database before updating.
- Test the update on a staging environment first.
- Review the release notes for behaviour and breaking changes.
- Update only modules that are compatible with your Thelia version.