Set up your local development environment

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

Before you begin 

Make sure that:

Note that to run your build locally, you need to set up your dependencies locally unless you use a third-party tool such as DDEV, Docksal or Lando. These Docker-based tools are open-source and cross-platform. They simplify how you can configure your local development environment regardless of how many different projects you have.

If you don’t want to use a Docker-based local development environment tool, you can use:

1. Download your app’s code 

View a list of your projects and environments 

If you have several projects on Platform.sh, you might want to view a list of them before downloading a copy of your code.

To do so, run the platform command. You get output similar to the following:

Your projects are:

+-----------------+--------------+------------------+------------------+
| ID              | Title        | Region           | Organization     |
+-----------------+--------------+------------------+------------------+
| abcdefgh1234567 | project-name | eu.platform.sh   | organization-inc |
+-----------------+--------------+------------------+------------------+

In Platform.sh, each project can have several environments. Each new environment is a child of the environment which you created it from. Child environments can sync code and/or data down from their parent environment. They can also merge code up to their parent, making them a good place for development, staging, and testing.

Before downloading a copy of your code, you might want to view a list of all the environments in your project to pick one.

To do so, run the following command:

platform environments --project PROJECT_ID

You get output similar to the following:

Your environments are: 
+--------------------+------------------+--------+-------------+
| ID                 | Title            | Status | Type        |
+--------------------+------------------+--------+-------------+
| main               | Main             | Active | production  |
|   march-release    | march release    | Active | development |
|   march-tests      | march tests      | Active | development |
|   april-release    | april release    | Active | development |
|   april-tests      | april tests      | Active | development |
+--------------------+------------------+--------+-------------+

Launch the download 

If your app’s code isn’t already present locally on your computer, you can download a copy of it. To do so, move to the directory where you want to save a copy of your project and run this command:

platform get PROJECT_ID

When prompted, choose a name for the target project directory and press Enter. You get output similar to the following:

Downloading [project-name](abcdefgh1234567)
  Cloning into '/Users/username/project-directory'...
  remote: counting objects: 3318, done.        
  Receiving objects: 100% (3318/3318), 20.23 MiB | 3.71 MiB/s, done.
  Resolving deltas: 100% (568/568), done.

The project [project-id](abcdefgh1234567) was successfully downloaded to: 'project-directory'

You can now access your app’s code from the project directory created on your computer. Note that inside the project directory, the .platform/local subdirectory is excluded from Git. It contains builds and any local metadata about your project the Platform.sh CLI needs.

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. Build your site locally 

Before you build your site, check that any runtime or tools needed for the build process are available in your local environment.

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. Run the following command:

    platform build
  2. When prompted, specify the source directory and the build destination.

    Your app is built locally. At the root of your local project directory, a _www subdirectory is created. It is a symbolic link pointing to the currently active build located in the .platform/local/builds directory.

  3. To check that the build was successful:

    • If you are familiar with how to set up a local web server or already have one, you can move to the _www directory to find your build and run your web server and services from there.

    • If you don’t want to set up everything manually, you can switch to a Docker-based local development environment tool such as DDEV, Docksal or Lando.

      Other options include tethered local development and untethered local development.