Environment Variables Reference

This page documents all environment variables used in Pimcore PaaS deployments. Understanding these variables is essential for successful configuration.

Overview: Three Variable Contexts

Pimcore PaaS uses environment variables in three distinct phases:

1. Local Development — Variables in your .env file for running Pimcore locally with your actual services
2. Build Phase — Placeholder values that allow Symfony's dependency injection container to compile during deployment (services aren't available yet)
3. Runtime — Real connection values automatically configured from PLATFORM_RELATIONSHIPS by config/pimcore/startup.php

Where Variables Are Configured

Context	Location	Purpose	When Set
Local Development	.env file in project root	Real connection details for your local database, Redis, and other services	Before running pimcore-install
Build Phase	.platform-scripts/build/export-vars.sh	Placeholder values to allow Symfony DI container compilation	Automatically during PaaS build
Runtime	config/pimcore/startup.php	Real connection values from PLATFORM_RELATIONSHIPS	Automatically when application starts
PaaS Console	Settings → Variables in Console UI	Admin credentials, license token, encryption secrets	Manual setup required before first deployment

PaaS Console Variables (Must Set Manually)

These must be set in the PaaS Console before your first deployment. Without them, your deployment will fail or your application won't start properly.

Navigate to Settings → Variables in the Pimcore PaaS Console and create the following:

