Good to know

Sync existing data

If you are starting your project from a public/enterprise demo or an existing project not running on PaaS, you need to sync data from the local directories /var/ and /public/var. Afterwards, ensure you are rebuilding your classes:

./bin/console pimcore:deployment:classes-rebuild --create-classes

Logs

By default, logs are streamed to stderr. Upsun stores those logs within the /var/log/ directory. You can find more details about how to access them here.

Running commands

You should run your commands using prod env variable --env=prod, especially when you are using interactive shell.

bin/console pimcore:bundle:list --json --no-debug --env=prod

Symfony cache dir

By default configuration, Symfony cache dir is set to /app/localCache. If you would like to change that consider changing the corresponding mount in the applications.yaml.

Working with definition files

The way of working with class definitions is not specific to PaaS, it's a general thing to consider depending on the way how you want to work with class definitions no matter where you run your Pimcore instance.

Class and ClassDefinition Storage Guidelines

As with Pimcore configurations, Pimcore class definitions are also stored as PHP configuration files.
These files can be added to version control systems and deployed across different environments.

By default, both the PHP configuration files and PHP classes are written to the /var/classes directory.

To make a class definition or class read-only, you can create a copy in /config/pimcore/classes.

If you need these classes in /config/pimcore/classes to remain writable for UI editing, set the PIMCORE_CLASS_DEFINITION_WRITABLE environment variable.

In PaaS, to ensure immutable deployments, minimize confusion for developers, and keep volumes clean, the following separation rules need to be kept in mind:

Quick reference

Directory	Contains	Filesystem	Writable at runtime?	In Git?
/config/pimcore/classes	Class definition files (.php config)	Immutable (read-only)	No (unless PIMCORE_CLASS_DEFINITION_WRITABLE is set)	Yes
/var/classes	Generated PHP classes & DataObject directory	Mounted volume	Yes	Not recommended

Details

• Files within /config/pimcore/classes are treated as code on an immutable filesystem.
  Therefore, this directory should normally only contain class definition files, not actual class files or the DataObject directory. There are a few exceptions/cases where classes would be required under this folder, for example, if you create custom classes that extend Pimcore’s DataObject classes. In these cases, please also make sure to add "Pimcore\\Model\\DataObject\\": "config/pimcore/classes/DataObject" to the psr-4 section in the project's composer.json.

• Once class definitions are created or modified, they should be moved to /config/pimcore/classes as part of the deployment pipeline.

• If UI-based class editing is required in PaaS, consider keeping the class definitions in the /var directory instead, as it remains writable.

Note: While it is possible to store class definitions in Git under /var, this approach is generally not recommended.

Following docs are explaining in details Pimcore class definitions and environment specific configurations.

Keeping your PaaS bundle up-to-date

After updating your PaaS bundle to a newer version you also need to update the files that PaaS bundle provides. Command ./vendor/bin/pimcore-paas-install-config accepts flag --force-overwrite or -f. Use this flag with caution, as it will replace your existing files with the new versions from the PaaS bundle. Merging your existing changes with the latest changes from the PaaS bundle is a manual process. Note: Please exercise caution when updating service versions (e.g., MariaDB 10.6 to 11.4). We strongly recommend testing the update in a non-production environment first and creating a database backup immediately before deployment.

Session storage

By default, a dedicated Redis instance is used to store session data. However, you could also use MySQL as session storage for low traffic projects and to save some computing resources. The config for that is provided in config/platform.yaml. If you would like to use it, you need to uncomment it, and also set the session handler accordingly in your configuration:

    session:
        handler_id: Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler

MySQL configuration limitations

Some MySQL configuration options are not available to configure on PaaS due to technical restraints of the managed database service.

The following MySQL configuration options are not available on Pimcore PaaS:

• lower_case_table_names - This option controls how table names are stored and compared. It is not configurable in the managed MariaDB service on PaaS, but is also not required for Pimcore to function properly.
• ha_archive - This archive storage engine option is not configurable in the managed database environment.

These limitations are inherent to the managed database service architecture and ensure system stability and security. Most Pimcore applications will work correctly without these specific configurations, but you should be aware of these differences.

Pimcore Studio config

Pimcore Studio configuration has been included in Pimcore PaaS. When you kickstart a project which includes Pimcore Studio, to avoid collisions, Pimcore Studio specific config in the config/config.yaml should be removed.

RabbitMQ Management UI

RabbitMQ offers a management plugin with a browser-based UI. You can access this UI with an SSH tunnel.

To open a tunnel, follow these steps.

SSH into your app container with a flag for local port forwarding:

ssh $(pimcore-cloud ssh --pipe) -L 15672:queue.internal:15672

Open http://localhost:15672 in your browser. Log in using the username and password from the relationship (usually guest/guest).

For more information, see the RabbitMQ Management Plugin documentation.

ImageMagick Policy Configuration

For improved performance, security and resource management, Pimcore PaaS includes a default custom ImageMagick policy file at .magick/policy.xml. This file restricts the formats and resources available to ImageMagick, which is used for image transformation tasks.

Default policy includes the following settings:

• Format Restrictions: Only specific image formats such as PS and EPS are added to the default list for read and write operations.
• Resource Limits: Memory, disk, file, and thread usage are capped to prevent excessive resource consumption:
  • Memory: 256MiB
  • Disk: 1GiB
  • Map: 512MiB
  • Open files: 256
  • Threads: 2
  • Operation time: 120 seconds

You can review or adjust these settings in .magick/policy.xml if your project has special requirements. For more details on ImageMagick policy configuration, see the official documentation.