Quick Start: Existing Project

This guide walks you through adding Pimcore PaaS deployment capabilities to an existing Pimcore project. If you're starting from scratch, see Quick Start: New Project instead.

Prerequisites

Before starting, ensure you have:

• Existing Pimcore project with Git version control initialized
• Pimcore license token and Composer repository URL (from your license certificate)
• Pimcore PaaS Console account at https://console.pimcore.cloud/ with a project created
• Pimcore CLI installed (installation guide)
• Project backup (recommended before making infrastructure changes)

Verifying Prerequisites

Before proceeding, verify your environment meets the requirements:

git --version              # Should show Git is installed
pimcore-cloud --version    # Should show Pimcore CLI is installed
composer --version         # Should show Composer is installed
git status                 # Should show you're in a Git repository

---

Step-by-Step Guide

Step 1: [LOCAL] Install PaaS Bundle

Add the Pimcore PaaS bundle to your existing project. First, configure Composer authentication (replace YOUR_PIMCORE_TOKEN and YOUR_REPO_NAME with actual values from your license certificate):

composer config --auth http-basic.repo.pimcore.com token YOUR_PIMCORE_TOKEN
composer config repositories.pimcore_enterprise composer https://repo.pimcore.com/YOUR_REPO_NAME/

Install the PaaS bundle:

composer require pimcore/paas

Enable the Enterprise Subscription Tools bundle in your /config/bundles.php by adding this line:

\Pimcore\Bundle\EnterpriseSubscriptionToolsBundle\PimcoreEnterpriseSubscriptionToolsBundle::class => ['all' => true],

Step 2: [LOCAL] Install PaaS Config Files

Install the PaaS-specific configuration files to your project:

./vendor/bin/pimcore-paas-install-config

This command creates several configuration files and directories in your project:

Files/Directories	Purpose
.platform/*	PaaS infrastructure configuration (services, routes, etc.)
.platform-scripts/*	Build and deploy scripts
config/pimcore/startup.php	Dynamic service configuration mapping (runtime)
config/platform.yaml	Pimcore generic PaaS configuration
.env.dev and .env.prod	Example environment configuration files

Important: Review these files and commit them to your Git repository. All configurations can be customized to fit your project's needs.

Step 3: [LOCAL] Configure Service Environment Variables

Add service configuration variables to your .env file. These are required during the PaaS build phase and for local development.

⚠️ Why are these variables needed?

During the PaaS build phase, your application is compiled before services like MariaDB, Redis, and OpenSearch are available. However, Symfony and Pimcore require certain environment variables to be defined during the build. These placeholder values satisfy the build-time requirements. At runtime, config/pimcore/startup.php automatically replaces them with real service credentials from PLATFORM_RELATIONSHIPS.

For local development, update these values to point to your actual local services.

Add the following variables to your .env file:

# Service configuration (placeholders for PaaS build, update for local development)
DATABASE_URL=mysql://user:pass@mariadb:3306/pimcore
REDIS_URL=redis://redis:6379
REDIS_SESSIONS_URL=redis://redis:6379
GOTENBERG_BASE_URL=http://localhost:3000
PIMCORE_ELASTICSEARCH_DSN=elasticsearch://elastic:9200
CHROMIUM_HOST=chrome
CHROMIUM_PORT=1234
PIMCORE_MESSENGER_TRANSPORT_DSN_PREFIX=amqp://user:pass@rabbitmq:5672/%2f/
PIMCORE_OPENSEARCH_DSN=opensearch://opensearch:9200

For local development: Update these values to match your actual local services (e.g., DATABASE_URL=mysql://root:root@127.0.0.1:3306/pimcore, REDIS_URL=redis://127.0.0.1:6379). If you're not using a service locally, the placeholder values are fine.

Reference: See .platform-scripts/build/export-vars.sh for how these variables are used during the PaaS build phase. For more details, consult the Environment Variables Reference guide.

Step 4: [LOCAL] Run Product Registration

Product registration is required for Pimcore Platform version 2025.1 or later.

Check your version:

grep '"pimcore/pimcore"' composer.json

If your version is 2025.1 or later, run the registration:

./vendor/bin/pimcore-paas-product-registration

This command generates the registration parameters. Follow the URL provided to complete the registration. You'll need:

• PIMCORE_PRODUCT_KEY
• PIMCORE_INSTANCE_IDENTIFIER
• PIMCORE_ENCRYPTION_SECRET

Save these values—you'll need them for the PaaS Console configuration in Step 6.

Note: If you've already registered your product instance, you can skip this step.

Step 5: [LOCAL] Prepare Git Repository

Ensure your project is on the main branch. Pimcore PaaS requires main as the production branch.

Check your current branch:

git branch

⚠️ CRITICAL: If you're on master or any other branch, rename it to main:

git branch -M main

Why? Pimcore PaaS expects the production environment to deploy from the main branch. The -M flag renames your current branch to main regardless of its current name. If your default branch is named master (common in older Git projects), deployments will fail until you rename it.

Verify you're now on main:

git branch

You should see * main in the output.

Step 6: [CONSOLE] Configure PaaS Console Variables

Log in to the Pimcore PaaS Console and navigate to your project. Go to Settings → Variables and create the following environment variables:

Variable Name	Description	Value Example	Sensitive	Available at build time
env:APP_ENV	Application environment	dev or prod	No	Yes (recommended)
env:PIMCORE_TOKEN	Pimcore license token	<your-pimcore-license-token>	Yes ✓	Yes (required)
env:PIMCORE_REPO	Enterprise Composer repository name (path segment of https://repo.pimcore.com/<name>/)	<your-repo-name>	No	Yes (required)
env:PIMCORE_ADMIN_USER	Admin username for first login	<your-admin-username>	Yes ✓	No
env:PIMCORE_ADMIN_PASSWORD	Admin password for first login	<your-secure-password>	Yes ✓	No
env:PIMCORE_PRODUCT_KEY	Product key from Step 4	<product-key-from-registration>	No	Yes (recommended)
env:PIMCORE_INSTANCE_IDENTIFIER	Instance identifier from Step 4	<instance-identifier>	No	Yes (recommended)
env:PIMCORE_ENCRYPTION_SECRET	Encryption secret from Step 4	<encryption-secret>	Yes ✓	Yes (recommended)

Note: Mark PIMCORE_TOKEN, PIMCORE_ADMIN_USER, PIMCORE_ADMIN_PASSWORD, and PIMCORE_ENCRYPTION_SECRET as sensitive (check the "sensitive" checkbox). The license token is used as a Composer authentication credential, and the encryption secret is used as the Symfony app secret and for data encryption.

Build-time visibility: PIMCORE_TOKEN and PIMCORE_REPO are consumed during the build phase by .platform-scripts/build/composer.sh (Composer authentication and enterprise repository registration). They must be marked as available during build. Marking APP_ENV, PIMCORE_ENCRYPTION_SECRET, PIMCORE_PRODUCT_KEY, and PIMCORE_INSTANCE_IDENTIFIER as available at build time as well is recommended: APP_ENV ensures the build hook's bin/console assets:install runs in the correct environment, and the others avoid container cache invalidation on the first runtime request. See the Environment Variables Reference for details.

These variables configure your runtime environment on PaaS and are used during the initial deployment.

Step 7: [LOCAL] Connect to PaaS Remote

Connect your local repository to the PaaS remote using the Pimcore CLI:

pimcore-cloud project:set-remote <project-id>

Replace <project-id> with your project ID from the PaaS Console (format: abcdefg123456).

This command adds a Git remote named pimcore to your repository and generates a .platform.app.yaml file.

⚠️ CRITICAL: Delete the generated .platform.app.yaml file immediately:

# If .platform.app.yaml was already added to Git, use git rm:
git rm -f .platform.app.yaml
git commit -m "Remove unneeded .platform.app.yaml"

# Otherwise, simply delete it:
rm -f .platform.app.yaml

Why? The project:set-remote command generates a .platform.app.yaml file for legacy compatibility, but Pimcore PaaS uses .platform/applications.yaml instead. If you leave the old file in place, it will cause configuration conflicts during deployment. The .platform/applications.yaml file was already created in Step 2.

Verify the remote was added:

git remote -v

You should see a pimcore remote pointing to your PaaS project.

Step 8: [LOCAL/CLI] Sync Existing Data

If your existing project has data in the var/ and public/var/ directories (assets, logs, cache, etc.), you need to upload them to PaaS before deploying.

Upload the var/ directory:

pimcore-cloud mount:upload --mount var --source ./var

Upload the public/var/ directory:

pimcore-cloud mount:upload --mount web/var --source ./public/var

These commands transfer your local files to the corresponding mounted volumes on PaaS.

Note about database: The PaaS environment will have an empty database on first deploy. If you need to migrate your existing database, consider using database dump/restore tools separately after the initial deployment. See the Migration Guide for database migration strategies.

Optional: If you have large amounts of data, you may want to selectively sync only essential files (e.g., exclude cache or temporary files) to reduce upload time.

Step 9: [LOCAL] Push to Deploy

Commit all your PaaS configuration changes and push to deploy:

git add -A
git commit -m "Add PaaS configuration"
git push pimcore main

The deployment process will:

1. Build your application
2. Install dependencies
3. Deploy services (MariaDB, Redis, OpenSearch, etc.)
4. Run the PaaS install profile (Pimcore\Paas\Install\PaasProfile) to set up the database schema and initial Pimcore configuration
5. Install enabled bundles
6. Run database migrations
7. Make your site available

This first deployment typically takes 10-15 minutes.

Watch the deployment progress:

• In the Console: Navigate to your project in the PaaS Console → Environments tab → main environment
• From the CLI: Run pimcore-cloud activity:log to view real-time deployment logs

Verify deployment success:

1. Wait for the main environment to show Active status in the Console
2. Click the generated URL to access your site
3. Log in to the admin panel at https://your-site-url/admin using the credentials you configured in Step 6

---

Next Steps

Now that your existing Pimcore project is deployed on PaaS:

• Environment Variables Reference - Learn about all available environment variables and how they work
• Configuration Guide - Customize your PaaS setup (RabbitMQ, OpenSearch, S3, etc.)
• Good to Know - Operational tips for running Pimcore on PaaS (logs, commands, cache, etc.)
• Migration Guide - Additional migration strategies for complex projects
• FAQ & Troubleshooting - Common issues and solutions

Common Issues

Deployment fails with "branch not found"

Make sure you renamed your branch to main (see Step 5). PaaS looks for the main branch by default.

Configuration conflicts during deployment

Check if .platform.app.yaml exists in your repository. If it does, delete it (see Step 7). PaaS uses .platform/applications.yaml instead.

Build fails with "environment variable not defined"

Verify that you added all service configuration variables to your .env file (see Step 3). These placeholder values are required during the PaaS build phase.

Admin login doesn't work after deployment

Verify that you set PIMCORE_ADMIN_USER and PIMCORE_ADMIN_PASSWORD in the PaaS Console (Step 6). These variables are required for the initial admin user creation.

Data or assets are missing after deployment

Make sure you ran the mount:upload commands in Step 8 before pushing your code. You can run them again after deployment to sync any missing files.

For more troubleshooting help, see the FAQ & Troubleshooting guide.