Skip to main content
Keel Docs Showcase

Install

Keel runs on Pimcore 11 and 12 (classic admin) and Pimcore Studio (2026+). The same bundle serves both. Only the routes file differs.

1. Require the bundle

bash
composer require keel/pimcore-keel

2. Register it

In config/bundles.php:

php
return [
    // …
    Keel\Bundle\KeelBundle::class => ['all' => true],
];

3. Add the routes

Create config/routes/keel.yaml. Use one of the two lines:

yaml
keel:
    resource: '@KeelBundle/config/routes.yaml'            # Pimcore 11 or 12, classic admin
    # resource: '@KeelBundle/config/routes_studio.yaml'   # Pimcore Studio (2026+)

4. Add the licence key

Put the key in .env.local, or set it as a real environment variable on the server. Never commit it.

dotenv
KEEL_LICENSE_KEY=…

You receive the key with your Keel licence, from whoever supplied Keel to you. It is signed for your company. See Licence.

5. Install the assets and the tables

bash
bin/console assets:install public
bin/console cache:clear
bin/console pimcore:bundle:install KeelBundle   # creates Keel's tables

Keel keeps bulk jobs, completeness scores, follows, import previews and Setup → History in eight tables of its own: keel_bulk_job, keel_bulk_item, keel_completeness_rule, keel_completeness, keel_follow, keel_import_stage, keel_history and keel_history_item. bin/console keel:install-tables does the same as the install command and can be repeated on every deploy: it creates only what is missing (also columns a new version adds) and changes nothing when everything is there. The database user needs the CREATE right for this step only; nothing in a request or a save creates a table. Pimcore's bundle list shows Keel as installed when all eight tables are there with this version's columns.

Big lists (5,000 items and more) sort through database indexes that you add as a step of their own:

bash
bin/console keel:sort-indexes --dry-run   # shows what it would change
bin/console keel:sort-indexes             # adds them: one ALTER TABLE per class table

Without them everything works; sorting a big list is slower. See Console commands.

Pimcore Studio

Studio loads Keel as a plugin build. After every Keel update, run assets:install again. Studio hides the Keel tab when the installed build does not match the bundle.

6. Check it works

bash
bin/console keel:setup --check

This only checks. It asks nothing and writes nothing. Each line is one check:

  • ✔ fine
  • ! worth a look, but Keel works
  • ✖ must be fixed: Keel is not installed completely

Under a ! or ✖ line comes the fix, ready to copy. The command ends with exit code 0 when nothing is marked ✖, and 1 otherwise (handy in a deploy script).

What you should see

On a working Studio project:

text
0 · Install check
-----------------

 ✔ Keel bundle dev-main is installed
 ✔ Routes are imported under /pimcore-studio/api/keel
 ✔ Licensed to Example Ltd
 ✔ PHP extension sodium is loaded
 ✔ Scripts and the Studio build are installed and current
 ✔ Pimcore's settings store is reachable (Customize is saved there)
 ✔ Keel's database tables are there
 ✔ Sort indexes of big lists are up to date
 ✔ List search uses Pimcore's search index (Generic Data Index)
 ✔ PHP (CLI) allows uploads up to 100 MB, uploads.max_mb is 100
 ✔ keel.yaml: the classes, fields and switcher paths it names exist
 ! PHP CLI memory_limit is 256 MB: cache:clear (debug on) may need more
     After a keel.yaml change, clear the cache with:
     php -d memory_limit=512M bin/console cache:clear
 ✔ Pimcore's maintenance ran 3 min ago (it runs scheduled publishing)

 [OK] Keel is installed. Lines marked ! are worth a look, but nothing is
      missing.

Line by line

  • Keel bundle … is installed: The bundle is registered (step 2) and its version.
    If not ✔: Without step 2 the command does not exist at all
  • Routes are imported under …: Step 3, and the right file: /admin/keel for the classic admin, /pimcore-studio/api/keel for Studio.
    If not ✔: ✖ Create or change config/routes/keel.yaml as shown in the fix
  • Licensed to …: KEEL_LICENSE_KEY is set and valid; shows the customer.
    If not ✔: ✖ No key, a key that is cut off or has quotes or spaces, or a key past its grace period. ! The key ends within 30 days or is in its grace period: see When a key expires
  • PHP extension sodium is loaded: Signed licence keys need it.
    If not ✔: ✖ Enable sodium for the CLI and the web server
  • Scripts … are installed and current: Step 5. On Studio also: the installed build is the bundle's build.
    If not ✔: ✖ bin/console assets:install public and cache:clear
  • Pimcore's settings store is reachable: The database table where Customize saves.
    If not ✔: ✖ bin/console doctrine:migrations:migrate (Keel has no migrations of its own)
  • Keel's database tables are there: Step 5's pimcore:bundle:install KeelBundle or keel:install-tables.
    If not ✔: ✖ Run bin/console keel:install-tables
  • Sort indexes of big lists are up to date: whether keel:sort-indexes has something to do.
    If not ✔: ! Run bin/console keel:sort-indexes (or cache:clear when sort_indexes.on_cache_warmup is on)
  • List search uses …: Whether the Generic Data Index is there.
    If not ✔: ! Fine for small lists. Install the index, or set search.index: off to hide the line
  • PHP (CLI) allows uploads up to …: PHP's upload_max_filesize and post_max_size against uploads.max_mb.
    If not ✔: ! Raise both PHP values, or lower uploads.max_mb. The web server's PHP can differ from the CLI.
  • keel.yaml: the classes, fields and switcher paths it names exist: Class names in urls, assignments and collections; status fields; {scope} in scope.paths.
    If not ✔: ! One line per problem, naming the key, e.g. keel.urls.Product: there is no class Product
  • PHP CLI memory_limit …: With debug on, cache:clear can need more than 256 MB.
    If not ✔: ! Use php -d memory_limit=512M bin/console cache:clear
  • Pimcore's maintenance ran … ago: When pimcore:maintenance last started. Scheduled publishing happens only when it runs.
    If not ✔: ! It has not run for over two hours (or not in the last day): set it up as described in Pimcore's maintenance

Pimcore's maintenance

Pimcore's maintenance job must run regularly. It publishes and unpublishes items at the times planned with Schedule… in Keel's editor and in Pimcore's Schedule tab (Scheduled publishing), and it does Pimcore's own clean-up. Without it, planned changes never happen; the Schedule panel then warns editors.

Run it every 5 minutes, and keep a queue worker running for the jobs it sends:

bash
# crontab of the web server user
*/5 * * * * cd /var/www/html && php bin/console pimcore:maintenance

# a long-running worker (supervisord, systemd, …), as in Pimcore's own setup
php bin/console messenger:consume pimcore_core pimcore_maintenance pimcore_scheduled_tasks pimcore_generic_execution_engine

Keep pimcore_generic_execution_engine last: Keel's bulk jobs run there (bulk.transport), and a long job must not hold up the other queues.

With Pimcore's Docker images, a supervisord program can repeat it instead of cron:

ini
[program:maintenance]
command=bash -c 'sleep 300 && exec php /var/www/html/bin/console pimcore:maintenance'
autostart=true
autorestart=true

bin/console keel:setup --check shows when maintenance last ran.

7. Open it

Reload the admin. Keel opens as the first tab. It can be closed, and reopened from its entry in the left menu.

You should see the Overview with one list per data object class in the menu. If you see License required or License expired instead, or no Keel tab, see Troubleshooting.

Next: first configuration with keel:setup.