Set up your local development environment

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 Platform.sh 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 Platform.sh 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 Platform.sh is DDEV. The integration with DDEV is maintained by Platform.sh 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

You need to have:

• A Platform.sh account: new users can sign up for a free trial account
• A working project
• Git
• The Platform.sh CLI

1. Get your code

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:

   platform get PROJECT_ID TARGET_DIRECTORY_NAME

   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 Platform.sh each time to test them. Instead, you can locally build your application using the Platform.sh 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

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

• Tethered local development involves running your app on a local web server but keeping all other services on Platform.sh and connecting to them over an SSH tunnel.
• Untethered local development involves running your entire site locally, including all services.

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

3. Build your site locally

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.