Skip to main content
Version: Next

Installation of the Studio Backend Bundle

Bundle Installation​

To install the Studio Backend Bundle, follow the five steps below:

  1. Make sure prerequisites are met:
  1. Install the required dependencies:
composer require pimcore/studio-backend-bundle
  1. Enable Firewall settings

To enable the firewall settings in your project, add the following configuration to your config/packages/security.yaml file. Keep in mind that the prefix part pimcore-studio/api can be changed to any other value in the config. You need to adapt your access_control settings accordingly.

security:
firewalls:
pimcore_studio: '%pimcore_studio_backend.firewall_settings%'
access_control:
- {
path: ^/pimcore-studio/api/(docs|docs/json|translations|user/reset-password|setting/admin/thumbnail)$, roles: PUBLIC_ACCESS
}
- { path: ^/pimcore-studio/api, roles: ROLE_PIMCORE_USER }

Optional: MCP firewall

If you use bundles that provide MCP (Model Context Protocol) servers (e.g. Data Importer), add the pimcore_mcp firewall as well. This enables authentication for all /pimcore-mcp/ routes. See the MCP Server documentation for details on authentication and token configuration.

security:
firewalls:
pimcore_mcp: '%pimcore_studio_backend.mcp_firewall_settings%'
pimcore_studio: '%pimcore_studio_backend.firewall_settings%'
access_control:
- {
path: ^/pimcore-studio/api/(docs|docs/json|translations|user/reset-password|setting/admin/thumbnail)$, roles: PUBLIC_ACCESS
}
- { path: ^/pimcore-studio/api, roles: ROLE_PIMCORE_USER }
- { path: ^/pimcore-mcp/, roles: ROLE_PIMCORE_USER }

Note: The pimcore_mcp firewall must be listed before pimcore_studio in the firewalls section. Symfony evaluates firewalls in order, so placing it first ensures /pimcore-mcp/ requests are matched by the correct firewall.

Optional: OAuth 2.1 authorization server

The bundle can also act as an embedded OAuth 2.1 authorization server, so standards-based clients can authenticate with standards-based bearer tokens instead of static credentials. It is opt-in and its endpoints live at the web root (outside the firewalls above), so it needs its own access_control rules. See the OAuth 2.1 Authorization Server page for setup and configuration.

Optional: Two-factor authentication

Users can protect their login with codes from an authenticator app; no extra firewall or access_control rule is needed. See Two-Factor Authentication for the configuration.

  1. Make sure the bundle is enabled in the config/bundles.php file. The following lines should be added:
use Pimcore\Bundle\StudioBackendBundle\PimcoreStudioBackendBundle;
// ...
return [
// ...
PimcoreStudioBackendBundle::class => ['all' => true],
// ...
];
  1. Install the bundle:
bin/console pimcore:bundle:install PimcoreStudioBackendBundle

OpenApi Documentation​

Access the OpenAPI documentation at:

https://<your-pimcore-host>/pimcore-studio/api/docs

JSON format:

https://<your-pimcore-host>/pimcore-studio/api/docs/json

Export the OpenAPI spec as a JSON file:

bin/console studio-backend-bundle:generate-openapi-config-json --file-name=<your-file-name>.json

Filename is optional. If not provided, the default filename is studio-backend-openapi.json. The file will be saved in the temp directory of your Pimcore project. If the file with the same name already exists, it will be overwritten

Setting Up Generic Data Index​

The Studio Backend requires the Generic Data Index bundle, which is a default dependency and automatically enabled. For setup instructions, see the Generic Data Index documentation.

Mercure​

The Studio Backend uses Mercure to push real-time updates to the frontend. Set up a Mercure hub and configure the bundle to use it. See Mercure official docs for general setup. The simplest approach is the Docker image with a reverse proxy to avoid CSP issues. For detailed configuration, see the Mercure Setup page.

JWT Key​

A valid JWT key is necessary for proper Mercure communication. Currently, the bundle uses the same key for subscriber and publisher. Use your preferred password generator to create a secure and valid JWT key, which is used by the application to encrypt JWT tokens and payloads. The key needs to be minimum 256 bits long which is 32 characters.

