User Documentation

Use Docksal for local development

Upsun Beta

Access our newest offering - Upsun!

Get your free trial by clicking the link below.

Get your Upsun free trial

Docksal is a Docker-based local development tool that plays nicely with It allows you to have fully containerized environments to run everything locally without having to install tools (such as the CLI) on your machine. It’s maintained by a community of developers and is a viable option for most projects.

This guide assumes you have a project already running within If you’re starting from scratch, first create a project from a template.

Before you begin Anchor to this heading

Make sure your computer meets the system requirements for Docksal.

1. Install Docksal Anchor to this heading

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

This installs Docksal and fin, its command-line interface (CLI). For more information on fin, run fin help.

2. Create a projects directory Anchor to this heading

Create a directory to store all of your Docksal projects. It’s recommended to be ~/Projects on Linux/macOS and C:\Projects on Windows. See all restrictions on the projects directory.

3. Add an API token Anchor to this heading

To connect Docksal with your account, use a API token.

  1. Create an API token in the Console.

  2. Add the token to your Docksal configuration by running this command:

    fin config set --global SECRET_PLATFORMSH_CLI_TOKEN="API_TOKEN"

Now you can run fin platform COMMAND from your computer without needing to install the CLI.

4. Get your project Anchor to this heading

To get your project, pull it with the following command:

fin pull init --hosting-platform='platformsh' --hosting-site=PROJECT_ID --hosting-env=ENVIRONMENT_NAME TARGET_DIRECTORY_NAME

This creates a directory with the specified name with all your files and code. It also adds a .docksal directory with all necessary Docksal configuration. These files are ignored by

5. Add commands Anchor to this heading

Docksal doesn’t automatically copy over any commands you have in your build flavor and hooks. To get your project running like on, you have to add the commands to Docksal.

The .docksal/commands directory should already have one command (init) such as the following:

#!/usr/bin/env bash

fin project rm -f
fin project start

This command removes any running Docksal containers and starts new ones. You can add new commands here that run on fin init or create a new file to run on fin NAME_OF_FILE.

You can add your build flavor and hook commands after these commands. That way the Docksal CLI container is running and can process commands.

For example, to install dependencies, use a command like the following depending on your dependency manager:

#!/usr/bin/env bash

fin project rm -f
fin project start

echo "Installing dependencies..."
npm install
#!/usr/bin/env bash

fin project rm -f
fin project start

echo "Installing dependencies..."
fin composer install

6. Run your project Anchor to this heading

Now your project is ready to run. In your project directory, run fin init.

The command returns the project URL http://DIRECTORY_NAME.docksal/. Open this URL to see your project running.

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 Docksal documentation.

Add environment variables Anchor to this heading

If your project requires environment variables for its hooks, add them to the Docksal environment.



To apply your changes, run the following command:

fin project restart

Customize your stack Anchor to this heading

Docksal comes configured with a default PHP container (known as the CLI container), web container, and database container. You can customize the versions for each.

Check the available versions for each by running fin image registry IMAGE. For example, to check the available containers for the app, run fin image registry docksal/cli.

You can then use the version you want by adding it as an environment variable. For example, to use the latest version, run the following command:

fin config set CLI_IMAGE='docksal/cli:latest'

You can also customize the .docksal/docksal.yml file. Use it for a docker-compose definition for your custom configurations.

Import MySQL data into Docksal Anchor to this heading

To download your data from and load it into your Docksal database container, run the following commands:

fin platform db:dump --gzip -f /tmp/database.sql.gz
fin exec 'zcat < /tmp/database.sql.gz | mysql -u user -p user -h db default'

You can also set the username, password, and database name using specific environment variables.

Is this page helpful?