---
title: Project Readiness and Essential Tooling | Shopware Community Hub
description: >-
  Ensure your Shopware project is deployment-ready with comprehensive
  checklists, essential tooling mastery, and validation workflows for Shopware
  PaaS.
canonical_url: 'https://hub.shopware.com/learn/unit/paas-project-tooling'
---

# Project Readiness and Essential Tooling

<LearningObjectives>

- Master essential tools: Git workflows, Shopware PaaS CLI, Composer, and YAML configuration.
- Create comprehensive pre-deployment validation checklists.
- Implement security hardening and performance optimization.
- Validate configuration management and environment setup.
- Execute deployment readiness verification.
- Troubleshoot common deployment issues effectively.

</LearningObjectives>

# Project Readiness and Essential Tooling

Now that your repository and environment strategy are in place, it's time to master the daily tools and ensure your project is deployment-ready. This final learning unit focuses on the practical skills and validation processes that make PaaS projects successful.

## Essential Tooling Setup

Before diving into deployment readiness, ensure you have the essential tools configured correctly. These tools will be your daily companions throughout the development and deployment lifecycle.

### Shopware PaaS CLI Setup

The Shopware PaaS CLI is your primary interface for managing projects and deployments. It provides a unified way to interact with all aspects of your PaaS environment.

**Installation and Initial Setup:**

```bash
# Install Shopware PaaS CLI
curl -fsSL https://cli.platform.sh/installer | bash

# Authenticate
platform auth:login

# Verify installation
platform --version

# Set up useful aliases for daily use
alias p='platform'
alias psh='platform ssh'
alias plogs='platform logs app --lines=100'
alias penv='platform environments'
```

### Recap: Git Configuration and Workflows

Shopware PaaS uses Git as the deployment mechanism. Every push triggers a build and deployment, making Git workflow mastery essential.

**Essential Git Setup:**

```bash
# Configure Git (if not already done)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Clone your Shopware PaaS project
platform get PROJECT_ID my-shopware-project
cd my-shopware-project

# Verify remotes (should include 'platform')
git remote -v
```

**Recommended Branching Strategy:**

- `main` → Production environment
- `develop` → Staging environment  
- `feature/*` → Development environments

```bash
# Start with latest develop branch
git checkout develop
git pull platform develop

# Create feature branch
git checkout -b feature/new-feature

# Work on feature, make commits
git add .
git commit -m "Add new feature"
git push platform feature/new-feature

# Merge when ready
git checkout develop
git merge feature/new-feature
git push platform develop
```

### Composer Best Practices

Composer is crucial for dependency management in PHP applications. Proper Composer usage ensures reliable deployments.

**Development Workflow:**

```bash
# Development workflow
composer install

# Production deployment (use in .platform.app.yaml)
composer install --no-dev --optimize-autoloader

# Security auditing
composer audit

# Update specific packages
composer update shopware/core
```

## Deployment Readiness Checklist

### Platform Access and Setup

**Account and Project Setup:**

- Shopware PaaS account activated.
- Project created and accessible via Shopware PaaS CLI.
- Team members are added with appropriate permissions.
- Billing and plan tier confirmed.

**Essential CLI Commands:**

```bash
# Project management
platform project:list
platform project:info
platform project:set-remote PROJECT_ID

# Environment management
platform environments
platform environment:branch staging
platform environment:info

# Access and debugging
platform ssh
platform logs app
platform db:dump
```

### Repository and Version Control

**Git Repository Checklist:**

- Repository properly initialized with `git init`.
- All code is committed and pushed to the repository.
- `.gitignore` configured to exclude sensitive files and directories.
- No secrets or credentials in version control.
- Platform.sh remote added: `platform project:set-remote PROJECT_ID`.

**Critical Files to Exclude:**

```txt
# .gitignore essentials
.env.local
.env.local.php
/var/
/public/media/
/public/thumbnail/
node_modules/
.platform/local/
```

### Platform Configuration Files

**Required Configuration Files:**

- [ ] `.platform.app.yaml` - Application configuration
- [ ] `.platform/services.yaml` - Database and services  
- [ ] `.platform/routes.yaml` - Routing and domains

