feat: add required ipv6 records for apex domains

.wordlist.txt

@@ -1,3 +1,4 @@
+AAAA
 ACL
 ACLs
 ADDR
@@ -122,6 +123,7 @@ CHANGELOG
 CKEditor
 CLI
 CMS
+CNAME
 CORS
 CPUs
 CRM
@@ -384,6 +386,7 @@ FPM
 FQCN
 FastRoute
 Fastly
+Fastly's
 Fastorder
 FieldCollection
 FieldSerializer
@@ -1959,6 +1962,7 @@ webpack
 webpackMerge
 webserver
 wednesday
+whatsmydns
 whitespace
 whitespaces
 whoami

products/paas/shopware/cdn/index.md

@@ -23,32 +23,63 @@ Fastly serves as the primary CDN solution for Shopware PaaS Native, delivering e
 
 Fastly is fully integrated into Shopware PaaS Native. The integration includes:
 
-- Pre-configured VCL snippets for optimal Shopware performance
 - Automatic cache invalidation mechanisms
 - Soft purge capabilities to maintain performance during cache updates
 - Deployment helper integration for seamless VCL snippet management
 
 ### Configuration
 
-Fastly is automatically configured and enabled by default in Shopware PaaS Native environments. No additional Shopware configuration is required - the PaaS platform handles all Fastly setup, VCL snippets, and cache management automatically.
+Fastly is automatically configured and enabled by default in Shopware PaaS Native environments. No additional Shopware configuration is required - the PaaS platform handles all Fastly setup and cache management automatically.
 
-#### Custom Domain DNS Configuration
+## Custom Domains
 
-To configure your custom domain with the Fastly CDN, you must configure a DNS record. Depending of the type of your record, the DNS configuration is different.
+### Prerequisites
 
-If you have multiple custom domains, you need to create a record per domain.
+Before adding a custom domain to your Shopware PaaS Native environment, ensure you have:
 
-**None APEX record**
+- 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
 
-Configure a `CNAME` record with your custom domain's DNS to point to:
+### 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 |
+
+### 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:
 
 ```dns
-cdn.shopware.shop
+CNAME: cdn.shopware.shop
 ```
 
-**APEX record**
+**Example:**
 
-Configure a `A` with your custom domain's DNS to point to:
+```dns
+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 four `A` records:
 
 ```dns
 151.101.3.52
@@ -57,10 +88,173 @@ Configure a `A` with your custom domain's DNS to point to:
 151.101.195.52
 ```
 
-This configuration ensures that all traffic to your custom domain is routed through the Fastly CDN for optimal performance and caching.
+**2. IPv6 routing** - Create four `AAAA` records:
+
+```dns
+2a04:4e42::820
+2a04:4e42:200::820
+2a04:4e42:400::820
+2a04:4e42:600::820
+```
+
+**3. Domain ownership** - Create a `TXT` record to prove domain ownership:
+
+```dns
+_shopware-challenge.<domain> IN TXT "shopware-challenge=<organization id>"
+```
+
+Replace `<domain>` with your actual domain and `<organization id>` with your organization ID from `sw-paas org list`.
+
+**Example for domain `example.com` with organization ID `abc123`:**
+
+```dns
+_shopware-challenge.example.com.  IN  TXT  "shopware-challenge=abc123"
+```
+
+::: info
+**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 3.
+:::
+
+### Step 2: 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):**
+
+```bash
+dig shop.example.com CNAME
+```
+
+**For apex domains:**
+
+```bash
+# Verify A records
+dig example.com A
+
+# Verify AAAA records
+dig example.com AAAA
+
+# Verify TXT record
+dig _shopware-challenge.example.com TXT
+```
+
+Ensure the responses match the values you configured in Step 1.
+
+### Step 3: Create Domain in PaaS
+
+Once DNS records are configured and propagated, create the domain using the CLI:
+
+```bash
+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 4: Deploy Application
+
+After successful domain creation, trigger an application deployment to activate the domain:
+
+```bash
+sw-paas application deploy create
+```
+
+Alternatively, you can use:
+
+```bash
+sw-paas application update
+```
+
+You may use the same commit to trigger a deployment.
+
+### Step 5: 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 2) 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](https://www.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**
+   - 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 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 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 info` 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
 
-#### Managing Custom Domains
+If issues persist after trying the above solutions, contact Shopware support with the following information:
 
-Custom domain management is handled through the `sw-paas` CLI domain command. You can attach multiple domains to a single shop. Following domain creation, you must update the application using `sw-paas application update`. You may use the same commit to trigger a deployment. This process will be automated in future releases.
+- 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
 
-Subsequently, you can configure the domain within Shopware and associate it with a storefront. Status update functionality is currently under development.
+This information will help support diagnose and resolve the issue quickly.