User Documentation

Set up your local development environment

Sign up for Upsun

Get your free trial by clicking the link below.

Get your Upsun free trial

To make changes to your app’s code and test them without affecting your production environment, set up a local development environment on your computer.

For the most effective testing, you want your local environment to match your environments. The best way to do this is to use a cross-platform tool based on Docker. This ensures the changes you make locally appear as they would on your environments. It also means you don’t have to worry about configuring your machine with the various dependencies, certificates, and connections your app needs to run.

The recommended tool for local development with is DDEV. The integration with DDEV is maintained by to ensure it works smoothly.

Other Docker-based tools are also supported, such as Docksal and Lando. If you choose to use a Docker-based tool, follow the steps on its page. Otherwise, follow these steps to run your app on your computer.

Before you begin Anchor to this heading

You need to have:

1. Get your code Anchor to this heading

If you don’t have your app code on your computer, download a copy.

  1. Get your project ID by running platform projects.

  2. Get the code by running the following command:


    Or pull from your integrated Git repository.

You can now access your code from the project directory on your computer. The CLI created a .platform/applications.yaml/local directory that’s excluded from Git. It contains builds and local metadata about your project.

You can now make changes to your project without pushing to each time to test them. Instead, you can locally build your application using the CLI.

Note that if your app contains services, you need to open an SSH tunnel to connect to them. For more information, see how to connect services.

2. Connect to services Anchor to this heading

If your app requires services to run, you have two options for developing locally:

Choose the option that works for you and get your services running.

3. Build your site locally Anchor to this heading

If you want your local development environment to be enclosed so your main system remains unaffected by the build and its dependencies, you can use a local virtual machine.

To build your site locally:

  1. Install any dependencies or tools needed for the build process.

  2. Run the following command:

    platform build

    Your app is built in the .platform/applications.yaml/local/builds directory. Unless you specify otherwise with the --destination flag, a symbolic link from your build is created as the _www directory at your project root.

  3. To check that the build was successful, move to the _www directory and run a web server.

Is this page helpful?