Upgrading Keel
After every Keel update
composer update keel/pimcore-keel # gets the newest version your composer.json allows
bin/console assets:install public
bin/console cache:clear
bin/console messenger:stop-workers
bin/console keel:install-tables # new tables and columns of this version; nothing when all are there
bin/console keel:sort-indexes --dry-run # then without --dry-run: index changes big lists are waiting for
bin/console keel:setup --check
keel:install-tables also moves History entries an older Keel kept in Pimcore's settings store into the keel_history
tables (bin/console keel:history:migrate does only that; Keel also does it by itself before the first History
request). A site that skipped the step is healed by the first Keel action that needs a table, with a line in the log
asking for the step.
For a new release tag, change the version in composer.json (or run composer require keel/pimcore-keel:<version>)
first.
assets:install matters most on Pimcore Studio: Studio hides the Keel tab while the installed build does not match the bundle. --check shows it as ✖ The installed Studio build is older than the bundle's: Studio hides the Keel tab.
Then reload the admin in the browser.
Tabs that were open during the update still run the old build. When such a tab needs a part of Keel it has not loaded yet (the import, the date picker, a settings page …), that file is gone: Keel tries once more, then shows Keel was updated. Reload to continue. with a Reload button. Nothing reloads by itself, so unsaved edits stay until the user presses Reload.
Queue workers after a deploy
Pimcore's queue workers (messenger:consume, usually run by supervisord) keep the code and cache they started with.
After a deploy or a cache clear they must restart, or they can fail every search index update until someone restarts
them. List search then misses new and changed items.
- What Keel does: when
bin/console cache:clearfinishes, Keel tells the running workers to stop after their current message, the same asbin/console messenger:stop-workers. The output showsKeel: asked running queue workers to restart on the new cache. Your process manager (supervisord, systemd, …) starts them again. A cache clear from Pimcore Studio counts too. Nothing is lost: the waiting index updates stay in the queue. - What you still do: run
bin/console messenger:stop-workersat the end of every deploy. Keel cannot help when the cache folder is deleted by hand (rm -rf var/cache), when new code arrives without acache:clear, or on the first deploy of this Keel version (the old code runs thatcache:clear). - Workers must restart by themselves. Check that your supervisord program has
autorestart=true, or that your systemd unit hasRestart=always. Otherwise a stopped worker stays stopped.
Your keel.yaml keeps working
New options are always optional, and their default is how Keel behaved before. An existing keel.yaml needs no change after an update.
To see what is new, compare your file with the bundle's config/keel.example.yaml, or print every option with:
bin/console config:dump-reference keel
If an update makes a value invalid (rare), cache:clear stops with a message that names the key and the value.
After a Pimcore update, or new bricks
Check that Keel's content editor can still edit and save every content field of your pages. Nothing is saved:
bin/console keel:check-editables --all
It exits with code 1 when a field fails. See Console commands.
Customize and Reset to automatic
Customize settings are in the database, so updates do not touch them. Reset to automatic (at the bottom left of Customize) removes every Customize choice: lists, columns, statuses, start page cards, theme and assignments go back to the automatic setup and keel.yaml. The Reset to automatic inside the Statuses step resets only the list you are looking at.
Customize is per environment: choices made on staging are not copied to production.
Removing Keel
See Uninstalling Keel.
Bulk jobs on the server
Bulk changes of more than 20 items now run in Pimcore's queue worker. Check that your messenger:consume lists
pimcore_generic_execution_engine (last), or set bulk.transport to a transport it does consume. Otherwise
jobs wait with Waiting for the background worker…. The same worker writes the file of a long export (more than
export.direct_rows, 2,000 rows) and runs History reverts of more than 100 items. Their tables come from
keel:install-tables. bulk.server_jobs: false keeps the old way.