**Sample .platform.app.yaml:**

```yaml
name: app
type: php:8.2
size: M
disk: 2048

# Build dependencies
dependencies:
  php:
    composer/composer: '^2'

# Web server configuration
web:
  locations:
    '/':
      root: 'public'
      passthru: '/index.php'
      index: ['index.php']
      expires: 1d
      scripts: true
      allow: false
      rules:
        '\.(css|js|gif|jpe?g|png|svg|ico|woff2?|ttf|eot)$':
          allow: true
          expires: 1w

# Persistent file storage
mounts:
  '/var': { source: 'local', source_path: 'var' }
  '/public/media': { source: 'local', source_path: 'media' }
  '/public/thumbnail': { source: 'local', source_path: 'thumbnail' }
  '/files': { source: 'local', source_path: 'files' }

# Build and deployment hooks
hooks:
  build: |
    set -e
    composer install --no-dev --optimize-autoloader
    npm ci
    npm run build
  
  deploy: |
    set -e
    php bin/console cache:clear
    php bin/console database:migrate --all --no-interaction
    php bin/console theme:refresh

workers:
  queue:
    size: S
    commands:
      start: |
        php bin/console messenger:consume async --time-limit=3600
```

**Sample .platform/services.yaml:**

```yaml
# Database configuration
db:
  type: mariadb:10.11
  disk: 4096
  configuration:
    properties:
      max_connections: 200
      innodb_buffer_pool_size: 1G

# Redis for caching and sessions
redis:
  type: redis:7.0
  size: S

# Elasticsearch for product search
elasticsearch:
  type: elasticsearch:8.4
  disk: 2048
  configuration:
    properties:
      xpack.security.enabled: false
```

### Environment Variables Configuration

**Required Environment Variables:**

- `APP_ENV` set to `prod` for production.
- `APP_SECRET` configured with secure random string.
- `DATABASE_URL` configured via Platform.sh relationships.
- Shopware-specific variables configured.

**Environment Variables Checklist:**

```bash
# Core Shopware variables
APP_ENV=prod
APP_SECRET=your-secure-secret-key
SHOPWARE_ES_ENABLED=true
SHOPWARE_ES_HOSTS=elasticsearch.internal:9200
SHOPWARE_HTTP_CACHE_ENABLED=true
SHOPWARE_HTTP_DEFAULT_TTL=3600

# Platform.sh specific
PLATFORM_PROJECT_ID=your-project-id
PLATFORM_ENVIRONMENT=main
```

**Validation Script:**

```bash
#!/bin/bash
# scripts/validate-env.sh

REQUIRED_VARS=(
  "APP_ENV"
  "APP_SECRET" 
  "SHOPWARE_ES_ENABLED"
)

for var in "${REQUIRED_VARS[@]}"; do
  if [ -z "${!var}" ]; then
    echo "❌ Missing: $var"
    exit 1
  fi
done

echo "✅ Environment variables validated"
```

## Application Readiness Validation

### Dependencies and Security

**Composer Dependencies:**

- All dependencies installed: `composer install --no-dev`
- Security audit passed: `composer audit`
- Autoloader optimized: `composer dump-autoload --optimize`
- No development dependencies in production.

**Security Hardening:**

- All secrets moved to environment variables.
- Debug mode disabled in production (`APP_ENV=prod`).
- Error reporting configured appropriately.
- File permissions are set correctly.

### Performance Optimization

**Caching Configuration:**

- HTTP cache enabled (`SHOPWARE_HTTP_CACHE_ENABLED=true`).
- Redis configured for sessions and cache.
- Elasticsearch is configured for product search.
- Static asset optimization enabled.

**Database Optimization:**

```bash
# Database preparation commands
php bin/console database:migrate --all
php bin/console cache:clear --env=prod
php bin/console cache:warmup --env=prod
php bin/console es:index
```

### Configuration Validation

**YAML Syntax Validation:**

```bash
# Validate YAML files
python -c "import yaml; yaml.safe_load(open('.platform.app.yaml'))"
find .platform -name "*.yaml" -exec python -c "import yaml; yaml.safe_load(open('{}'))" \;
```

