Quick Start: New Project

This guide walks you through creating a new Pimcore project from scratch and deploying it to Pimcore PaaS. If you already have an existing Pimcore project, see Quick Start: Existing Project instead.

Prerequisites

Before starting, ensure you have:

• Pimcore license token and Composer repository URL (from your license certificate)
• Pimcore PaaS Console account at https://console.pimcore.cloud/
• Git installed locally
• Pimcore CLI installed (installation guide)
• Either:
  • PHP 8.3+ with Composer (for Option A)
  • Docker with Docker Compose (for Option B)

Verifying Prerequisites

Before proceeding, verify your environment meets the requirements:

For Option A (Composer):

php --version        # Should show 8.3 or higher
composer --version   # Should show Composer is installed
git --version        # Should show Git is installed
pimcore-cloud --version  # Should show Pimcore CLI is installed

For Option B (Docker):

docker --version           # Should show Docker is installed
docker compose version     # Should show Docker Compose is installed
git --version              # Should show Git is installed
pimcore-cloud --version    # Should show Pimcore CLI is installed

Choose Your Setup Method

Select the installation method that matches your local development environment:

Option	Best For	Requirements
Option A: Composer	Developers with PHP installed locally	PHP 8.3+, Composer
Option B: Docker	Containerized development, no local PHP	Docker, Docker Compose

Both options result in the same deployed PaaS environment—choose based on your preferred local workflow.

---

Option A: Composer-Based Installation

Step 1: Create the Project

[LOCAL] Create a new Pimcore PaaS skeleton project:

COMPOSER_MEMORY_LIMIT=-1 composer create-project pimcore/paas-skeleton my-project
cd my-project

Replace my-project with your desired project name.

Step 2: Configure Composer Authentication

