It is recommended that you first review How Docksal works documentation before reading this manual. You should understand what project containers are and which project containers exist by default.
Understanding stack configurations
Using stack configurations
Docksal images
Docksal relies on Docker Compose to launch groups of related containers. The yml files you use are Compose Files. Please read the documentation to understand their main sections.
Some containers and their parameters are required for Docksal to work properly. Please see Don’t break your Docksal setup! section.
You have to run fin project start (fin p start for short) to apply configuration changes.
If you remove services or volumes you have to remove them with fin project rm [service].
docksal.yml is a Compose file.
It’s the main configuration file for a project and controls its the settings for each service. Use it to
modify settings that are needed for anyone that uses your project.
If you don’t have this file in your project folder, fin will load the default stack, this way providing a zero-configuration setup.
For more details on its role, check loading order.
docksal.env is an Environment file.
It is used to override of some of the default environment variables, without the need for
a full docksal.yml file (e.g., to override MYSQL_ROOT_PASSWORD) or to provide additional environment
variables for your automation scripts (see custom commands).
docksal-local.yml and docksal-local.env are used for additional customizations that happen after the main files
are loaded. See loading order. A good example of their use is exposing custom ports
or switching PHP versions.
These files are intended for local overrides. They should be added to .gitignore and never committed into a project
repo. You can always include an example file in the repo, e.g., example.docksal-local.env, and instruct users to copy
it and adjust as necessary.
Docksal ships with a set of default configurations (stacks), which are yml files stored in $HOME/.docksal/stacks/.
These files are a good reference when you begin creating a custom project configuration.
| File name | Description |
|---|---|
volumes-*.yml |
Different bindings for Docker volumes. The default is volume-bind.yml. Always used for binding volumes. |
services.yml |
Contains default service descriptions. Used for zero-configuration. |
stack-default.yml |
The default stack with 3 services that inherits services.yml. Used for zero-configuration. |
stack-default-static.yml |
Same configuration as stack-default.yml but does not inherit services.yml |
stack-acquia.yml |
Acquia-like stack with Solr, Varnish and memcached |
!!! warning “DO NOT CHANGE DEFAULT STACKS!”
Do not change or customize existing default stacks.
Use the .docksal folder in your project to customize the project configuration.
With this swarm of configuration files, Docksal lets you configure a project in a way that works for you and your team. Just like Bash configuration files (/etc/profile, bashrc, bash_profile, bash_logout), they give the flexibility to configure a Docksal project in dozens of ways.
fin loads files in a certain order. Files loaded later override settings from the files loaded earlier.
The list below goes from the earliest to the latest in this queue.
Loading order:
$HOME/.docksal/stacks/volumes-*.yml - only volumes-bind.yml loads at the moment (volumes in Docksal)$HOME/.docksal/stacks/stack-*.yml - only loads if there is no docksal.yml in the project or if forced by settings the DOCKSAL_STACK variable in docksal.envdocksal.yml - extends the stack if DOCKSAL_STACK is set in docksal.env or completely overrides it otherwisedocksal.env - sets or modifies environment variablesdocksal-local.yml - extends the loaded stack or docksal.ymldocksal-local.env - sets or modifies environment variables set previouslyTo see the files loaded for a particular project run fin config show.
You can simply create a .docksal folder in your project root and run fin project start (fin start for short).
The default stack ($HOME/.docksal/stacks/stack-default.yml) will be loaded and used to create containers in this case.
This is a great way to start developing a new project. This approach can also be used on a permanent basis,
if your needs are simple. stack-default.yml extends the configuration from services.yml,
so you’ll be getting the latest stack versions with every Docksal update.
You can switch between pre-created zero-configuration stacks by adding the following line to your docksal.env file
and running fin project reset.
DOCKSAL_STACK="acquia"
The following stacks are available:
default - web, db, cli (assumed, when none specified)acquia - web, db, cli, varnish, memcached, solr (used specifically for Acquia hosted projects)Custom configurations are useful when you have a larger or more complex project. One where a CI server is involved
or many people are on a project team, and you have to be careful about maintaining software versions.
Having a custom configuration will protect your project from the updates in services.yml when you update Docksal.
fin config generate
This command will create docksal.yml by copying stack-default-static.yml into the project directory.
This file has a fully independent description of services, so future changes to the default stack(s) will no longer
affect the project configuration. This also means that future Docksal updates, bringing new features and changes,
will not automatically apply. You might need to re-generate your static configuration or append those changes manually
in docksal.yml.
Certain configuration settings in yaml files are required for your Docksal stack to function properly.
In the web service, there are settings defined in the volumes, labels, environment, and depends_on sections.
You should not remove or change these values.
web:
volumes:
# Project root volume
- project_root:/var/www:ro,nocopy
labels:
- io.docksal.virtual-host=${VIRTUAL_HOST},*.${VIRTUAL_HOST},${VIRTUAL_HOST}.*
- io.docksal.cert-name=${VIRTUAL_HOST_CERT_NAME:-none}
- io.docksal.project-root=${PROJECT_ROOT}
- io.docksal.permanent=${SANDBOX_PERMANENT:-false}
environment:
- APACHE_DOCUMENTROOT=/var/www/${DOCROOT:-docroot}
# cli has to be up before web
depends_on:
- cli
In the cli service, there is the volumes section. You should not remove or change these volumes.
cli:
volumes:
# Project root volume
- project_root:/var/www:rw,nocopy
# Shared ssh-agent socket
- docksal_ssh_agent:/.ssh-agent:ro
To review the configuration applied to your project run:
fin config show
It does not show the contents or the configuration files directly. Instead, it compiles them together and outputs the resulting configuration. Some important environment variables are listed at the top.
The COMPOSE_FILE section displays files that were used to produce this configuration.
See configuration files load order for more information on how config files are loaded and merged.
A sample output from fin config show:
COMPOSE_PROJECT_NAME: myproject
COMPOSE_PROJECT_NAME_SAFE: myproject
COMPOSE_FILE:
/Users/testuser/.docksal/stacks/volumes-bind.yml
/Users/testuser/.docksal/stacks/stack-default.yml
PROJECT_ROOT: /Users/testuser/projects/myproject
DOCROOT: docroot
VIRTUAL_HOST: myproject.docksal
VIRTUAL_HOST_ALIASES: *.myproject.docksal
IP: 192.168.64.100
MYSQL_PORT:
Docker Compose configuration
---------------------
networks: {}
services:
cli:
hostname: cli
image: docksal/cli:2.5-php7.1
volumes:
- docksal_ssh_agent:/.ssh-agent:ro
- project_root:/var/www:rw,nocopy
db:
environment:
MYSQL_DATABASE: default
MYSQL_PASSWORD: user
MYSQL_ROOT_PASSWORD: root
MYSQL_USER: user
hostname: db
image: docksal/db:1.1-mysql-5.6
web:
depends_on:
- cli
environment:
APACHE_DOCUMENTROOT: /var/www/docroot
hostname: web
image: docksal/web:2.1-apache2.4
labels:
io.docksal.project-root: /Users/testuser/projects/myproject
io.docksal.virtual-host: myproject.docksal
volumes:
- project_root:/var/www:ro,nocopy
version: '2.0'
volumes:
docksal_ssh_agent:
external: true
external_name: docksal_ssh_agent
project_root:
driver: local
driver_opts:
device: /Users/testuser/projects/myproject
o: bind
type: none
---------------------
All variables changed below will require, at minimum, a project restart fin restart so that they can take effect. Additional steps may be required.
The location of the folder on the host machine to mount to VirtualBox. See file sharing for more information.
Default: docksal/ssh-agent:1.0
The Docker image to use for SSH Agent. This contains the keys that are shared among the projects.
Default: docksal/vhost-proxy:1.3
Docker image to use as the VHOST Proxy. This forwards all requests to the appropriate container based upon the hostname that is being requested.
Default: docksal/dns:1.0
Docker image to use for DNS Routing.
When set, this will allow for Docksal to no longer accept updates. This is usually good in combination with CI=true.
Default: local
Allow for environment specific YML and ENV files. fin will load additional configuration from docksal-${DOCKSAL_ENVIRONMENT}.yml and/or docksal-${DOCKSAL_ENVIRONMENT}.env. Default usage is creating docksal-local.yml and docksal-local.env for local overrides that are not intended to be committed.
Default: 0
Allow for collecting of statistical usage of docksal. When set to 1 this will no longer send statistics.
Default: 0
Designates whether to use Docker through VirtualBox or Native Docker. On Linux this is always set to 1. Otherwise it is set to 0.
For VirtualBox set to 0.
For Docker Native set to 1.
Override the default DNS server that Docksal uses. For environments where access to Google DNS server (8.8.8.8) is blocked, it should be set to the LAN DNS server. This is often true for VPN users or users behind a corporate firewall.
Used to set the IP address for the Docksal reverse proxy to listen on. When CI variable is set to true this will be set to 0.0.0.0.
Default: docksal
This is the domain to use which is tacked on to the end of the projects url.
Allow disabling the DNS resolver configuration (in case there are issues with it). Set to true to activate.
Default: root
This variable is mandatory and specifies the password that will be set for the MySQL root superuser account.
This is an optional variable. Set to yes to allow the container to be started with a blank password for the root user. NOTE: Setting this variable to yes is not recommended unless you really know what you are doing, since this will leave your MySQL instance completely unprotected, allowing anyone to gain complete superuser access.
This is an optional variable. Set to yes to generate a random initial password for the root user (using pwgen). The generated root password will be printed to stdout (GENERATED ROOT PASSWORD: …..).
Default: true
When the variable is true (unless MYSQL_ROOT_PASSWORD is set or MYSQL_ALLOW_EMPTY_PASSWORD is set to true), the root user’s password is set as expired and must be changed before MySQL can be used normally. This variable is only supported for MySQL 5.6 and later.
Skip Timezone Checking when initializing the the DB engine.
Default: default
This variable allows you to specify the name of a database to be created on image startup. If a user name and a password are supplied with MYSQL_USER and MYSQL_PASSWORD, the user is created and granted superuser access to this database (corresponding to GRANT ALL). The specified database is created by a CREATE DATABASE IF NOT EXIST statement, so that the variable has no effect if the database already exists.
Default: user
This is used to create a user, and the user is granted superuser permissions for the database specified by the MYSQL_DATABASE variable. Both MYSQL_USER and MYSQL_PASSWORD are required for a user to be created; if any of the two variables is not set, the other is ignored.
Default: user
This is used to set the newly created user’s password.
Default: 3306
The port mapping to use for MySQL container, e.g., 33061:3306 will expose 3306 port as 33061 on the host.
Default: user
This variable allows you to specify the name of a database to be created on image startup.
Default: user
This is used to create a user, and the user is granted superuser permissions for the database specified by the POSTGRES_DB variable.
Default: user
This is used to set the newly created user’s password.
Default: 5432
The port to use when setting up PostgreSQL.
Username to use for basic authentication.
Password to use for basic authentication.
Overrides git user.email inside cli. This is picked up from host’s git settings by default (docksal/cli v2.5+).
Overrides git user.name inside cli. This is picked up from host’s git settings by default (docksal/cli v2.5+).
User ID for the Container User. On MacOS & Linux defaults to current user account id -u.
WARNING: do not override this variable unless you know what you are doing.
Group ID for the Container User. On MacOS & Linux defaults to current group account id -g.
WARNING: do not override this variable unless you know what you are doing.
Default: 0
Enables PHP XDebug Service for debugging. See XDebug.
Use to pass an additional private SSH key. The key is stored in /home/docker/.ssh/id_rsa inside cli and will be considered by the SSH client in addition to the keys loaded in docksal-ssh-agent when establishing a SSH connection from within cli.
Acquia Cloud API Email Address. See Acquia Drush Commands.
Acquia Cloud API Key. See Acquia Drush Commands.
Token used for logging in to Pantheon’s CLI Tool Terminus.
The following variables should only be used within a CI system. They are primarily used for setting up the ability for Docksal to turn off and conserve resources.
Defines the timeout of inactivity after which the project stack will be stopped (e.g., 0.5h).
Defines the timeout of inactivity after which the project stack and code base will be entirely wiped out from the host (e.g., 168h). This requires PROJECTS_ROOT to be set.
WARNING: use at your own risk!
Contains path to the project root directory.
Tells vhost-proxy service which cert to use for the project. Certs are expected in $HOME/.docksal/certs.
Project’s VIRTUAL_HOST setting should match the certificate name.
For VIRTUAL_HOST=example.com, the following cert files must be present on the host:
$HOME/.docksal/certs/example.com.crt
$HOME/.docksal/certs/example.com.key
Also see Default and custom certs for HTTPS.
If set to true, the sandbox environment will not be removed event after the PROJECT_DANGLING_TIMEOUT timeout.
The PHP version is defined by the cli service. The default image used is docksal/cli:2.5-php7.1, which uses PHP 7.1.
A service image name consists of two parts: a docker image name and a tag.
docksal/cli is the name of the docker image, while 2.4-php7.1 is the image tag.
To switch PHP versions you have to change the image used for the cli service to your desired one.
Note: if the project stack is already running, then apply the changes with fin project reset cli. This will properly
reset and update the cli service.
How to find out all supported PHP versions?
When using zero-configuration (or any other), the service image can be overridden in docksal-local.yml.
The same technique is applicable to docksal.yml if DOCKSAL_STACK is set in docksal.env. In this case,
docksal.yml will extend/modify the stack configuration defined in DOCKSAL_STACK instead of overriding it.
To switch the PHP version override the image value for the cli service.
For example, in docksal-local.yml or docksal.yml:
version: "2.1"
services:
cli:
image: docksal/cli:2.5-php7.2
docksal-local.yml will append or modify the configuration that was loaded before it, regardless of whether it was
stack-default.yml or docksal.yml.
docksal.yml will append or modify the configuration only if DOCKSAL_STACK is set in docksal.env.
When not using a predefined stack (docksal.yml is present and DOCKSAL_STACK is not set in docksal.env),
you are in control of everything. In this case the stack configuration is not inherited from
services.yml ($HOME/.docksal/services.yml), so you must fully describe the cli service in the project’s docksal.yml.
An example section of a docksal.yml file that describes the cli service and overrides the PHP version:
services:
cli:
hostname: cli
image: docksal/cli:2.5-php7.2
volumes:
- docksal_ssh_agent:/.ssh-agent:ro
- project_root:/var/www:rw,nocopy
Note: when not using a predefined stack, you must fully describe all other services (web, db, etc.) as well.
Switching MySQL versions is performed in the same way as the PHP version switch.
Instead of the cli service image you will be modifying the db service image.
To see all Docker Hub images produced and supported by Docksal team run:
fin image registry
To get all tags of a certain image provide its name with the same command. For example:
fin image registry docksal/db
This is optional, but highly recommended.
Site provisioning can be automated via a custom command (e.g., fin init, which will call .docksal/commands/init). Put project specific initialization tasks there, like:
For a working example of a Docksal powered project with fin init take a look at: