Docksal
Contents:
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 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'
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.
Key | Value |
---|---|
DB Name | default |
Username | user |
Password | user |
Host | db |
Port | 3306 |
See the exporting tutorial for information on how to use rsync.