[LOCAL] Add your Pimcore license credentials to Composer (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/

Now install the enterprise dependencies:

composer install

Step 3: Configure Local Environment Variables

[LOCAL] The skeleton includes a .env file with service configuration variables that serve two purposes:

1. For PaaS builds: Placeholder values allow Symfony to compile during build (when services aren't available yet)
2. For local development: Real configuration pointing to your actual local services

You only need to add your PIMCORE_TOKEN:

# Edit .env and add your token (from your license certificate):
PIMCORE_TOKEN="<your-pimcore-license-token>"

The .env file already contains these service configuration variables:

Variable	Default Value	Purpose
GOTENBERG_IP	1.2.3.4	Gotenberg service IP (update with your local IP if using Gotenberg)
GOTENBERG_PORT	1234	Gotenberg port (update with your local port if using Gotenberg)
REDIS_HOST	redis	Redis hostname (update with your local Redis host if needed)
REDIS_PORT	1234	Redis port (update with your local Redis port if needed)

How .env works:

• PaaS deployment: At runtime, config/pimcore/startup.php automatically overwrites these with real service credentials from PLATFORM_RELATIONSHIPS. The actual values don't matter for PaaS—only their presence is required for the build phase.
• Local development: Update these values to point to your actual local services (e.g., REDIS_HOST="127.0.0.1", REDIS_PORT="6379"). If you don't use a service locally, the placeholder values are fine.

Step 4: Register Your Pimcore Product

[LOCAL] 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_INSTALL_PRODUCT_KEY
• PIMCORE_INSTALL_INSTANCE_IDENTIFIER
• PIMCORE_INSTALL_ENCRYPTION_SECRET

Save these values—you'll need them for the PaaS Console configuration later.

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

Step 5: Install Pimcore Locally (Optional but Recommended)

[LOCAL] Install Pimcore locally to test your setup before deploying:

./vendor/bin/pimcore-install

When prompted:

• Choose an admin username and password
• This process may take up to 20 minutes
• You can test the local installation at http://localhost/admin (configure your web server to point to the public/ directory)

Note: This step is optional but recommended to ensure your project is properly configured before deploying to PaaS.

Step 6: Initialize Git Repository

[LOCAL] Initialize Git and prepare your repository:

git init
git add .
git commit -m "Initial Pimcore PaaS skeleton"

⚠️ CRITICAL: Rename your branch to main:

git branch -M main

Why? Pimcore PaaS requires main as the production branch. The -M flag renames your current branch to main regardless of its current name (e.g., master or any other default). If you skip this step, your deployment will fail.

Step 7: Configure PaaS Console Variables

[CONSOLE] Log in to the Pimcore PaaS Console and create a new project. Then navigate to Settings → Variables and create the following environment variables:

Variable Name	Description	Value Example	Sensitive
env:APP_ENV	Application environment	dev or prod	No
env:PIMCORE_TOKEN	Pimcore license token	<your-pimcore-license-token>	Yes ✓
env:PIMCORE_INSTALL_ADMIN_USERNAME	Admin username for first login	<your-admin-username>	Yes ✓
env:PIMCORE_INSTALL_ADMIN_PASSWORD	Admin password for first login	<your-secure-password>	Yes ✓
env:PIMCORE_INSTALL_PRODUCT_KEY	Product key from registration	<product-key-from-registration>	No
env:PIMCORE_INSTALL_INSTANCE_IDENTIFIER	Instance identifier from registration	<instance-identifier>	No
env:PIMCORE_INSTALL_ENCRYPTION_SECRET	Encryption secret from registration	<encryption-secret>	Yes ✓

Note: Mark PIMCORE_TOKEN, PIMCORE_INSTALL_ADMIN_USERNAME, PIMCORE_INSTALL_ADMIN_PASSWORD, and PIMCORE_INSTALL_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.

Step 8: Connect to PaaS Remote

[LOCAL] 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).

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

# If .platform.app.yaml was already added to Git, use git rm:
git rm -f .platform.app.yaml
git commit -m "Remove unused .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.

Step 9: Deploy to PaaS

[LOCAL] Push your code to deploy:

git push pimcore main

The deployment process will:

1. Build your application
2. Install dependencies
3. Deploy services (MariaDB, Redis, OpenSearch, etc.)
4. Run your Pimcore installation
5. Make your site available

This first deployment typically takes 10-15 minutes.

Step 10: Verify Your Deployment

[CONSOLE] Check the deployment status:

1. Open your project in the PaaS Console
2. Navigate to the Environments tab
3. Wait for the main environment to show Active status
4. Click the generated URL to access your site

[LOCAL] You can also check deployment logs:

pimcore-cloud environment:logs

Log in to the admin panel at https://your-site-url/admin using the credentials you configured in Step 7.

---

Option B: Docker-Based Installation

Step 1: Create the Project

[LOCAL] Create a new Pimcore PaaS skeleton project using Docker:

docker run -u `id -u`:`id -g` --rm -v `pwd`:/var/www/html pimcore/pimcore:php8.3-latest composer create-project pimcore/paas-skeleton my-project

Note for Windows users: Replace `id -u`:`id -g` with your user:group ID (e.g., 1000:1000).

Replace my-project with your desired project name.

Step 2: Configure Docker Compose

[LOCAL] Set the correct user permissions for Docker Compose:

# Linux:
sed -i "s|#user: '1000:1000'|user: '$(id -u):$(id -g)'|g" docker-compose.yaml

# macOS:
sed -i '' "s|#user: '1000:1000'|user: '$(id -u):$(id -g)'|g" docker-compose.yaml

Start the Docker services:

docker compose up -d

This starts MariaDB, Redis, and the PHP container needed for local development.

Step 3: Configure Composer Authentication

[LOCAL] Add your Pimcore license credentials inside the Docker container (replace YOUR_PIMCORE_TOKEN and YOUR_REPO_NAME with actual values):

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

Now install the enterprise dependencies:

docker compose exec php composer install

Step 4: Configure Local Environment Variables

[LOCAL] The skeleton includes a .env file with service configuration variables that serve two purposes:

1. For PaaS builds: Placeholder values allow Symfony to compile during build (when services aren't available yet)
2. For local development: Real configuration pointing to your actual local services

You only need to add your PIMCORE_TOKEN:

# Edit .env and add your token (from your license certificate):
PIMCORE_TOKEN="<your-pimcore-license-token>"

The .env file already contains these service configuration variables:

Variable	Default Value	Purpose
GOTENBERG_IP	1.2.3.4	Gotenberg service IP (Docker Compose configures actual service)
GOTENBERG_PORT	1234	Gotenberg port (Docker Compose configures actual service)
REDIS_HOST	redis	Redis hostname (matches Docker Compose service name)
REDIS_PORT	1234	Redis port (Docker Compose configures actual port)

How .env works with Docker:

• PaaS deployment: At runtime, config/pimcore/startup.php automatically overwrites these with real service credentials from PLATFORM_RELATIONSHIPS. The actual values don't matter for PaaS—only their presence is required for the build phase.
• Local Docker development: Your docker-compose.yaml configures actual services (MariaDB, Redis, Gotenberg, etc.) with matching hostnames. The default values work out-of-the-box with the provided Docker setup.

Step 5: Register Your Pimcore Product

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

Check your version:

docker compose exec php grep '"pimcore/pimcore"' composer.json

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

docker compose exec php ./vendor/bin/pimcore-paas-product-registration

Follow the URL provided to complete registration. Save these values for later:

• PIMCORE_INSTALL_PRODUCT_KEY
• PIMCORE_INSTALL_INSTANCE_IDENTIFIER
• PIMCORE_INSTALL_ENCRYPTION_SECRET

Step 6: Install Pimcore Locally (Optional but Recommended)

[LOCAL] Install Pimcore inside the Docker container:

docker compose exec php ./vendor/bin/pimcore-install

When prompted, choose an admin username and password. This may take up to 20 minutes.

Access your local installation at http://localhost/admin.

Step 7: Initialize Git Repository

[LOCAL] Initialize Git (outside the container):

git init
git add .
git commit -m "Initial Pimcore PaaS skeleton"

⚠️ CRITICAL: Rename your branch to main:

git branch -M main

Why? Pimcore PaaS requires main as the production branch. The -M flag renames your current branch to main regardless of its current name (e.g., master or any other default). If you skip this step, your deployment will fail.

Step 8: Configure PaaS Console Variables

[CONSOLE] Log in to the Pimcore PaaS Console and create a new project. Then navigate to Settings → Variables and create the following environment variables:

Variable Name	Description	Value Example	Sensitive
env:APP_ENV	Application environment	dev or prod	No
env:PIMCORE_TOKEN	Pimcore license token	<your-pimcore-license-token>	Yes ✓
env:PIMCORE_INSTALL_ADMIN_USERNAME	Admin username	<your-admin-username>	Yes ✓
env:PIMCORE_INSTALL_ADMIN_PASSWORD	Admin password	<your-secure-password>	Yes ✓
env:PIMCORE_INSTALL_PRODUCT_KEY	Product key from Step 5	<product-key-from-registration>	No
env:PIMCORE_INSTALL_INSTANCE_IDENTIFIER	Instance identifier from Step 5	<instance-identifier>	No
env:PIMCORE_INSTALL_ENCRYPTION_SECRET	Encryption secret from Step 5	<encryption-secret>	Yes ✓

Note: Mark PIMCORE_TOKEN, PIMCORE_INSTALL_ADMIN_USERNAME, PIMCORE_INSTALL_ADMIN_PASSWORD, and PIMCORE_INSTALL_ENCRYPTION_SECRET as sensitive (check the "sensitive" checkbox). The encryption secret is used as the Symfony app secret and for data encryption.

Step 9: Connect to PaaS Remote

[LOCAL] Connect your repository to PaaS (outside the container):

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

Replace <project-id> with your project ID from the PaaS Console.

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

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

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

Why? The project:set-remote command generates a .platform.app.yaml file, but PaaS uses .platform/applications.yaml. The old file causes configuration conflicts.

Step 10: Deploy to PaaS

[LOCAL] Push your code to deploy:

git push pimcore main

The deployment process takes 10-15 minutes for the first deployment.

Step 11: Verify Your Deployment

[CONSOLE] Check deployment status:

1. Open your project in the PaaS Console
2. Navigate to Environments tab
3. Wait for main environment to show Active
4. Click the URL to access your site

[LOCAL] Check deployment logs if needed:

pimcore-cloud environment:logs

Log in at https://your-site-url/admin with the credentials from Step 8.

---

Next Steps

Now that your Pimcore instance is running 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
• FAQ & Troubleshooting - Common issues and solutions

Common Issues

Deployment fails with "branch not found"

Make sure you renamed your branch to main (see Step 6 or 7). 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 8 or 9). PaaS uses .platform/applications.yaml instead.

Admin login doesn't work

Verify that you set PIMCORE_INSTALL_ADMIN_USERNAME and PIMCORE_INSTALL_ADMIN_PASSWORD in the PaaS Console (Step 7 or 8). These variables are required for the initial admin user creation.

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