Use Docksal for local development

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

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

Before you begin

Make sure your computer meets the system requirements for Docksal.

1. Install Docksal

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

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

To connect Docksal with your Platform.sh account, use a Platform.sh 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 Platform.sh CLI.

4. Get your project

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 Platform.sh.

5. Add commands

Docksal doesn’t automatically copy over any commands you have in your build flavor and hooks. To get your project running like on Platform.sh, 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

cd "$PROJECT_ROOT"
echo "Installing dependencies..."
npm install

#!/usr/bin/env bash

fin project rm -f
fin project start

cd "$PROJECT_ROOT"
echo "Installing dependencies..."
fin composer install

6. Run your project

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

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

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

fin config set VARIABLE_NAME=VARIABLE_VALUE

VARIABLE_NAME=VARIABLE_VALUE

HOSTING_PLATFORM="platformsh"

To apply your changes, run the following command:

fin project restart

Customize your stack

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

To download your data from Platform.sh 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.