Upsun User Documentation

Use DDEV for local development

Sign up

Get your free trial by clicking the link below.

Get your Upsun free trial

DDEV is an open-source tool for local development environments. It allows you to use Docker in your workflows while maintaining a GitOps workflow. You get fully containerized environments to run everything locally without having to install tools (including the Upsun CLI, PHP, and Composer) on your machine.

This guide assumes you have a project already running with Upsun and you have the code on your computer.

If you’re starting from scratch, first create a project.

Before you begin Anchor to this heading

Make sure your computer meets the system requirements for DDEV.

For the integration to run smoothly, you also need the following tools:

  • jq
  • base64
  • perl

If you don’t have these already installed, use your normal package manager.

1. Install DDEV Anchor to this heading

To install DDEV, follow the DDEV documentation for your operating system.

This installs the self-contained ddev command-line interface (CLI). For more information on ddev, run ddev help.

2. Add DDEV configuration to your project Anchor to this heading

Get basic configuration set up for your project by running the following command:

ddev config

Follow the prompts to add the correct DDEV configuration files to your repository.

3. Add an API token Anchor to this heading

To connect DDEV with your Upsun account, use a Upsun API token.

First create an API token in the Console.

Then add the token to your DDEV configuration. You can do so globally (easiest for most people):

ddev config global --web-environment-add=UPSUN_CLI_TOKEN=API_TOKEN

You can also add the token only to the project:

ddev config --web-environment-add=UPSUN_CLI_TOKEN=API_TOKEN

4. Optional: Get your project data Anchor to this heading

To get your environment data (files, database), run the following command:

ddev pull upsun

To skip pulling files, add --skip-files to the command. To skip pulling a database, add --skip-db to the command.

5. Run your project Anchor to this heading

Now your project is ready to run:

ddev start

This runs all your hooks and builds your project like on Upsun.

The command returns the project URL as well as a specific port on To see your project running, open one of these URLs.

What’s next Anchor to this heading

You’ve got a project running on a local web server. Now you can add customizations. For more ideas and options, see the DDEV documentation.

Add environment variables Anchor to this heading

If your project requires environment variables for its hooks or runtime, add them to the project’s DDEV environment:


To apply your changes, run the following command:

ddev restart

Is this page helpful?