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?	Example Value
env:APP_ENV	Application environment	No	prod or dev
env:PIMCORE_TOKEN	License token from your Pimcore certificate	Yes (tick)	<your-pimcore-license-token>
env:PIMCORE_INSTALL_ADMIN_USERNAME	Admin username for Pimcore backend	Yes (tick)	<your-admin-username>
env:PIMCORE_INSTALL_ADMIN_PASSWORD	Admin password for Pimcore backend	Yes (tick)	<your-secure-password>
env:PIMCORE_INSTALL_PRODUCT_KEY	Product key from product registration	No	<product-key-from-registration>
env:PIMCORE_INSTALL_INSTANCE_IDENTIFIER	Instance identifier from product registration	No	<instance-identifier>
env:PIMCORE_INSTALL_ENCRYPTION_SECRET	Encryption secret generated by pimcore-paas-product-registration	Yes (tick)	<encryption-secret>

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

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>
DATABASE_HOST	Local database hostname	127.0.0.1 or mariadb (Docker)
DATABASE_PORT	Local database port	3306
DATABASE_USER	Local database username	root or pimcore
DATABASE_PASSWORD	Local database password	(your local password)
DATABASE_DBNAME	Local database name	pimcore
REDIS_HOST	Local Redis hostname	127.0.0.1 or redis (Docker)
REDIS_PORT	Local Redis port	6379
GOTENBERG_IP	Local Gotenberg service IP	Docker container IP or placeholder if not used
GOTENBERG_PORT	Local Gotenberg service port	3000 or placeholder if not used
PIMCORE_INSTALL_INSTANCE_IDENTIFIER	From product registration	(generated value)
PIMCORE_INSTALL_PRODUCT_KEY	From product registration	(generated value)
PIMCORE_INSTALL_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_HOST	mariadb	PLATFORM_RELATIONSHIPS['database']['host']	Your local DB host (e.g., 127.0.0.1)
DATABASE_PORT	1234	PLATFORM_RELATIONSHIPS['database']['port']	Your local DB port (e.g., 3306)
DATABASE_USER	user	PLATFORM_RELATIONSHIPS['database']['username']	Your local DB username
DATABASE_PASSWORD	pass	PLATFORM_RELATIONSHIPS['database']['password']	Your local DB password
DATABASE_DBNAME	pimcore	PLATFORM_RELATIONSHIPS['database']['path']	Your local DB name
REDIS_HOST	redis	PLATFORM_RELATIONSHIPS['redis']['host']	Your local Redis host (e.g., 127.0.0.1 or redis for Docker)
REDIS_PORT	1234	PLATFORM_RELATIONSHIPS['redis']['port']	Your local Redis port (e.g., 6379)
GOTENBERG_IP	1.2.3.4	PLATFORM_RELATIONSHIPS['gotenberg8']['ip']	Your local Gotenberg IP (if using)
GOTENBERG_PORT	1234	PLATFORM_RELATIONSHIPS['gotenberg8']['port']	Your local Gotenberg port (if using)
PIMCORE_ES_CLIENT_HOST	elastic:1234	PLATFORM_RELATIONSHIPS['elasticsearch']['host'] . ':' . ['port'] (if enabled)	Your local Elasticsearch (if using)
PIMCORE_ES_CLIENT_USERNAME	user	(Not used in current config)	Your local Elasticsearch username (if using)
PIMCORE_ES_CLIENT_PASS	pass	(Not used in current config)	Your local Elasticsearch password (if using)
PIMCORE_ENCRYPTION_SECRET	xyz	Build-phase placeholder; at runtime the actual encryption secret is provided via the PIMCORE_INSTALL_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)
RABBITMQ_URL	amqp://user:pass@rabbitmq:1234	PLATFORM_RELATIONSHIPS['queue'] (if enabled)	Your local RabbitMQ URL (if using)
PIMCORE_OPENSEARCH_CLIENT_HOST	https://opensearch:9200	PLATFORM_RELATIONSHIPS['opensearch']['host'] . ':' . ['port'] (if enabled)	Your local OpenSearch (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_HOST	database relationship	MariaDB connection host
DATABASE_PORT	database relationship	MariaDB connection port
DATABASE_USER	database relationship	MariaDB username
DATABASE_PASSWORD	database relationship	MariaDB password
DATABASE_DBNAME	database relationship	MariaDB database name
REDIS_HOST	redis relationship	Redis cache host
REDIS_PORT	redis relationship	Redis cache port
REDIS_SESSIONS_HOST	redis-sessions relationship	Redis session storage host
REDIS_SESSIONS_PORT	redis-sessions relationship	Redis session storage port
GOTENBERG_IP	gotenberg8 relationship	Gotenberg PDF service IP
GOTENBERG_PORT	gotenberg8 relationship	Gotenberg PDF service port
GOTENBERG_HOST_URL	Primary route from PLATFORM_ROUTES	Public URL for Gotenberg callbacks
PIMCORE_ES_CLIENT_HOST	elasticsearch relationship (if enabled)	Elasticsearch host:port
RABBITMQ_URL	queue relationship (if enabled)	RabbitMQ connection string
PIMCORE_OPENSEARCH_CLIENT_HOST	opensearch relationship (if enabled)	OpenSearch host:port
MERCURE_URL	mercure route (if enabled)	Mercure hub URL for real-time features
PIMCORE_IS_PRODUCTION_SYSTEM	Platform.sh environment type	true on production branch, false otherwise

Reference: See config/pimcore/startup.php lines 5-84 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 lines 11-245 (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

Configuration location: config/platform.yaml lines 131-167 (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 lines 138-146 (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 7 required variables are set (see "PaaS Console Variables" section above).

---

Missing Build-Phase Service Variables

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

Environment variable not found: "DATABASE_HOST"

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_INSTALL_INSTANCE_IDENTIFIER, PIMCORE_INSTALL_PRODUCT_KEY, PIMCORE_INSTALL_ENCRYPTION_SECRET

---

See Also

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