Skip to main content
Keel Docs Showcase

Upgrading Keel

After every Keel update

bash
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:clear finishes, Keel tells the running workers to stop after their current message, the same as bin/console messenger:stop-workers. The output shows Keel: 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-workers at 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 a cache:clear, or on the first deploy of this Keel version (the old code runs that cache:clear).
  • Workers must restart by themselves. Check that your supervisord program has autorestart=true, or that your systemd unit has Restart=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:

bash
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:

bash
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.