Akeneo best practices

Tune Akeneo PIM on TurboStack for performance and stability - Elasticsearch index, job queues, Redis, OPcache, production mode and right-sized resources.

Akeneo PIM combines a Symfony web application, a MySQL catalog, a mandatory search index, and a set of background job queues. Performance and stability depend on keeping those components healthy and right-sized. This page covers what TurboStack already configures for you and the additional optimizations worth applying.

What TurboStack configures for you

When you deploy with app_type: akeneo, the platform sets up the full runtime so you do not have to wire it together manually:

Production build. The role installs Akeneo with make prod and APP_ENV=prod, which compiles assets and Symfony's cache for production rather than running in debug mode.
Background job queues. Three systemd job-queue consumers run continuously per app so imports, exports and maintenance tasks are processed: pim-job-queue@ui_job, pim-job-queue@import_export_job and pim-job-queue@data_maintenance_job. They run as user services with Restart=always.
Search index. The app is wired to Elasticsearch/OpenSearch via APP_INDEX_HOSTS (default localhost:9200). Akeneo cannot run without it - the product and catalog index lives there.
Database. A dedicated MySQL database and user are provisioned and injected through .env.local.
Nginx vhost. An Akeneo-tuned vhost serves the public/ front controller with a long fastcgi_read_timeout (1200s) for heavy operations, and blocks direct access to any other PHP file.
PDF/export dependencies. System packages Akeneo needs for rendering Portable Document Format (PDF) files and exports (ghostscript, aspell) are installed for you.
Log rotation. Akeneo's var/logs/*.log files are rotated automatically via logrotate.

Recommended optimizations

Apply these on top of the defaults - most are toggled on the host's Services tab.

Keep Elasticsearch/OpenSearch healthy. It is the heart of the PIM. After large catalog changes, reindex with bin/console pim:product:index and pim:product-model:index.
Enable Redis for caching and sessions to take load off MySQL and speed up the UI.
OPcache keeps compiled PHP in memory - confirm it is enabled for your PHP version for a large throughput win.
Stay in production mode. Never switch the app to dev/debug on a live host; rebuild with make prod after upgrades.
Scale the job queues for catalogs with frequent imports/exports by running additional queue consumers so jobs do not back up. See Background job queues for the service unit and how to manage it.
Optimize media. Use a Content Delivery Network (CDN)/HTTP cache in front of generated product images and assets to reduce origin load.
Schedule maintenance (index refreshes, cleanup jobs) during off-peak hours through the data maintenance queue.

Background job queues

Akeneo processes imports, exports and maintenance tasks through background job queues. TurboStack installs three queue consumers as systemd --user services per app and keeps them running with Restart=always:

pim-job-queue@ui_job - jobs started from the user interface.
pim-job-queue@import_export_job - imports and exports.
pim-job-queue@data_maintenance_job - cleanup and maintenance jobs.

Each service is an instance of one template unit at ~/.config/systemd/user/pim-job-queue@.service. The name after @ is the queue the consumer reads:

[Unit]
Description=Akeneo PIM Job Queue Service (#%i)
After=network-online.target
Requires=dbus.socket
StartLimitIntervalSec=0

[Service]
Type=simple
WorkingDirectory=%h/akeneo
ExecStart=%h/akeneo/bin/console messenger:consume --env=prod %I
RestartSec=10s
Restart=always

[Install]
WantedBy=default.target

%i is the queue name, so one template serves every queue; %h is your home directory.
--env=prod runs the consumer against the production environment.
Adjust WorkingDirectory to match your app path if it differs.

Manage a consumer like any other user service:

systemctl --user status pim-job-queue@import_export_job
systemctl --user restart pim-job-queue@import_export_job

When a busy queue backs up, run more consumer processes for it, but keep the total within the host's processor budget. See Scale throughput with more instances.

For the systemd --user basics - including loginctl enable-linger so the services keep running after you log out - see How to manage user system services.

Sizing and scaling

TurboStack auto-tunes resource allocations to the host. Override the defaults only when measurements justify it:

Variable	Tune when
`mysql_innodb_size`	The catalog working set does not fit in the buffer pool.
`redis_memory`	Cache eviction is frequent.
`elasticsearch_heap_size`	Akeneo is index-heavy; size this to your catalog, but keep heap at roughly half of available RAM and never above ~31 gigabytes (GB).

See Performance tuning before changing any of these, and change one variable at a time.

Stability

Back up regularly. Ensure the MySQL catalog and the application files are covered - review Backups. The search index can be rebuilt from the database if needed.
Watch Health for CPU, memory and disk pressure, and confirm the job-queue services stay running.
Keep versions current. Track Akeneo, PHP and Elasticsearch/OpenSearch releases and apply security updates.
Test on a staging clone. Validate Akeneo upgrades and large catalog imports on a copy before applying them to production.