Shopware 6
This guide covers integrating smoxy with Shopware 6. It is written for Shopware 6.7 and 6.6, the two release lines Shopware maintains as of November 2026. Where the two differ, both variants are shown.
INFO
Prerequisites: Complete the Getting Started guide first. Your shop's domain must be routed through smoxy.
Zone Settings
The quickest way to a correctly configured zone is the Online shop preset with the shop system Shopware, offered when you create a zone. It applies these settings:
| Setting | Value | Why Shopware needs it |
|---|---|---|
| Dynamic Cache | On | Caches the storefront HTML at the edge |
| Respect origin Cache-Control | On | Shopware marks pages that must not be shared as private and sets the edge TTL with s-maxage |
| Request Hostname in the cache key | On | Sales channel domains on the same zone serve different pages under the same path |
| Cookie Value in the cache key | sw-cache-hash, sw-currency | Keeps apart the cache variants Shopware creates per customer state (see below) |
| Strip cache-tag headers | On | Shopware's xkey header can grow larger than some clients accept |
| Conditional Rule | Bypass the cache for /admin, /api and /store-api | The Administration and the APIs always need the live shop |
The preset also turns on managed ignored URL parameters, stale cache and image optimization, and adds a rule that caches images by their URI only.
For a zone created without the preset, apply these settings by hand. Also keep the xkey entry in the zone's cache tag headers, which is there by default: smoxy reads the tags in Shopware's purge requests from this header.
WARNING
Why sw-cache-hash belongs in the cache key: Starting with Shopware 6.8, Shopware also caches pages for logged-in customers and filled carts. On Shopware 6.7.6 and later, the CACHE_REWORK feature flag already enables this. The only thing that tells these pages apart from the guest version is the sw-cache-hash cookie. smoxy builds its cache key from the zone settings, not from the Vary header Shopware sends. Without sw-cache-hash in the cache key, a page rendered for one customer, including that customer's prices, could be served to other visitors.
Cache Tagging (Surrogate Keys)
Shopware 6 tags every cacheable response with surrogate keys in the xkey header. When content changes, Shopware tells smoxy which tags to purge, so only the affected pages are cleared instead of the entire cache.
Enable Reverse Proxy Mode
Add the reverse proxy configuration to config/packages/shopware.yaml.
Shopware 6.7:
shopware:
http_cache:
reverse_proxy:
enabled: true
hosts: ["https://smoxy:<token>@example.com"]Shopware 6.6:
shopware:
http_cache:
reverse_proxy:
enabled: true
hosts: ["https://smoxy:<token>@example.com"]
use_varnish_xkey: trueReplace example.com with your shop domain and <token> with the zone's purge token.
INFO
Upgrading to Shopware 6.7: Shopware 6.7 always uses xkey tags, so use_varnish_xkey no longer has any effect. Remove it when upgrading: the option is deprecated, and Shopware 6.8 removes it entirely. The same applies to ban_method, ban_headers and purge_all.
INFO
Shopware 6.5 and older use the configuration key storefront.reverse_proxy instead of shopware.http_cache.reverse_proxy. The key changed with Shopware 6.6.0.
INFO
Cloudflare users: If you use Cloudflare, you must set up a separate subdomain for cache invalidation. See Cloudflare Setup.
Environment Variables
Set these variables in your shop's .env file (or .env.local):
SHOPWARE_HTTP_CACHE_ENABLED=1
SYMFONY_TRUSTED_PROXIES=REMOTE_ADDRSHOPWARE_HTTP_CACHE_ENABLED is on by default. If it is set to 0, Shopware stops marking pages as cacheable and smoxy has nothing to cache.
SYMFONY_TRUSTED_PROXIES tells Shopware to trust the X-Forwarded-For and X-Forwarded-Proto headers smoxy sends, so Shopware sees the visitor's IP address and knows the request arrived over HTTPS. REMOTE_ADDR trusts whichever address connects to Shopware directly. If a load balancer sits between smoxy and Shopware, list the addresses of that hop instead. Since Shopware 6.6, the older TRUSTED_PROXIES variable is no longer read. See Client IP at Your Origin for background.
Optimize Cache Hit Rate (Shopware 6.6 Only)
On Shopware 6.6, reduce cache tag fragmentation by disabling per-item tags for config, snippets, and theme config:
shopware:
cache:
tagging:
each_config: false
each_snippet: false
each_theme_config: falseThis reduces the number of tags written per page, which leads to fewer unnecessary cache invalidations and a higher cache hit rate.
WARNING
Remove this block before upgrading to Shopware 6.7. Shopware 6.7 removed these per-item tags and the shopware.cache.tagging options with them. With the block still in place, Shopware 6.7 stops with an "Unrecognized option" configuration error.
When Changes Reach smoxy
Shopware 6.6 sends invalidations to smoxy immediately. Shopware 6.7 delays them by default: it collects the affected tags and sends them in one batch through the scheduled task shopware.invalidate_cache, every 5 minutes by default. A change saved in the Administration can therefore take up to about five minutes to appear in the storefront. smoxy purges as soon as the request arrives.
- Scheduled tasks must run in your setup (
bin/console scheduled-task:runtogether with a message queue worker). Otherwise the delayed invalidations never leave Shopware. - Admin API requests whose changes must be visible right away can send the header
sw-force-cache-invalidate: 1. bin/console cache:clear:delayedsends all pending invalidations immediately.
Clearing the Entire Cache
To clear its whole HTTP cache, Shopware sends a BAN request without further headers to the configured host. smoxy treats this request as a Flush URL for /, so bin/console cache:clear:http and bin/console cache:clear:all only clear the start page in smoxy. Since Shopware 6.7, bin/console cache:clear no longer touches the HTTP cache at all.
To clear all cached HTML, for example as the last step of a deployment, send a Flush Content Class request to smoxy directly:
curl -X BAN -H "secret: <token>" -H "type: html" https://example.com/type: html clears all cached HTML documents and keeps images and other assets cached. The Clear Cache by Type quick action in the Hub does the same without a token. Use Flush All only when everything has to go.
Multiple Sales Channels
If your Shopware 6 installation uses multiple sales channels with different domains (e.g. country-specific shops), you only need to configure one domain in the reverse proxy hosts setting. Shopware knows which caches to clear for which sales channel and transmits this information to smoxy automatically.
Make sure Request Hostname is part of the zone's cache key (the Shopware preset turns it on). Otherwise the sales channels share cache entries for the same path, and a visitor of one domain could get a page of another.
WARNING
Important: All sales channels of the same Shopware installation must use the same smoxy zone.
