Upsun Integration¶

DDEV provides integration with the Upsun by Platform hosting system, allowing Upsun users to easily download database and files from Upsun to a local DDEV-managed environment.

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):

   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 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. You’ll want to use ddev 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=nf4amudfn23biyourproject
           - PLATFORM_ENVIRONMENT=main
       

     • Or with a command from your terminal:

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

   For more information about how to set environment variables for containers and services see Environment Variables for Containers and Services.

3. Run ddev 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 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 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.
• 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.