# Upsun Integration

DDEV provides integration with the [Upsun by Platform](<https://upsun.com/>) hosting system, allowing Upsun users to easily download database and files from Upsun to a local DDEV-managed environment.

> [!TIP]
>
> Consider using `ddev add-on get ddev/ddev-upsun` ([ddev-upsun](<https://github.com/ddev/ddev-upsun>)) for more complete Upsun integration.

DDEV’s Upsun integration pulls databases and files from an existing Upsun site/environment into your local system so you can develop locally.

## Upsun Global Configuration

You need to obtain and configure an API token first. This only needs to be done once.

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 `$HOME/.ddev/global_config.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)):

   ```
   web_environment:
       - UPSUN_CLI_TOKEN=abcdeyourtoken
   ```

   You can also do this with:

   ```
   ddev config global --web-environment-add="UPSUN_CLI_TOKEN=abcdeyourtoken"
   ```

   > **What if I have more than one API token?**
   >
   > To use multiple API tokens for different projects, add them to your per-project configuration using the [`.ddev/config.local.yaml`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#environmental-overrides>) file instead. This file is gitignored by default.
   >
   > ```
   > web_environment:
   >     - UPSUN_CLI_TOKEN=abcdeyourtoken
   > ```

## Upsun Per-Project Configuration

1. Check out the Upsun site and configure it with [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>). You’ll want to use [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) and make sure the basic functionality is working.
2. Add `PLATFORM_PROJECT` and `PLATFORM_ENVIRONMENT` variables to your project, or rely on automatic derivation when possible.

   - Automatic derivation (no action required):

     - If your repository contains `.upsun/local/project.yaml` with an `id:` key, DDEV will derive `PLATFORM_PROJECT` from that file.
     - If your local Git branch name corresponds to the Upsun environment name, DDEV will derive `PLATFORM_ENVIRONMENT` from the current Git branch.
     - In typical setups where both `.upsun/local/project.yaml` and a matching Git branch exist, you do not need to set `PLATFORM_PROJECT` or `PLATFORM_ENVIRONMENT` manually.
   - Manual configuration (only if automatic derivation is not suitable):

     - Either in `.ddev/config.yaml` or a `.ddev/config.*.yaml` file:

       ```
       web_environment:
           - PLATFORM_PROJECT=abc12def34567
           - PLATFORM_ENVIRONMENT=main
       ```
     - Or with a command from your terminal:

       ```
       ddev config --web-environment-add="PLATFORM_PROJECT=abc12def34567,PLATFORM_ENVIRONMENT=main"
       ```

   For more information about how to set environment variables for containers and services see [Environment Variables](<https://ddev.github.io/ddev/en/stable/users/configuration/environment-variables/index.md>).
3. Run [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>).
4. Run `ddev pull upsun`. After you agree to the prompt, the current upstream databases and files will be downloaded.
5. Optionally use `ddev push upsun` to push local files and database to Upsun. The [`ddev push`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#push>) command can potentially damage your production site, so we don’t recommend using it.

### Managing Multiple Apps

If your environment contains more than one app, add `PLATFORM_APP` variable to your project:

- Either in `.ddev/config.yaml` or a `.ddev/config.*.yaml` file:

  ```
  web_environment:
      - ...
      - PLATFORM_APP=app
  ```
- Or with a command from your terminal:

  ```
  ddev config --web-environment-add="PLATFORM_APP=app"
  ```

### Managing Multiple Databases

If your project has only one database, it will automatically be pulled into and pushed from DDEV’s `db` database.

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.

You can designate the primary database using the `PLATFORM_PRIMARY_RELATIONSHIP` environment variable:

```
ddev config --web-environment-add="PLATFORM_PRIMARY_RELATIONSHIP=main"
```

You can also do the same thing by running `ddev pull upsun` and using the `--environment` flag:

```
ddev pull upsun --environment="PLATFORM_PRIMARY_RELATIONSHIP=main"
```

## Usage

- [`ddev pull upsun`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#pull>) will connect to Upsun to download database and files. To skip downloading and importing either file or database assets, use the `--skip-files` and `--skip-db` flags.
- To pull from a specific environment without permanently changing your project config, pass environment variables using `--environment`:

  ```
  ddev pull upsun --environment="PLATFORM_ENVIRONMENT=main"
  ```

  You can combine multiple variables:

  ```
  ddev pull upsun --environment="PLATFORM_PROJECT=abc12def34567,PLATFORM_ENVIRONMENT=main,PLATFORM_APP=app,PLATFORM_PRIMARY_RELATIONSHIP=main,UPSUN_CLI_TOKEN=abcdeyourtoken"
  ```
- If you need to change the `upsun.yaml` recipe, you can change it to suit your needs, but remember to remove the `#ddev-generated` line from the top of the file.