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.
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
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.
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
To start a new Docksal project, initialize the configuration with the
fin config generate command and specify the
fin config generate --docroot=web fin project start
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.
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
# 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.
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 backup 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'
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.