github.com/ddev/ddev@v1.23.2-0.20240519125000-d824ffe36ff3/docs/content/users/providers/platform.md (about)

     1  # Platform.sh Integration
     2  
     3  DDEV provides integration with the [Platform.sh Website Management Platform](https://platform.sh/), which allows Platform.sh users to quickly download and provision a project from Platform.sh in a local DDEV-managed environment.
     4  
     5  !!!tip
     6      Consider using `ddev get ddev/ddev-platformsh` ([platformsh/ddev-platformsh](https://github.com/ddev/ddev-platformsh)) for more complete Platform.sh integration.
     7  
     8  DDEV’s Platform.sh integration pulls databases and files from an existing Platform.sh site/environment into your local system so you can develop locally.
     9  
    10  ## Platform.sh Global Configuration
    11  
    12  You need to obtain and configure an API token first. This is only needed once.
    13  
    14  1. Login to the Platform.sh Dashboard and go to *Account* → *API Tokens*. Create an API token DDEV can use.
    15  2. Add the API token to the `web_environment` section in your global DDEV configuration at `~/.ddev/global_config.yaml`:
    16  
    17  ```yaml
    18  web_environment:
    19    - PLATFORMSH_CLI_TOKEN=abcdeyourtoken
    20  ```
    21  
    22  ## Platform.sh Per-Project Configuration
    23  
    24  1. Check out the site from Platform.sh and configure it with [`ddev config`](../usage/commands.md#config). You’ll want to use [`ddev start`](../usage/commands.md#start) and make sure the basic functionality is working.
    25  2. Add `PLATFORM_PROJECT` and `PLATFORM_ENVIRONMENT` variables to your project.
    26  
    27      * Either in `.ddev/config.yaml` or a `.ddev/config.*.yaml` file:
    28  
    29          ```yaml
    30          web_environment:
    31          - PLATFORM_PROJECT=nf4amudfn23biyourproject
    32          - PLATFORM_ENVIRONMENT=main
    33          ```
    34  
    35      * Or with a command from your terminal:
    36  
    37          ```bash
    38          ddev config --web-environment-add="PLATFORM_PROJECT=nf4amudfn23bi,PLATFORM_ENVIRONMENT=main"
    39          ```
    40  
    41  3. Run [`ddev restart`](../usage/commands.md#restart).
    42  4. Run `ddev pull platform`. After you agree to the prompt, the current upstream databases and files will be downloaded.
    43  5. Optionally use `ddev push platform` to push local files and database to Platform.sh. The [`ddev push`](../usage/commands.md#push) command can potentially damage your production site, so we don’t recommend using it.
    44  
    45  ### Managing Multiple Apps
    46  
    47  If your environment contains more than one app, add `PLATFORM_APP` variable to your project:
    48  
    49  * Either in `.ddev/config.yaml` or a `.ddev/config.*.yaml` file:
    50  
    51      ```yaml
    52      web_environment:
    53      - ...
    54      - PLATFORM_APP=app
    55      ```
    56  
    57  * Or with a command from your terminal:
    58  
    59      ```bash
    60      ddev config --web-environment-add="PLATFORM_APP=app"
    61      ```
    62  
    63  ### Managing Multiple Databases
    64  
    65  If your project has only one database, it will automatically be pulled into and pushed from DDEV’s `'db'` database.
    66  
    67  If your project has multiple databases, they’ll all be pulled into DDEV with their respective remote names. You can optionally designate a *primary* to use DDEV’s default `'db'` database, which may be useful in some cases—particularly if you’ve been using the default solo-database behavior and happened to add another one to your project.
    68  
    69  You can designate the primary database using the `PLATFORM_PRIMARY_RELATIONSHIP` environment variable:
    70  
    71  ```
    72  ddev config --web-environment-add="PLATFORM_PRIMARY_RELATIONSHIP=main"
    73  ```
    74  
    75  You can also do the same thing by running `ddev pull platform` and using the `--environment` flag:
    76  
    77  ```
    78  ddev pull platform --environment="PLATFORM_PRIMARY_RELATIONSHIP=main"
    79  ```
    80  
    81  ## Usage
    82  
    83  * `ddev pull platform` will connect to Platform.sh to download database and files. To skip downloading and importing either file or database assets, use the `--skip-files` and `--skip-db` flags.
    84  * If you need to change the `platform.yaml` recipe, you can change it to suit your needs, but remember to remove the `#ddev-generated` line from the top of the file.