Keep the jwt_key private! To learn more about JWT keys and generate a valid key, e.g. take a look at https://jwt.io.

Also make sure that the keys configured in pimcore match the keys in the (docker) Mercure configuration.

Configuration​

Configure a JWT key for Mercure. This key signs and verifies the JWT tokens used for authentication.

Mercure configuration​

URLs for accessing Mercure server-side (for updating state information within application services) and client-side (for getting updates in Pimcore Studio UI) can be configured via a symfony configuration.

Optionally, you can configure the cookie parameters:

  • lifetime for the JWT token in seconds (default is 3600 seconds)
  • SameSite attribute (default is Strict; set jwt_cookie_strictness to false to use None). Browsers only accept SameSite=None cookies with the Secure flag, which is set only when hub_url_client is an https URL.
  • domain of the cookie (jwt_cookie_host, e.g. .example.com; by default the host of hub_url_client is used, a leading dot also makes the cookie available to sibling subdomains)
pimcore_studio_backend:
mercure_settings:
jwt_key: '<your-256-bit-secret-min-32-chars>'

# The url to the mercure hub for the server (must be set, there is no default).
# This can also be the docker container name (e.g., http://mercure/.well-known/mercure).
hub_url_server: 'http://mercure/.well-known/mercure'

# Optional configuration

# The url to the mercure hub for the (frontend) client.
# If it is not set, the default will be set to "http(s)://<YOUR_CURRENT_PIMCORE_HOST>/hub".
# It is possible to use "<PIMCORE_SCHEMA_HOST>" as a placeholder for the current schema and host if path to mercure should be different.
hub_url_client: 'https://your-app-domain.com/hub'
cookie_lifetime: 3600
jwt_cookie_strictness: true
jwt_cookie_host: '.your-app-domain.com'

You need to configure the full URL including protocol, port and path to Mercure here. For client side url it is also possible to use <PIMCORE_SCHEMA_HOST> for the current schema and host of client. If hub_url_client is not set, it is generated from the scheme and host of the current request and the default path /hub. hub_url_server must be set: it has no default and is not checked when the container is built. When it is empty, no Mercure updates are published and an error is written to the log.

Default Controllers for New Documents​

A new page, snippet or email document that is created without a predefined document type gets the controller configured in pimcore.documents.default_controller. A project that renders emails with a different controller than pages can configure a controller per document type; every type without an entry keeps the core default:

pimcore_studio_backend:
documents:
default_controllers:
email: App\Controller\MailController::defaultAction

Only page, snippet and email are accepted as keys. A predefined document type selected while creating the document still takes precedence, as does the base document when a translation is added.

Maximum Size of Text Assets​

Studio loads a text asset completely into the editor and preview. To protect the browser, a text asset larger than 2 MB is not loaded (GET /assets/{id}/text answers HTTP 413 and Studio shows "Preview not available"). The limit can be changed per project:

pimcore_studio_backend:
asset_text_settings:
# Maximum size of a text asset in bytes that Studio loads. Default value is 2000000 (2 MB).
max_file_size: 5000000

The value must be at least 1. A higher limit also raises the PHP memory a single preview request needs, because the file is held in memory several times while it is converted to UTF-8; keep memory_limit in mind when raising it.

Publish and Save Permissions​

For data objects, the publish and unpublish permissions include saving the changes sent with the request. See Publish and Save Permissions for the details.

Changing the prefix of the Studio Backend​

It is possible to change the route where you can reach the API. By default, the route is /pimcore-studio/api/.
If you want to change the prefix, you can do so by changing the configuration like the following: Keep in mind that you need to update your access_control settings accordingly.

pimcore_studio_backend:
url_prefix: '/your-prefix/api/'
security:
access_control:
- { path: ^/your-prefix/api/(docs|docs/json|translations)$, roles: PUBLIC_ACCESS }
- { path: ^/your-prefix/api, roles: ROLE_PIMCORE_USER }