Custom Domains

Prerequisites

Before adding a custom domain to your Shopware PaaS Native environment, ensure you have:

• Shopware PaaS CLI installed and configured (sw-paas)
• Your organization ID (retrieve it using sw-paas org list)
• A registered domain with access to DNS management
• Permissions to deploy your application

Overview

Custom domains allow you to serve your Shopware shop through your own branded domain while leveraging Fastly's CDN for optimal performance. The platform actively validates your DNS configuration during domain creation to ensure proper routing and security.

Important: DNS records must be configured and fully propagated before creating the domain in the PaaS platform. The domain creation process validates all DNS records in real-time and will fail if they are not correctly configured.

Quick Reference: DNS Records

Record Type	For Apex Domains	For Non-Apex Domains	Target	Count	Purpose
CNAME	No	Yes	cdn.shopware.shop	1	Routes subdomain traffic to Fastly CDN
A	Yes	No	Fastly IPv4 addresses	4	Routes apex domain traffic (IPv4)
AAAA	Yes	No	Fastly IPv6 addresses	4	Routes apex domain traffic (IPv6)
TXT	Yes	No	Domain ownership proof	1	Validates domain ownership

The TXT challenge record applies to apex domains only. If your custom domain is a subdomain, the CNAME record is the only record you need and you can skip Step 2.

Step 1: Configure DNS Records

Configure DNS records at your domain registrar or DNS provider. The required records differ based on whether you're using an apex domain or a subdomain.

For Non-Apex Domains (Subdomains)

If your custom domain is a subdomain (e.g., shop.example.com, www.example.com), create a CNAME record:

CNAME: cdn.shopware.shop

Example:

shop.example.com.  IN  CNAME  cdn.shopware.shop.

For Apex Domains

If your custom domain is an apex/root domain (e.g., example.com), you need to configure multiple record types:

1. IPv4 routing - Create all A records:

151.101.3.52
151.101.67.52
151.101.131.52
151.101.195.52

2. IPv6 routing - Create all AAAA records:

2a04:4e42::820
2a04:4e42:200::820
2a04:4e42:400::820
2a04:4e42:600::820

Step 2: Domain ownership (apex domains only)

Apex domains additionally require a TXT record to prove domain ownership. Skip this step if your custom domain is a subdomain.

_shopware-challenge.<domain> IN TXT "shopware-challenge=<organization id>"

Replace <domain> with your apex domain and <organization id> with your organization ID from sw-paas org list.

Example with the following setup:

• your apex domain is example.com
• your organization ID is abc123

Create the following record:

_shopware-challenge.example.com.  IN  TXT  "shopware-challenge=abc123"

INFO

The challenge record needs to stay as long as the domain is configured in our PaaS.

DNS Propagation Time: DNS changes typically propagate within 15-30 minutes but can take up to 48 hours depending on TTL settings and DNS provider. We strongly recommend waiting for full propagation before proceeding to Step 4.

Use Step 3 to validate all records are correct and propagated.

Step 3: Verify DNS Propagation

Before creating the domain in the PaaS platform, verify that your DNS records have propagated correctly using the dig command or online DNS lookup tools.

For non-apex domains (CNAME):

dig shop.example.com CNAME

For apex domains:

# Verify A records
dig example.com A

# Verify AAAA records
dig example.com AAAA

For the challenge record (apex domains only):

# Verify TXT record
dig _shopware-challenge.example.com TXT

Ensure the responses match the values you configured in Step 1 and 2.

Step 4: Create Domain in PaaS

Once DNS records are configured and propagated, create the domain using the CLI:

sw-paas domain create

You can attach multiple domains to a single shop by running this command for each domain.

WARNING

Active DNS Validation: The platform performs real-time validation of your DNS configuration during domain creation. The following checks must pass:

• For apex domains: A records point to correct Fastly IPv4 addresses, AAAA records point to correct Fastly IPv6 addresses, and TXT record matches your organization ID
• For non-apex domains: CNAME record points to cdn.shopware.shop
• DNS propagation: Records must be resolvable through public DNS

If validation fails, verify your DNS configuration and wait for propagation before retrying.

Step 5: Deploy Application

After successful domain creation, trigger an application deployment to activate the domain:

sw-paas application deploy create

Alternatively, you can use:

sw-paas application update

You may use the same commit to trigger a deployment.

Step 6: Configure in Shopware

After deployment completes:

1. Log in to your Shopware administration panel
2. Navigate to domain/storefront configuration
3. Associate the custom domain with your desired storefront

The domain should now serve traffic through the Fastly CDN.

Troubleshooting

DNS Validation Fails During Domain Creation

Symptoms:

• Error message during sw-paas domain create
• Domain creation rejected or fails validation

Solutions:

1. Verify DNS record configuration

   • Double-check that all required records are configured correctly
   • For apex domains: Ensure all 4 A records, all 4 AAAA records, and the TXT record are present
   • For non-apex domains: Ensure CNAME points to cdn.shopware.shop

2. Check DNS propagation

   • Use dig commands (see Step 3) to verify records are resolvable
   • Try querying from different DNS servers: dig @8.8.8.8 example.com A
   • Use online tools like whatsmydns.net to check global propagation

3. Wait for propagation

   • If records appear correct in your DNS provider but aren't resolving, wait longer for propagation
   • DNS changes can take up to 48 hours in some cases

4. Verify organization ID (apex domains)

   • Run sw-paas org list to confirm your organization ID
   • Ensure the TXT record value exactly matches: shopware-challenge=<your-org-id>

5. Check for typos

   • Verify the domain name is spelled correctly
   • Ensure no extra spaces or characters in DNS records

Domain Created But Not Serving Traffic

Symptoms:

• Domain creation succeeded, but the site is not accessible
• SSL/TLS certificate errors
• Connection timeouts

Solutions:

1. Verify deployment completed

   • Check that Step 4 deployment finished successfully
   • Run sw-paas application deploy get to check application status

2. Check Shopware configuration

   • Ensure domain is associated with a storefront in Shopware admin (Step 5)
   • Verify sales channel configuration

3. Clear caches

   • Clear browser cache and cookies
   • Try accessing the domain in incognito/private browsing mode
   • Clear Shopware caches if necessary

4. DNS propagation delay

   • Even after domain creation, DNS changes may still be propagating globally
   • Wait additional time and retest

Getting Help

If issues persist after trying the above solutions, contact Shopware support with the following information:

• Domain name you're trying to configure
• Your organization ID
• Complete error messages (exact text)
• DNS query results (output from dig commands)
• Timeline of actions taken and when errors occurred
• Screenshots of DNS configuration from your provider

This information will help the support to diagnose and resolve the issue quickly.