# Pantheon Integration

DDEV provides configurable integration with the [Pantheon Website Management Platform](<https://pantheon.io/>), which allows Pantheon users to quickly download and provision a project from Pantheon in a local DDEV-managed environment.

DDEV’s Pantheon integration pulls an existing backup from an existing Pantheon site/environment into your local system. That means you must already have a Pantheon site with a backup in order to use it.

## Pantheon Quickstart

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.

> [!TIP]
>
> **`ddev pull pantheon` fails due to Terminus version mismatch**
>
> See [How to Downgrade Terminus in DDEV’s Web Container and Customize Other Bundled Tools](<https://ddev.com/blog/ddev-bundled-tools-using-custom-versions/>).

1. Get your Pantheon machine token:

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

      ```
      web_environment:
          - TERMINUS_MACHINE_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:
   >     - TERMINUS_MACHINE_TOKEN=abcdeyourtoken
   > ```
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`.
3. For `ddev push pantheon` make sure your public SSH key is configured in Pantheon under *Account* → *SSH Keys*.
4. Check out the project codebase from Pantheon. Enable the “Git Connection Mode” and use `git clone` to check out the code locally.
5. Configure the local checkout for DDEV using [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>).
6. Add `DDEV_PANTHEON_SITE` and `DDEV_PANTHEON_ENVIRONMENT` variables to your project `.ddev/config.yaml`:

   ```
   web_environment:
       - DDEV_PANTHEON_SITE=your-project
       - DDEV_PANTHEON_ENVIRONMENT=dev
   ```

   You can also do this with `ddev config --web-environment-add="DDEV_PANTHEON_SITE=your-project,DDEV_PANTHEON_ENVIRONMENT=dev"`.

   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`.

   > **Legacy Variable Names**
   >
   > The old `PANTHEON_SITE` and `PANTHEON_ENVIRONMENT` variable names are still supported for backward compatibility but are deprecated. These names conflict with Pantheon’s own environment variables, which can cause applications to misidentify their runtime environment. Using `DDEV_PANTHEON_SITE` and `DDEV_PANTHEON_ENVIRONMENT` is strongly recommended.
7. Run [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>).
8. Run `ddev pull pantheon`. DDEV will download the Pantheon database and files and bring them into the local DDEV environment. You should now be able to access the project locally.
9. Optionally use `ddev push pantheon` to push local files and database to Pantheon. 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.

## Using Existing Backups vs Fresh Database Dumps

By default, `ddev pull pantheon` generates a fresh database dump, which ensures you get the most current data but can take several minutes. For faster pulls, you can use existing Pantheon backups instead.

To use existing backups, set `DDEV_USE_PANTHEON_BACKUP=true`:

```
# In .ddev/config.yaml
web_environment:
    - DDEV_USE_PANTHEON_BACKUP=true
```

Or use it for a one-time pull:

```
ddev pull pantheon --environment=DDEV_USE_PANTHEON_BACKUP=true
```

> [!TIP]
>
> **When to use existing backups**
>
> - During development when you need to refresh your local environment frequently
> - When the backup is recent enough for your needs
> - When you want faster pull times

> [!WARNING]
>
> **Backup freshness**
>
> Existing backups may not include the very latest data. Check your Pantheon dashboard to see when the last backup was created. Fresh dumps are generated on-demand and reflect the current state of your database.

## Usage

- [`ddev pull pantheon`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#pull>) will connect to Pantheon 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 pantheon --environment="DDEV_PANTHEON_ENVIRONMENT=dev"
  ```

  You can combine multiple variables:

  ```
  ddev pull pantheon --environment="DDEV_PANTHEON_SITE=your-project,DDEV_PANTHEON_ENVIRONMENT=dev,DDEV_USE_PANTHEON_BACKUP=true,TERMINUS_MACHINE_TOKEN=abcdeyourtoken"
  ```
- If you need to change the `pantheon.yaml` recipe, you can change it to suit your needs, but remember to remove the `#ddev-generated` line from the top of the file.