---
title: Configuration in Shopware | Shopware Community Hub
description: Understanding Shopware Configuration Best Practices.
canonical_url: 'https://hub.shopware.com/learn/unit/paas-shopware-configuration'
---

# Configuration in Shopware

<LearningObjectives>

- Understand key configuration aspects of Shopware.
- Learn about environment-specific settings.
- Master security best practices.
- Configure performance optimization settings.

</LearningObjectives>

# Shopware Configuration: Getting It Right From Day One

Configuration is the foundation of every successful deployment—get it right, and your shop will run smoothly; get it wrong, and you'll face endless debugging sessions and potential security issues.

In this learning unit, you'll learn how to configure Shopware correctly on Shopware PaaS, with real examples and common pitfalls to avoid. From environment variables to security settings, ensuring you'll ensure your application is optimized from the start.

<Callout title="Time Saved" type="info">

Following these configuration practices will save you hours of debugging and prevent production issues that could cost thousands in lost sales.

</Callout>

## The Configuration Priorities

Every Shopware project needs three layers of configuration done right:

1. **Environment variables** → Secrets, database connections, and environment-specific settings.
2. **Shopware PaaS YAML files** → Infrastructure, services, and deployment configuration.
3. **Shopware configuration** → Cache settings, performance optimization, and feature flags.

**Get these wrong and you'll face:**

- Security vulnerabilities from exposed secrets.
- Performance issues from misconfigured caching.
- Deployment failures from incorrect service configuration.
- Hours of debugging in production.

## Getting Started: Environment Variables

Imagine you're preparing to launch a new Shopware shop for a client. The first step is to set up your environment variables. These are the "dials and switches" that control how your shop behaves in different contexts.

**Why use environment variables?**

- They keep sensitive data (like secrets and database credentials) out of your codebase.
- They make it easy to switch between development, staging, and production without changing code.

<Callout title="Best Practice" type="info">

Never commit secrets or credentials to your repository. Use environment variables and secret managers provided by your PaaS platform.

</Callout>

### Example: Essential Environment Variables

```dotenv
APP_ENV=prod                           # Set to 'dev' for development, 'prod' for production
APP_SECRET=your-secret-here            # Used for cryptographic operations—keep this safe!
APP_URL=https://your-shop.com          # The public URL of your shop
DATABASE_URL=mysql://user:pass@host:3306/shopware
MAILER_DSN=smtp://localhost:1025       # Mail server configuration
REDIS_HOST=localhost                   # Redis host for caching
```

**Scenario:**  
You're moving your shop from staging to production. By updating `APP_ENV` and `APP_URL`, you instantly adapt your configuration for the new environment—no code changes required.

## How Shopware Loads Configuration

Shopware uses a layered approach to configuration. This means you can have different settings for development and production, and Shopware will automatically pick the right ones.

**Typical structure:**

```yaml
<project root>
└── config
    └── packages
        ├── shopware.yaml           # Main configuration
        ├── dev
        │   └── shopware.yaml      # Development-specific overrides
        └── prod
            └── shopware.yaml      # Production-specific overrides
```

<Callout title="Tip" type="info">

Keep your production configuration as strict and secure as possible. Use the development config to enable debugging and profiling tools.

</Callout>

## Security: Protecting Your Shop from Day One

Security is not an afterthought — it's a core part of your configuration. Shopware provides several ways to keep your shop safe, but you need to use them correctly.

### Common Security Settings

- **CSRF Protection**: Prevents cross-site request forgery attacks.
- **Password Policy**: Enforces strong passwords for all users.
- **API Authentication**: Secured via APP_SECRET (Shopware 6.7+) or JWT keys (earlier versions).

**Example:**

```yaml
# config/packages/shopware.yaml
shopware:
    security:
        csrf:
            enabled: true
            mode: 'twig'
        password_policy:
            upper: 1
            lower: 1
            numeric: 1
            special: 1
            min_length: 8
    api:
        api_browser:
            auth_required: true
        # JWT keys only needed for Shopware 6.6 and earlier
        # Shopware 6.7+ uses APP_SECRET automatically
```

<Callout title="Security Tip" type="info">

Always use unique, strong secrets for APP_SECRET. Since Shopware 6.7, APP_SECRET handles all authentication needs. Never share secrets between environments.

</Callout>

## Performance: Getting the Most Out of Shopware

Performance tuning starts with configuration. Shopware supports advanced caching, search, and system settings to help your shop run smoothly.

### Caching and Search

- **Redis**: Used for fast caching and session storage.
- **OpenSearch/Elasticsearch**: Powers product search and indexing.

**Example:**

```yaml
framework:
    cache:
        app: cache.adapter.redis
        system: cache.adapter.redis
        default_redis_provider: 'redis://localhost'

shopware:
    cache:
        entity_cache:
            enabled: true
            expiration_time: 3600
    elasticsearch:
        enabled: true
        indexing_enabled: true
        hosts: ['localhost:9200']
        index_prefix: 'myshop'
        throw_exception: true
        debug: false
```

<Callout title="Performance Tip" type="info">

Enable Redis and OpenSearch in production for the best results. Use local or in-memory solutions for development.

</Callout>

## Real-World Example: Setting Up a New Project

Let's say you're onboarding a new client. Here's a step-by-step approach:

1. **Clone the project repository** and review the `.env` and config files.
2. **Set environment variables** for the new environment (staging, production, etc.).
3. **Review security settings** in `shopware.yaml` and ensure secrets are unique.
4. **Enable caching and search** for production.
5. **Test configuration** using Shopware CLI:

```bash
bin/console debug:config
bin/console cache:clear
bin/console cache:warmup
bin/console debug:container --env-vars
bin/console config:dump-reference shopware
```

## Common Pitfalls and How to Avoid Them

- **Forgetting to update secrets**: Always generate new secrets for each environment.
- **Committing sensitive data**: Double-check your `.gitignore` and never commit `.env.local` or secret files.
- **Mixing up environments**: Use clear naming and documentation for each environment's config.
- **Not enabling production optimizations**: Make sure caching and search are enabled in production.

## Additional Resources

- [Shopware Configuration Documentation](https://developer.shopware.com/docs/guides/hosting/configurations/)
- [Shopware Security Best Practices](https://developer.shopware.com/docs/resources/references/security.html#security)
- [Shopware CLI Reference](https://developer.shopware.com/docs/resources/references/core-reference/commands-reference.html)

## Key Takeaways

- **Environment Variables**: Use environment variables for all sensitive data and environment-specific settings.
- **Layered Configuration**: Understand how Shopware's layered configuration system works.
- **Security First**: Implement security best practices from day one.
- **Performance Optimization**: Configure caching and search for optimal performance.

## Next Steps

Now that you understand how to configure your Shopware application properly, you're ready to learn how to deploy it successfully.

In the next learning unit, we'll explore the deployment process on Shopware PaaS, including Platform.sh configuration, environment management, and troubleshooting techniques.