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.
Make sure your computer meets the system requirements for 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
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.
To connect Docksal with your Platform.sh account, use a Platform.sh API token.
Create an API token in the Console.
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.
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.
.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
or create a new file to run on
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
Now your project is ready to run.
In your project directory, run
The command returns the project URL
Open this URL to see your project running.
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.
If your project requires environment variables for its hooks, add them to the Docksal environment.
fin config set <VARIABLE_NAME>=<VARIABLE_VALUE>
To apply your changes, run the following command:
fin project restart
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
Use it for a docker-compose definition for your custom configurations.
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.