**Platform.sh Configuration Test:**

```bash
# Test deployment without going live
platform push --no-activate

# Validate configuration
platform app:config-get
platform environment:info
```

## Deployment Workflow and Testing

### Pre-Deployment Testing

**Local Testing Checklist:**

- [ ] Application runs without errors locally.
- [ ] All unit tests pass: `php bin/phpunit`.
- [ ] No linting errors: `php bin/console lint:yaml config/`.
- [ ] Assets compile successfully: `npm run build`.

**Staging Environment Testing:**

```bash
# Deploy to staging first
git checkout develop
git push platform develop

# Test staging environment
platform url -e develop
platform ssh -e develop "php bin/console debug:router"
```

### Quality Gates Script

```bash
#!/bin/bash
# scripts/deployment-checklist.sh

echo "🔍 Running deployment readiness checks..."

# PHP syntax check
find . -name "*.php" -exec php -l {} \; > /dev/null
echo "✅ PHP syntax check passed"

# Composer validation
composer validate --strict --no-check-publish
echo "✅ Composer validation passed"

# YAML validation
find .platform* -name "*.yaml" | xargs -I {} python -c "import yaml; yaml.safe_load(open('{}'))"
echo "✅ YAML validation passed"

# Environment variables check
source scripts/validate-env.sh

# Git status check
if [[ -n $(git status --porcelain) ]]; then
  echo "❌ Uncommitted changes detected"
  exit 1
fi
echo "✅ Git repository clean"

echo "🚀 Ready for deployment!"
```

### Final Deployment

**Production Deployment Process:**

```bash
# Final preparation
./scripts/deployment-checklist.sh

# Ensure we're on the right branch
git checkout main
git merge develop

# Deploy to production
git push platform main

# Monitor deployment
platform logs app -f
```

## Troubleshooting Common Issues

### Git and Platform.sh Issues

**Branch Divergence Issues:**

```bash
# Fix diverged branches
git fetch platform
git reset --hard platform/main

# Force deployment
git commit --allow-empty -m "Force deployment"
git push platform main

# Check deployment status
platform logs deploy
platform environment:info
```

### CLI Authentication Issues

```bash
# Re-authenticate
platform auth:logout
platform auth:login

# Verify access
platform auth:info
platform project:list
```

### Configuration Problems

```bash
# Debug configuration
platform app:config-get
platform environment:relationships

# Check mounted volumes
platform mount:list
platform mount:size
```

## Performance Validation

### Load Testing Preparation

**Basic Performance Checks:**

- Page load times under 2 seconds.
- Database queries optimized.
- Image assets optimized.
- CDN configuration verified.

**Performance Monitoring Setup:**

```bash
# Enable Blackfire for performance profiling
platform variable:create --level environment --name BLACKFIRE_AGENT_SOCKET --value 'tcp://blackfire.internal:8707'

# Check resource usage
platform metrics:all
```

## Next Steps

With your project validated and tools mastered, you're ready for the **Configuration & Deployment** course, where you'll learn advanced deployment strategies, build pipeline optimization, and production configuration management.

<Callout title=" Final Checklist & Best Practices" type="info">

**Git**: Use feature branches, descriptive commits, test before merging to main.

**YAML Configuration**: Validate syntax, consistent indentation, comment complex configurations, use proper data types.

**Testing**: Implement quality gates, test on staging, monitor deployments, validate configuration.

**Security**: Move secrets to environment variables, disable debug mode in production, audit dependencies regularly.

**Performance**: Enable caching, optimize database queries, use CDN, monitor resource usage.

**Readiness Checks:**

- All essential tools are configured.
- Validation checks passed.
- Staging deployment was successful.
- Performance baseline established.
- Team trained on deployment workflows.

</Callout>

You now have both the tools and a systematic approach needed for successful Shopware PaaS deployments.

Congratulations! You've completed the Planning & Bootstrapping course. You now have a solid foundation in project setup, environment strategy, and essential tooling.

In the next course, **Configuration & Deployment**, you'll learn how to take your prepared project and deploy it successfully to production, mastering advanced configuration techniques and CI/CD practices along the way.