docs: update web_environment usage, fixes ddev#6599 (ddev#6600) [sk…

…ip ci]

Co-authored-by: Stanislav Zhuk <[email protected]>

docs/content/users/debugging-profiling/blackfire-profiling.md

@@ -19,15 +19,15 @@ The Blackfire CLI is built into the web container, so you don’t need to instal
 1. Add the `BLACKFIRE_SERVER_ID`, `BLACKFIRE_SERVER_TOKEN`, `BLACKFIRE_CLIENT_ID`, and `BLACKFIRE_CLIENT_TOKEN` environment variables to `~/.ddev/global_config.yaml` via the `web_environment` key:
 
     ```yaml
-      web_environment:
-      - OTHER_ENV=something
-      - BLACKFIRE_SERVER_ID=dde5f66d-xxxxxx
-      - BLACKFIRE_SERVER_TOKEN=09b0ec-xxxxx
-      - BLACKFIRE_CLIENT_ID=f5e88b7e-xxxxx
-      - BLACKFIRE_CLIENT_TOKEN=00cee15-xxxxx1
+    web_environment:
+        - OTHER_ENV=something
+        - BLACKFIRE_SERVER_ID=dde5f66d-xxxxxx
+        - BLACKFIRE_SERVER_TOKEN=09b0ec-xxxxx
+        - BLACKFIRE_CLIENT_ID=f5e88b7e-xxxxx
+        - BLACKFIRE_CLIENT_TOKEN=00cee15-xxxxx1
     ```
 
