QAG-31: (docs) Improve README.md formatting and readability

- Consolidate duplicate commands across environments

Refs: README.md

Author: tormi

README.md

@@ -5,7 +5,7 @@ This project is a tailored fork of the popular [drupal-composer template](https:
 ## Getting started
 
 1. **Create a new project repository**
-   Click "[Use this template](https://github.com/wunderio/drupal-project/generate)" to generate a new project:
+  Click "[Use this template](https://github.com/wunderio/drupal-project/generate)" to generate a new project:
    - Select the correct owner.
    - Name the project as `client-COUNTRYCODE-CLIENT-PROJECT`.
    - Set the repository to private (unless the project is public).
@@ -77,20 +77,22 @@ This project supports two local development environments: DDEV (preferred) and L
 2. Ensure Docker is running on your system
 3. Start the environment and set up your project:
 
-   ```bash
-   # Start the DDEV environment
-   ddev start
+  ```bash
+  # Start the DDEV environment
+  ddev start
 
-   # Authenticate SSH for database syncing
-   ddev auth ssh
+  # Authenticate SSH for database syncing
+  ddev auth ssh
 
-   # Synchronize local database with a remote environment
-   # See `scripts/syncdb.sh` for options
-   ddev syncdb
+  # Synchronize local database with a remote environment
+  # See `scripts/syncdb.sh` for options
+  ddev syncdb
 
-   # Get a one-time login link for admin access
-   ddev drush uli
-   ```
+  # Get a one-time login link for admin access
+  drush uli
+  ```
+
+Note: All commands in the DDEV section should be run within the DDEV environment using `ddev` prefix (e.g., `ddev drush uli`), or by using `ddev ssh` to access the container shell first.
 
 #### DDEV services and access points
 
@@ -141,9 +143,9 @@ For a complete list of all available services, URLs, and ports, use:
 1. Install [Lando](https://github.com/lando/lando/releases)
 2. Start the environment:
 
-   ```bash
-   lando start
-   ```
+  ```bash
+  lando start
+  ```
 
 #### Lando common commands
 
@@ -194,44 +196,106 @@ This project uses [Cursor](https://docs.cursor.com/) as the recommended AI-power
 
 ### Varnish and Purge configuration
 
-1. **Enable Varnish:**
-   - Uncomment the Varnish configuration in `.lando.yml` under `services → varnish` and `proxy → varnish`.
-   - Run `lando rebuild -y`.
+This section describes how to set up Varnish caching and Purge functionality in your local development environment.
+
+Note: Drush commands in this section should be run with the appropriate environment prefix (`ddev` or `lando`).
+
+#### Configuration Overview
+
+The project includes ready-to-use Varnish configuration:
+
+1. **Configuration Import (Recommended)**
+   - For existing projects, simply import the configuration from `config/sync`:
+
+      ```bash
+      drush cim -y
+      ```
+
+   - This applies all Purge and Varnish settings, including processors and purgers
+
+2. **Manual Configuration (for new sites)**
+   - If config/sync is not available, follow these steps:
+
+   a. **Install required modules**:
+
+      ```bash
+      drush en purge purge_drush purge_processor_lateruntime purge_queuer_coretags purge_tokens purge_ui varnish_purger varnish_purge_tags -y
+      ```
+
+   b. **Configure Varnish Purger**:
+      - Set a value for **Browser and proxy cache maximum age** in `admin/config/development/performance`
+      - Navigate to `/admin/config/development/performance/purge`
+      - Click **Add purger** and select **Varnish Purger**:
+        - **Name:** "Varnish Purger"
+        - **Type:** "Tags"
+        - **Request method:** "BAN" (important: use BAN instead of PURGE for compatibility with Silta)
+        - **Headers:** `Cache-Tags`: `[invalidation:expression]`
+        - Save the configuration
 
-2. **Basic installation profile configuration:**
-   - Install the `basic` profile: `lando drush si basic -y`.
-   - This sets up Purge and Varnish Purge out of the box.
+   c. **Configure processors**:
+      - Go to `/admin/config/development/performance/purge/processors`
+      - Ensure these processors are enabled:
+        - `drush_purge_invalidate` (for manual invalidation via Drush)
+        - `lateruntime` (for batching invalidations)
+        - `purge_ui_block_processor` (for admin UI functionality)
 
-3. **Configuration for installed sites:**
-   - Enable the required modules:
+   d. **Export the configuration**:
 
-     ```bash
-     lando drush en purge purge_drush purge_processor_lateruntime purge_queuer_coretags purge_tokens purge_ui varnish_purger varnish_purge_tags -y
-     ```
+      ```bash
+      drush cex -y
+      ```
 
-   - Set a value for **Browser and proxy cache maximum age** in `admin/config/development/performance`.
-   - Navigate to `/admin/config/development/performance/purge`, click **Add purger**, and select **Varnish Purger**:
-     - **Name:** "Varnish Purger"
-     - **Headers:** `Cache-Tags`: `[invalidation:expression]`
-     - Save the configuration.
-   - Export the configuration:
+   e. **Update settings.php**:
+      - Find the purger ID in `varnish_purger.settings.<PURGER_ID>.yml`
+      - Update `web/sites/default/settings.php` with the correct purger ID:
 
-     ```bash
-     lando drush cex -y
-     ```
+        ```php
+        if (getenv('VARNISH_ADMIN_HOST')) {
+          $config['varnish_purger.settings.<PURGER_ID>']['hostname'] = trim(getenv('VARNISH_ADMIN_HOST'));
+          $config['varnish_purger.settings.<PURGER_ID>']['port'] = getenv('VARNISH_ADMIN_PORT') ? trim(getenv('VARNISH_ADMIN_PORT')) : '80';
+        }
+        ```
+
+#### Environment-Specific Setup
+
+##### DDEV (Recommended)
+
+1. **Varnish Configuration**: DDEV comes pre-configured with Varnish in `.ddev` folder.
+
+2. **Testing Configuration**:
+
+   ```bash
+   ddev drush cr
+   ddev exec curl -X BAN -H "Cache-Tags: config:system.performance" http://varnish
+   ```
+
+   If working correctly, you should receive a "200 Ban added" response
+
+3. **Viewing Varnish logs**:
+
+   ```bash
+   ddev exec -s varnish varnishlog -i BAN -i Cache
+   ```
+
+##### Lando
+
+1. **Enable Varnish**:
+   - Varnish configuration is already enabled in `.lando.yml` & `.lando/varnish.vcl`.
+
+2. **Testing Configuration**:
+
+   ```bash
+   lando drush cr
+   lando ssh -c "curl -X BAN -H 'Cache-Tags: config:system.performance' http://varnish"
+   ```
 
-   - Find the purger ID in the exported `varnish_purger.settings.<PURGER_ID>.yml` file.
-   - Update `web/sites/default/settings.php`:
-     - Replace all occurrences of `varnish_purger.settings.<OLD_ID>` with the new purger ID.
-   - Clear the cache:
+### Important Notes
 
-     ```bash
-     lando drush cr
-     ```
+- **BAN vs PURGE Method:** Always use the "BAN" method in the Varnish purger configuration instead of "PURGE". The Silta Varnish configuration is set up to handle BAN requests but may reject PURGE requests with "405 Method Not Allowed" errors.
 
-   Varnish should now be configured to handle caching and purging when content is updated.
+- **Processors:** The default Purge setup uses the `purge_processor_lateruntime` module, which empties the purge queue during page requests. This works well for most sites needing immediate cache clearing. Ensure all required processors are enabled.
 
-**Note:** The default Purge setup uses the `purge_processor_lateruntime` module, which empties the purge queue during page requests. This works well for most sites needing immediate cache clearing.
+- **Cache Tags:** The Varnish configuration is set up to handle cache tag invalidation with the `Cache-Tags` header.
 </details>
 
 <details>
@@ -243,11 +307,11 @@ The [PHPUnit](https://phpunit.de/) test framework is predefined in this project.
 
 #### Testing examples
 
-Use `lando phpunit` to run PHPUnit commands:
+Note: Run these commands with the appropriate environment prefix (`ddev phpunit` or `lando phpunit`).
 
-- Run one test class: `lando phpunit path/to/your/class/file.php`
-- List groups: `lando phpunit --list-groups`
-- Run all tests in a particular group: `lando phpunit --group Groupname`
+- Run one test class: `phpunit path/to/your/class/file.php`
+- List groups: `phpunit --list-groups`
+- Run all tests in a particular group: `phpunit --group Groupname`
 </details>
 
 ### Secrets handling