# Akeneo best practices

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](../../platform/hosts/services.md) 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](#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:

```ini
[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:

```bash
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](../../technologies/system-services/manage-user-services.md#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](../../technologies/system-services/manage-user-services.md).

## 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](../../concepts/performance-tuning.md) 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](../../platform/hosts/backups.md). The search index can be rebuilt from the database if needed.
- **Watch [Health](../../platform/hosts/health.md)** 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.

## Related

- [Deploy Akeneo](deploy.md)
- [Troubleshooting Akeneo](troubleshooting.md)
- [How to manage user system services](../../technologies/system-services/manage-user-services.md)
- [Services](../../platform/hosts/services.md)
- [Performance tuning](../../concepts/performance-tuning.md)