-    You can also do this with `ddev config global --web-environment-add="BLACKFIRE_SERVER_ID=<id>,BLACKFIRE_SERVER_TOKEN=<token>,BLACKFIRE_CLIENT_ID=<id>,BLACKFIRE_CLIENT_TOKEN=<token>"`, but any existing environment variables will be deleted.
+    You can also do this with `ddev config global --web-environment-add="BLACKFIRE_SERVER_ID=<id>,BLACKFIRE_SERVER_TOKEN=<token>,BLACKFIRE_CLIENT_ID=<id>,BLACKFIRE_CLIENT_TOKEN=<token>"`.
 
 2. [`ddev start`](../usage/commands.md#start).
 3. `ddev blackfire on`.

docs/content/users/extend/customization-extendibility.md

@@ -37,16 +37,16 @@ You can set custom environment variables in several places:
 
     ```yaml
     web_environment:
-    - MY_ENV_VAR=someval
-    - MY_OTHER_ENV_VAR=someotherval
+        - MY_ENV_VAR=someval
+        - MY_OTHER_ENV_VAR=someotherval
     ```
 
 4. The project’s [`web_environment`](../configuration/config.md#web_environment) setting in `.ddev/config.yaml` or `.ddev/config.*.yaml`:
 
     ```yaml
     web_environment:
-    - MY_ENV_VAR=someval
-    - MY_OTHER_ENV_VAR=someotherval
+        - MY_ENV_VAR=someval
+        - MY_OTHER_ENV_VAR=someotherval
     ```
 
 If you’d rather use the CLI to set the project or global `web_environment` value, you can use the [`ddev config`](../usage/commands.md#config) command:

docs/content/users/install/ddev-installation.md

@@ -404,18 +404,18 @@ Once you’ve [installed a Docker provider](docker-installation.md), you’re re
 
     You can expose ports via the `ports` setting, which is usually not recommended if you work locally due to port conflicts. But you can load these additional Docker compose files only when Codespaces is detected. See [Defining Additional Services](./../extend/custom-compose-files.md#docker-composeyaml-examples) for more information. 
 
-    ```
+    ```yaml
     services:
         web:
             ports:
-            - "5174:5174"
+                - "5174:5174"
     ```
 
     ### Default environment variables
 
     Codespace instances already provide some [default environment values](https://docs.github.com/en/codespaces/developing-in-codespaces/default-environment-variables-for-your-codespace). You can inherit and inject them in your `.ddev/config.yaml`:
 
-    ```
+    ```yaml
     web_environment: 
         - CODESPACES
         - CODESPACE_NAME

docs/content/users/providers/acquia.md

@@ -9,20 +9,32 @@ DDEV’s Acquia integration pulls database and files from an existing project in
 1. Get your Acquia API token from *Account Settings* → *API Tokens*.
 2. Make sure you’ve added your SSH key to your Acquia account in *Account Settings* → *SSH Keys*.
 3. Run [`ddev auth ssh`](../usage/commands.md#auth-ssh). (Typically once per DDEV session, not every pull.)
-4. In `~/.ddev/global_config.yaml` (or the project `config.yaml`), add or update the [`web_environment`](../configuration/config.md#web_environment) section with the API keys:
+4. In `~/.ddev/global_config.yaml` add or update the [`web_environment`](../configuration/config.md#web_environment) section with the API keys:
 
-   ```yaml
-   web_environment:
-   - ACQUIA_API_KEY=xxxxxxxx
-   - ACQUIA_API_SECRET=xxxxx
-   ```
+    ```yaml
+    web_environment:
+        - ACQUIA_API_KEY=xxxxxxxx
+        - ACQUIA_API_SECRET=xxxxx
+    ```
+
+    You can also do this with:
+
+    ```bash
+    ddev config global --web-environment-add="ACQUIA_API_KEY=xxxxxxxx,ACQUIA_API_SECRET=xxxxx"
+    ```
 
 5. In the project `.ddev/config.yaml` add the `ACQUIA_ENVIRONMENT_ID` environment variable:
 
-   ```yaml
-   web_environment:
-   - ACQUIA_ENVIRONMENT_ID=yoursite.dev
-   ```
+    ```yaml
+    web_environment:
+        - ACQUIA_ENVIRONMENT_ID=yoursite.dev
+    ```
+
+    You can also do this with:
+
+    ```bash
+    ddev config --web-environment-add="ACQUIA_ENVIRONMENT_ID=yoursite.dev"
+    ```
 
 6. Run [`ddev restart`](../usage/commands.md#restart).
 7. Use `ddev pull acquia` to pull the project database and files.

docs/content/users/providers/index.md

@@ -1,6 +1,6 @@
 # Hosting Provider Integration
 
-DDEV offers hosting provider integration and sample integrations for [Pantheon](https://pantheon.io), [Platform.sh](https://platform.sh) and [Acquia](https://www.acquia.com) hosting, along with other examples.
+DDEV offers hosting provider integration and sample integrations for [Pantheon](https://pantheon.io), [Platform.sh](https://platform.sh), [Upsun](https://upsun.com/), [Lagoon](https://lagoon.sh/) and [Acquia](https://www.acquia.com) hosting, along with other examples.
 
 Hosting provider integration allows connecting with your upstream hosting. `ddev pull <provider>` downloads and `ddev push <provider>` uploads the **database** and the **user-generated files** to an upstream provider. It does *not* push (deploy) or pull your code. Your code should be under version control in for example Git.
 
@@ -14,26 +14,37 @@ DDEV also provides the `push` command to push database and files to upstream. Th
 
 Each provider recipe is a YAML file that can have whatever name you want. The examples are mostly named after the hosting providers, but they could be named `upstream.yaml` or `live.yaml`, so you could `ddev pull upstream` or `ddev pull live`. If you wanted different upstream environments to pull from, you could name one “prod” and one “dev” and `ddev pull prod` and `ddev pull dev`.
 
-[Recipes](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/) are provided for [Acquia](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/acquia.yaml), [Local files](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/localfile.yaml.example) (like Dropbox, for example), [Pantheon](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/pantheon.yaml.example), [Platform.sh](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/platform.yaml), and [rsync](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/rsync.yaml.example). We know you’ll find improvements to these examples and will have lots to contribute for other hosting providers, and we look forward to your contributions as pull requests here or in [ddev-contrib](https://github.com/ddev/ddev-contrib).
+[Recipes](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/) are provided for:
+
+- [Acquia](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/acquia.yaml)
+- [Git](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/git.yaml.example)
+- [Lagoon](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/lagoon.yaml)
+- [Local files](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/localfile.yaml.example) (like Dropbox, for example)
+- [Pantheon](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/pantheon.yaml.example)
+- [Platform.sh](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/platform.yaml)
+- [rsync](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/rsync.yaml.example)
+- [Upsun](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/upsun.yaml)
+
+We know you’ll find improvements to these examples and will have lots to contribute for other hosting providers, and we look forward to your contributions as pull requests here or in [ddev-contrib](https://github.com/ddev/ddev-contrib).
 
 Each provider recipe is a file named `<provider>.yaml` and consists of several mostly-optional stanzas:
 
-* `environment_variables`: Environment variables will be created in the web container for each of these during pull or push operations. They’re used to provide context (project ID, environment name, etc.) for each of the other stanzas. This stanza is not used in more recent hosting integrations, since providing the environment variables in `config.yaml` or via `ddev pull xxx --environment=VARIABLE=value` is preferred.
-* `db_pull_command`: A script that determines how DDEV should obtain a database. Its job is to create a gzipped database dump in `/var/www/html/.ddev/.downloads/db.sql.gz`. This is optional; if nothing has to be done to obtain the database dump, this step can be omitted.
-* `db_import_command`: (optional) A script that imports the downloaded database. This is for advanced usages like multiple databases. The default behavior only imports a single database into the `db` database. The [localfile example](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/localfile.yaml.example) uses this technique.
-* `files_pull_command`: A script that determines how DDEV can get user-generated files from upstream. Its job is to copy the files from upstream to `/var/www/html/.ddev/.downloads/files`. If nothing has to be done to obtain the files, this step can run `true`.
-* `files_import_command`: (optional) A script that imports the downloaded files. There are a number of situations where it’s messy to push a directory of files around, and one can put it directly where it’s needed. The [localfile example](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/localfile.yaml.example) uses this technique.
-* `db_push_command`: A script that determines how DDEV should push a database. Its job is to take a gzipped database dump from `/var/www/html/.ddev/.downloads/db.sql.gz` and load it on the hosting provider.
-* `files_push_command`: A script that determines how DDEV push user-generated files to upstream. Its job is to copy the files from the project’s user-files directories (`$DDEV_FILES_DIRS`) to the correct places on the upstream provider.
+- `environment_variables`: Environment variables will be created in the web container for each of these during pull or push operations. They’re used to provide context (project ID, environment name, etc.) for each of the other stanzas. This stanza is not used in more recent hosting integrations, since providing the environment variables in `config.yaml` or via `ddev pull xxx --environment=VARIABLE=value` is preferred.
+- `db_pull_command`: A script that determines how DDEV should obtain a database. Its job is to create a gzipped database dump in `/var/www/html/.ddev/.downloads/db.sql.gz`. This is optional; if nothing has to be done to obtain the database dump, this step can be omitted.
+- `db_import_command`: (optional) A script that imports the downloaded database. This is for advanced usages like multiple databases. The default behavior only imports a single database into the `db` database. The [localfile example](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/localfile.yaml.example) uses this technique.
+- `files_pull_command`: A script that determines how DDEV can get user-generated files from upstream. Its job is to copy the files from upstream to `/var/www/html/.ddev/.downloads/files`. If nothing has to be done to obtain the files, this step can run `true`.
+- `files_import_command`: (optional) A script that imports the downloaded files. There are a number of situations where it’s messy to push a directory of files around, and one can put it directly where it’s needed. The [localfile example](https://github.com/ddev/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/localfile.yaml.example) uses this technique.
+- `db_push_command`: A script that determines how DDEV should push a database. Its job is to take a gzipped database dump from `/var/www/html/.ddev/.downloads/db.sql.gz` and load it on the hosting provider.
+- `files_push_command`: A script that determines how DDEV push user-generated files to upstream. Its job is to copy the files from the project’s user-files directories (`$DDEV_FILES_DIRS`) to the correct places on the upstream provider.
 
 The [environment variables provided to custom commands](../extend/custom-commands.md#environment-variables-provided) are also available for use in these recipes.
 
 There are [hooks](../configuration/hooks.md) available to execute commands before and after each pull or push: `pre-pull`, `post-pull`, `pre-push`, `post-push`. These could be for example a [`ddev snapshot`](../usage/commands.md#snapshot) to backup the database before a pull or a specific task to clear/warm-up caches of your application.
 
 ## Example Integrations and Hints
 
-* All of the [supplied integrations](https://github.com/ddev/ddev/tree/master/pkg/ddevapp/dotddev_assets/providers) are examples of what you can do.
-* You can name a provider anything you want. For example, an Acquia integration doesn’t have to be named “acquia”, it can be named “upstream”. This is a great technique for [downloading a particular multisite](https://stackoverflow.com/a/68553116/215713).
+- All of the [supplied integrations](https://github.com/ddev/ddev/tree/master/pkg/ddevapp/dotddev_assets/providers) are examples of what you can do.
+- You can name a provider anything you want. For example, an Acquia integration doesn’t have to be named “acquia”, it can be named “upstream”. This is a great technique for [downloading a particular multisite](https://stackoverflow.com/a/68553116/215713).
 
 ## Provider Debugging
 

docs/content/users/providers/lagoon.md

@@ -5,7 +5,20 @@ DDEV provides integration with [Lagoon](https://lagoon.sh/), allowing users to q
 ## Lagoon Per-Project Configuration
 
 1. Check out the Lagoon project and configure it by running [`ddev config`](../usage/commands.md#config). You’ll want to run [`ddev start`](../usage/commands.md#start) and make sure the basic functionality is working.
-2. Add `LAGOON_PROJECT` and `LAGOON_ENVIRONMENT` variables to your project using `'web_environment'` in its YAML configuration or a `.ddev/.env` file. For example, run `ddev config --web-environment-add="LAGOON_PROJECT=<project-name>,LAGOON_ENVIRONMENT=<environment-name>"`.
+2. Add `LAGOON_PROJECT` and `LAGOON_ENVIRONMENT` variables to your project using `'web_environment'` in its YAML configuration or a `.ddev/.env` file. For example:
+
+    ```yaml
+    web_environment:
+        - LAGOON_PROJECT=<project-name>
+        - LAGOON_ENVIRONMENT=<environment-name>
+    ```
+
+    You can also do this with:
+
+    ```bash
+    ddev config --web-environment-add="LAGOON_PROJECT=<project-name>,LAGOON_ENVIRONMENT=<environment-name>"
+    ```
+
 3. Configure an [SSH key](https://docs.lagoon.sh/using-lagoon-advanced/ssh/) for your Lagoon user.
 4. Run `ddev auth ssh` to make your SSH key available in the project’s web container.
 5. Run [`ddev restart`](../usage/commands.md#restart).

docs/content/users/providers/pantheon.md

@@ -9,12 +9,13 @@ DDEV’s Pantheon integration pulls an existing backup from an existing Pantheon
 If you have DDEV installed, and have an active Pantheon account with an active site, you can follow this guide to spin up a Pantheon project locally.
 
 1. Get your Pantheon machine token:
-   a. Log in to your Pantheon Dashboard and [Generate a Machine Token](https://pantheon.io/docs/machine-tokens/) for DDEV to use.
-   b. Add the API token to the `web_environment` section in your global DDEV configuration at `~/.ddev/global_config.yaml`.<!-- markdownlint-disable-next-line -->
-   ```
-   web_environment:
-   - TERMINUS_MACHINE_TOKEN=abcdeyourtoken
-   ```
+    1. Log in to your Pantheon Dashboard and [Generate a Machine Token](https://pantheon.io/docs/machine-tokens/) for DDEV to use.
+    2. Add the API token to the `web_environment` section in your global DDEV configuration at `~/.ddev/global_config.yaml`.
+
+        ```yaml
+        web_environment:
+            - TERMINUS_MACHINE_TOKEN=your_token
+        ```
 
 2. Choose a Pantheon site and environment you want to use with DDEV. You can usually use the site name, but in some environments you may need the site ID, which is the long third component of your site dashboard URL. So if the site dashboard is at `https://dashboard.pantheon.io/sites/009a2cda-2c22-4eee-8f9d-96f017321555#dev/`, the site ID is `009a2cda-2c22-4eee-8f9d-96f017321555`.
 

docs/content/users/providers/platform.md

@@ -14,10 +14,16 @@ You need to obtain and configure an API token first. This is only needed once.
 1. Login to the Platform.sh Dashboard and go to *Account* → *API Tokens*. Create an API token DDEV can use.
 2. Add the API token to the `web_environment` section in your global DDEV configuration at `~/.ddev/global_config.yaml`:
 
-```yaml
-web_environment:
-  - PLATFORMSH_CLI_TOKEN=abcdeyourtoken
-```
+    ```yaml
+    web_environment:
+        - PLATFORMSH_CLI_TOKEN=abcdeyourtoken
+    ```
+
+    You can also do this with:
+
+    ```bash
+    ddev config global --web-environment-add="PLATFORMSH_CLI_TOKEN=abcdeyourtoken"`
+    ```
 
 ## Platform.sh Per-Project Configuration
 
@@ -28,8 +34,8 @@ web_environment:
 
         ```yaml
         web_environment:
-        - PLATFORM_PROJECT=nf4amudfn23biyourproject
-        - PLATFORM_ENVIRONMENT=main
+            - PLATFORM_PROJECT=nf4amudfn23biyourproject
+            - PLATFORM_ENVIRONMENT=main
         ```
 
     * Or with a command from your terminal:
@@ -50,8 +56,8 @@ If your environment contains more than one app, add `PLATFORM_APP` variable to y
 
     ```yaml
     web_environment:
-    - ...
-    - PLATFORM_APP=app
+        - ...
+        - PLATFORM_APP=app
     ```
 
 * Or with a command from your terminal:
@@ -68,13 +74,13 @@ If your project has multiple databases, they’ll all be pulled into DDEV with t
 
 You can designate the primary database using the `PLATFORM_PRIMARY_RELATIONSHIP` environment variable:
 
-```
+```bash
 ddev config --web-environment-add="PLATFORM_PRIMARY_RELATIONSHIP=main"
 ```
 
 You can also do the same thing by running `ddev pull platform` and using the `--environment` flag:
 
-```
+```bash
 ddev pull platform --environment="PLATFORM_PRIMARY_RELATIONSHIP=main"
 ```
 

docs/content/users/providers/upsun.md

@@ -11,10 +11,16 @@ You need to obtain and configure an API token first. This only needs to be done
 1. Login to the Upsun Dashboard and go to *My Profile* → *API Tokens*. Create an API token DDEV can use.
 2. Add the API token to the `web_environment` section in your global DDEV configuration at `~/.ddev/global_config.yaml`:
 
-```yaml
-web_environment:
-  - UPSUN_CLI_TOKEN=abcdeyourtoken
-```
+    ```yaml
+    web_environment:
+        - UPSUN_CLI_TOKEN=abcdeyourtoken
+    ```
+
+    You can also do this with:
+
+    ```bash
+    ddev config global --web-environment-add="UPSUN_CLI_TOKEN=abcdeyourtoken"
+    ```
 
 ## Upsun Per-Project Configuration
 
@@ -25,8 +31,8 @@ web_environment:
 
         ```yaml
         web_environment:
-        - UPSUN_PROJECT=nf4amudfn23biyourproject
-        - UPSUN_ENVIRONMENT=main
+            - UPSUN_PROJECT=nf4amudfn23biyourproject
+            - UPSUN_ENVIRONMENT=main
         ```
 
     * Or with a command from your terminal:

docs/content/users/usage/cms-settings.md

@@ -93,10 +93,10 @@ $settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml'
 
         ```yaml
         web_environment:
-          # Make DDEV Drush shell PIDs last for entire life of the container
-          # so `ddev drush site:set @alias` persists for all Drush connections.
-          # https://chrisfromredfin.dev/posts/drush-use-ddev/
-          - DRUSH_SHELL_PID=PERMANENT
+            # Make DDEV Drush shell PIDs last for entire life of the container
+            # so `ddev drush site:set @alias` persists for all Drush connections.
+            # https://chrisfromredfin.dev/posts/drush-use-ddev/
+            - DRUSH_SHELL_PID=PERMANENT
         ```
 
 ### TYPO3 Specifics
@@ -111,7 +111,7 @@ Since TYPO3 9.5 you have to setup a `Site Configuration` for each site you like
 
 ```yaml
 web_environment:
-- TYPO3_CONTEXT=Development/DDEV
+    - TYPO3_CONTEXT=Development/DDEV
 ```
 
 This variable will be available after the project start or restart.