Using Docksal for local development

Docksal is a docker based local development tool that plays nicely with Platform.sh. It is maintained by a community of developers and is a viable option for most Platform.sh projects.

See the Docksal documentation for installing and setting up Docksal on your system.

Docksal will ask you to create a .docksal directory in your application root, which functions similarly to the .platform.app.yaml file. It is safe to check this directory into your Git repository as Platform.sh will simply ignore it.

Docksal Fin (fin) is a command line tool for controlling Docksal and used for interacting with a Docksal project. For more information on the use of the fin command, type the help subcommand to get all available commands and options.

fin help

Using Platform.sh CLI within Docksal

The SECRET_PLATFORMSH_CLI_TOKEN must be set to use the Platform.sh CLI within your Docksal project. This is an API Token found with your Platform.sh account and can be generated by going to the API Tokens page and clicking the Create API Token link. This will allow for you to interact with your Platform.sh account from within the CLI container.

fin config set --global SECRET_PLATFORMSH_CLI_TOKEN=XXX

Pulling a Platform.sh project

The Docksal CLI ships with the Platform.sh CLI tool. To use the tool and pull a project locally, make sure you have uploaded your SSH key to your Platform.sh account. Once that is done and a SECRET_PLATFORMSH_CLI_TOKEN has been added using the above step, you can set up your project with the following instructions.

Note: Replace PROJECT_ID with your project's ID, which can found within the Platform.sh dashboard. Replace PROJECT_DIRECTORY with the name of the local directory you'd like the project cloned into.

If you do not already have Platform.sh CLI installed locally, you can use the one in the CLI image. The advantage of this would mean that the tool would never have to be installed locally and therefore is one less dependency.

fin run-cli 'platform get PROJECT_ID -e master PROJECT_DIRECTORY'

If you already have Platform.sh CLI installed locally, you can use that instead.

platform get PROJECT_ID -e master PROJECT_DIRECTORY

Initializing a Platform.sh project

To start a new Docksal project, initialize the configuration with the fin config generate command and specify the docroot flag.

fin config generate --docroot=web
fin project start

The web directory is one of the many different items that can be set for the document. If this is different or changes over time running the following will fix this.

fin config set docroot=XXX # Replacing XXX with the new document root.

Customizing a Platform.sh project

By default, Docksal comes configured with a PHP 7.1 container, an Apache 2.4 web container, and a MySQL 5.6 database container. Additional versions are available in the images and you can set the desired versions by setting following variables within your .docksal/docksal.env file.

# Apache Versions 2.2 / 2.4
#WEB_IMAGE='docksal/web:2.1-apache-2.2'
WEB_IMAGE='docksal/web:2.1-apache-2.4'

# MySQL Version: 5.6 / 5.7 / 8.0
#DB_IMAGE='docksal/db:1.2-mysql-5.6'
DB_IMAGE='docksal/db:1.2-mysql-5.7'
#DB_IMAGE='docksal/db:1.2-mysql-8.0'

# PHP Versions Available 5.6 / 7.0 / 7.1 / 7.2
#CLI_IMAGE='docksal/cli:2.5-php5.6'
#CLI_IMAGE='docksal/cli:2.5-php7.0'
CLI_IMAGE='docksal/cli:2.5-php7.1'
#CLI_IMAGE='docksal/cli:2.5-php7.2'

You can further create and customize a .docksal/docksal.yml file within your project. This is a docker-compose file and can be customized as needed for your application, as some customizations are specific to certain applications. See Docksal documentation on extending stock images.

Downloading MySQL data from Platform.sh into Docksal

In most cases, downloading data from Platform.sh and loading it into your project is straightforward. The following commands, run from your application root, will download a compressed database snapshot and load it into the local Docksal database container.

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

Connecting Projects to the Database

After importing your database into the project the next step is connecting to the database server. The following information can be used for setting up a connection for your application.

See the exporting tutorial for information on how to use rsync.