Variable Name	Description	Sensitive?	Available at build time?	Example Value
env:APP_ENV	Application environment	No	Yes (recommended)	prod or dev
env:PIMCORE_TOKEN	License token from your Pimcore certificate (used to authenticate against repo.pimcore.com during composer install)	Yes (tick)	Yes (required)	<your-pimcore-license-token>
env:PIMCORE_REPO	Name of your enterprise Composer repository on repo.pimcore.com (the path segment after the host, e.g. pimcore-developers for https://repo.pimcore.com/pimcore-developers/)	No	Yes (required)	<your-repo-name>
env:PIMCORE_ADMIN_USER	Admin username for Pimcore backend	Yes (tick)	No	<your-admin-username>
env:PIMCORE_ADMIN_PASSWORD	Admin password for Pimcore backend	Yes (tick)	No	<your-secure-password>
env:PIMCORE_PRODUCT_KEY	Product key from product registration	No	Yes (recommended)	<product-key-from-registration>
env:PIMCORE_INSTANCE_IDENTIFIER	Instance identifier from product registration	No	Yes (recommended)	<instance-identifier>
env:PIMCORE_ENCRYPTION_SECRET	Encryption secret generated by pimcore-paas-product-registration (used as Symfony app secret and for data encryption)	Yes (tick)	Yes (recommended)	<encryption-secret>

Note: The product key, instance identifier, and encryption secret are generated when you run ./vendor/bin/pimcore-paas-product-registration locally.

Build-time vs. Runtime Visibility on PaaS (Upsun)

Variables created in the PaaS Console are runtime-only by default. Some of the variables above must additionally be exposed to the build phase so that composer install and the Symfony container compilation can access them:

Variable	Why it's needed at build time
PIMCORE_TOKEN	Used by .platform-scripts/build/composer.sh to authenticate against repo.pimcore.com during composer install. Without it, the build fails with a 401 from the Composer repository.
PIMCORE_REPO	Used by .platform-scripts/build/composer.sh to register your enterprise Composer repository (https://repo.pimcore.com/$PIMCORE_REPO/). Without it, enterprise packages cannot be resolved during the build.
APP_ENV	The build hook runs php bin/console assets:install (see .upsun/includes/hooks.yaml), which boots Symfony. If APP_ENV is not visible at build time, Symfony falls back to the value from .env (dev), warming the wrong cache and producing artifacts that have to be rebuilt on the first runtime request. Recommended to mark as build-visible (or to pass --env=prod explicitly in the build hook).
PIMCORE_ENCRYPTION_SECRET	Referenced by config/platform.yaml (Symfony secret, encryption secret, Mercure JWT key). The build falls back to a placeholder value, but exposing the real one at build time avoids container cache invalidation on the first request.
PIMCORE_PRODUCT_KEY, PIMCORE_INSTANCE_IDENTIFIER	Read by the enterprise subscription tools during container compilation. Recommended to expose at build time to avoid container rebuild on first runtime access.

How to mark a variable as visible at build time:

• In the PaaS Console UI: When creating or editing the variable, check the "Available during build" (or equivalent) checkbox.
• Via the Pimcore CLI: Pass --visible-build=true (and --visible-runtime=true) when creating the variable, e.g.:

  pimcore-cloud variable:create --name=env:PIMCORE_TOKEN --value=<token> --sensitive=true --visible-build=true --visible-runtime=true

Symptom of a missing build-time variable: The deployment build hook fails during composer install with Authentication required (repo.pimcore.com) (missing PIMCORE_TOKEN) or Could not find package ... in any version for enterprise packages (missing PIMCORE_REPO).

Local .env Variables

For local development, set these in your .env file in the project root:

Variable	Description	Example Value
APP_ENV	Application environment	dev
APP_DEBUG	Enable Symfony debug mode	true
PIMCORE_DEV_MODE	Enable Pimcore development features	false
PIMCORE_TOKEN	License token (same as Console)	<your-pimcore-license-token>
PIMCORE_REPO	Enterprise Composer repository name (same as Console)	<your-repo-name>
DATABASE_URL	Database DSN (Doctrine DBAL URL)	mysql://root:password@127.0.0.1:3306/pimcore
REDIS_URL	Redis connection URL for cache	redis://127.0.0.1:6379 or redis://redis:6379 (Docker)
REDIS_SESSIONS_URL	Redis connection URL for sessions	redis://127.0.0.1:6379 or redis://redis:6379 (Docker)
GOTENBERG_BASE_URL	Local Gotenberg service base URL	http://localhost:3000 or placeholder if not used
PIMCORE_INSTANCE_IDENTIFIER	From product registration	(generated value)
PIMCORE_PRODUCT_KEY	From product registration	(generated value)
PIMCORE_ENCRYPTION_SECRET	From product registration	(generated value)

Build-Phase Service Configuration Variables

Purpose: During the PaaS build phase, the Symfony dependency injection container must be compiled. However, services like MariaDB and Redis aren't available yet—they only become available at runtime. These variables must be available in the environment with placeholder values during the build to allow Symfony compilation to succeed.

Behavior:

• PaaS deployment: During the build, these variables are exported by .platform-scripts/build/export-vars.sh so they are available to Symfony. At runtime, config/pimcore/startup.php automatically overwrites them with real service credentials from PLATFORM_RELATIONSHIPS. The actual placeholder values don't matter—only their presence during build.
• Local development: Define these variables in your .env file so that local composer commands and Symfony can compile the container. Update them to point to your actual local services. If you don't use a service locally, the placeholder values are fine.

Location (PaaS build): .platform-scripts/build/export-vars.sh (exports these variables into the build environment)

Variable	Placeholder Value	Real Value Source (PaaS runtime)	Local Development
DATABASE_URL	mysql://user:pass@mariadb:3306/pimcore	Constructed from PLATFORM_RELATIONSHIPS['database']	Your local DB DSN (e.g., mysql://root:pass@127.0.0.1:3306/pimcore)
REDIS_URL	redis://redis:6379	Constructed from PLATFORM_RELATIONSHIPS['redis']	Your local Redis URL (e.g., redis://127.0.0.1:6379)
REDIS_SESSIONS_URL	redis://redis:6379	Constructed from PLATFORM_RELATIONSHIPS['redis-sessions']	Your local Redis URL (e.g., redis://127.0.0.1:6379)
GOTENBERG_BASE_URL	http://localhost:3000	Constructed from PLATFORM_RELATIONSHIPS['gotenberg8']	Your local Gotenberg URL (e.g., http://localhost:3000)
PIMCORE_ELASTICSEARCH_DSN	elasticsearch://elastic:9200	Constructed from PLATFORM_RELATIONSHIPS['elasticsearch'] (if enabled)	Your local Elasticsearch DSN (if using)
PIMCORE_ENCRYPTION_SECRET	xyz	Build-phase placeholder; at runtime the actual encryption secret is provided via the PIMCORE_ENCRYPTION_SECRET Console variable	Use placeholder value
CHROMIUM_HOST	chrome	(Not currently mapped in startup.php)	Your local Chrome/Chromium host (if using)
CHROMIUM_PORT	1234	(Not currently mapped in startup.php)	Your local Chrome/Chromium port (if using)
PIMCORE_MESSENGER_TRANSPORT_DSN_PREFIX	amqp://user:pass@rabbitmq:5672/%2f/	Constructed from PLATFORM_RELATIONSHIPS['queue']	Your local AMQP/Doctrine DSN prefix (if using)
MERCURE_URL	http://localhost:8888 (fallback)	Derived from mercure route in PLATFORM_ROUTES (if enabled)	Your local Mercure hub URL
MERCURE_SERVER_URL	http://localhost:8888/.well-known/mercure (fallback)	Derived from mercure route + /.well-known/mercure (if enabled)	Your local Mercure server URL
MERCURE_JWT_KEY	placeholder-jwt-key-for-build-phase (fallback)	Derived from PIMCORE_ENCRYPTION_SECRET at runtime (if Mercure enabled)	Your local Mercure JWT key
PIMCORE_OPENSEARCH_DSN	opensearch://opensearch:9200	Constructed from PLATFORM_RELATIONSHIPS['opensearch'] (if enabled)	Your local OpenSearch DSN (if using)

Auto-Configured Variables (Runtime)

At runtime, config/pimcore/startup.php uses the Platform.sh Config Reader library to extract real connection details from the PLATFORM_RELATIONSHIPS environment variable and sets them for use by Pimcore and Symfony.

Variable	Source Service	Purpose
DATABASE_URL	database relationship	MariaDB connection DSN
REDIS_URL	redis relationship	Redis cache connection URL
REDIS_SESSIONS_URL	redis-sessions relationship	Redis session storage connection URL
GOTENBERG_BASE_URL	gotenberg8 relationship	Gotenberg PDF service base URL
GOTENBERG_HOST_URL	Primary route from PLATFORM_ROUTES	Public URL for Gotenberg callbacks
PIMCORE_ELASTICSEARCH_DSN	elasticsearch relationship (if enabled)	Elasticsearch DSN
PIMCORE_MESSENGER_TRANSPORT_DSN_PREFIX	queue relationship	AMQP messenger transport DSN prefix
PIMCORE_OPENSEARCH_DSN	opensearch relationship (if enabled)	OpenSearch DSN
MERCURE_URL	mercure route (if enabled)	Mercure hub URL for real-time features
MERCURE_SERVER_URL	mercure route (if enabled)	Mercure server URL (hub URL + /.well-known/mercure)
MERCURE_JWT_KEY	Derived from PIMCORE_ENCRYPTION_SECRET (if Mercure enabled)	JWT key for Mercure authentication
PIMCORE_IS_PRODUCTION_SYSTEM	Platform.sh environment type	true on production branch, false otherwise

Reference: See config/pimcore/startup.php for implementation details.

Optional Variables

These variables are used for advanced configurations and are not required for basic deployments.

S3 Object Storage

If using Amazon S3 for asset storage (configured in config/platform.yaml):

Variable	Description	Example Value
S3_STORAGE_KEY	AWS access key ID	AKIAIOSFODNN7EXAMPLE
S3_STORAGE_SECRET	AWS secret access key	wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
S3_PUBLIC_BUCKET	S3 bucket for public assets (thumbnails)	my-pimcore-public
S3_PRIVATE_BUCKET	S3 bucket for private storage	my-pimcore-private

Configuration location: config/platform.yaml (commented out by default)

Class Definition Writable

Variable	Description	Example Value
PIMCORE_CLASS_DEFINITION_WRITABLE	Allow class definitions to be edited in production	true or false

Note: This is generally not recommended for production environments.

Mercure Real-Time Updates

If using Pimcore Direct Edit or Studio with Mercure:

Variable	Description	Set By
MERCURE_URL	Mercure hub URL	Automatically set by startup.php from routes
MERCURE_SERVER_URL	Mercure server URL for server-side publishing	Automatically set by startup.php from routes
MERCURE_JWT_KEY	JWT key for Mercure authentication	Automatically derived from PIMCORE_ENCRYPTION_SECRET by startup.php

Configuration location: config/platform.yaml (commented out by default)

Web-to-Print (Gotenberg)

Variable	Description	Set By
GOTENBERG_HOST_URL	Public URL for Gotenberg callbacks	Automatically set by startup.php

Configuration location: config/platform.yaml (commented out by default)

Troubleshooting

Missing Console Variables

Symptom: Deployment fails with error message like:

Environment variable "PIMCORE_TOKEN" not set

Solution: Go to Settings → Variables in the PaaS Console and ensure all required variables are set (see "PaaS Console Variables" section above). For variables consumed during the build phase (PIMCORE_TOKEN, PIMCORE_REPO, and recommended: PIMCORE_ENCRYPTION_SECRET, PIMCORE_PRODUCT_KEY, PIMCORE_INSTANCE_IDENTIFIER), make sure they are also marked as available during build.

---

Missing Build-Phase Service Variables

Symptom: Build fails during composer install or Symfony container compilation with:

Environment variable not found: "DATABASE_URL"

Solution: Check that .platform-scripts/build/export-vars.sh exists and is being sourced in your build hook. Verify the file contains all required placeholder variable exports.

Reference: Your build hook (defined in .platform/applications.yaml or included via .upsun/includes/hooks.yaml) should source the script:

hooks:
  build: |
    set -e
    . .platform-scripts/build/export-vars.sh
    composer install --no-interaction --optimize-autoloader

---

Wrong Runtime Values

Symptom: Application connects to wrong database or services at runtime, or connections fail.

Solution:

1. Check that config/pimcore/startup.php is being loaded by your application
2. Verify the file is reading from PLATFORM_RELATIONSHIPS correctly
3. Use SSH to inspect environment: pimcore-cloud ssh → echo $PLATFORM_RELATIONSHIPS | base64 -d | jq
4. Ensure relationship names in .platform/applications.yaml match those used in startup.php

Common mismatch: If you renamed a relationship in .platform/applications.yaml (e.g., database → db), you must update startup.php accordingly.

---

Product Registration Variables Not Working

Symptom: Pimcore shows license errors or product registration prompts after deployment.

Solution:

1. Ensure you ran ./vendor/bin/pimcore-paas-product-registration locally and followed the registration URL
2. Copy the generated values to both:
   • Local .env file (for local development)
   • PaaS Console → Settings → Variables (for production)
3. Verify variable names exactly match: PIMCORE_INSTANCE_IDENTIFIER, PIMCORE_PRODUCT_KEY, PIMCORE_ENCRYPTION_SECRET

---

See Also

• Configuration — Customizing service configurations
• Good to Know — Operational guidance for running projects
• FAQ & Troubleshooting — Common issues and solutions