Configuration variables can be specified in the docksal.env file or by running the fin config set command.
There are 2 scopes of variables: global and project. Global scope variables are set in $HOME/.docksal/docksal.env,
while project scope variables are set in $PROJECT_ROOT/.docksal/docksal.env.
# Setting a global scope variable
$ fin config set --global DOCKER_NATIVE=1
Added value for DOCKER_NATIVE into /Users/user/.docksal/docksal.env
# Setting a project scope variable
$ fin config set DOCROOT=web
Added value for DOCROOT into /Users/user/Projects/project/.docksal/docksal.env
Changing the default value of a global variable may or may not require additional steps to apply the changes.
Default: 2048
The default amount of memory allocated to Docksal’s VirtualBox machine, in megabytes.
Default: 50000
The default amount of disk space allocated to Docksal’s VirtualBox machine, in megabytes.
Default: 0
Applicable to macOS or Windows.
Designates whether to run Docker through VirtualBox or Docker Desktop.
For VirtualBox set to 0. For Docker Desktop set to 1.
See Docker Modes for detailed instructions on this variable usage.
Default: 0
Set to 1 to suppress alerts about the outdated Docksal version.
Default: 0
If set to 1, all yes/no confirms will automatically be answered yes.
Useful for CI environments that fake tty and thus “freeze” waiting for user input.
Default: 10
The number of docker log files that should be kept before they are removed.
Default: 1m
The size of the docker logs before they are rotated.
Default: 10s
Can be used to increase container healthcheck interval and thus help with excessive load produced by healthchecks from many concurrently running containers.
Default: docksal
This is the domain name used for Docksal project URLs, i.e., http://$PROJECT_NAME.$DOCKSAL_DNS_DOMAIN.
Project named myproject will result in http://myproject.docksal URL by default.
Can be used to override IP binding for the docksal-dns system service (Linux only).
This is automatically set to 0.0.0.0 (meaning “listen on all network interfaces”) for:
Default: autodetected with fallback to 8.8.8.8
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.
Default: 0
Set to 1 and run fin system reset to disable the DNS resolver configuration.
This can be used if there are issues with DNS resolution on the host machine while running Docksal.
Also check DOCKSAL_DNS_DISABLED as it may be a better option than just disabling the host resolver configuration.
Default: 0
Set to 1 and do fin system reset to disable the docksal-dns built-in service and switch to using the public
.docksal.site base domain. This automatically sets DOCKSAL_DNS_DOMAIN=docksal.site and DOCKSAL_NO_DNS_RESOLVER=1.
Useful when docksal-dns is conflicting with corporate rules or if some other software restricts it
(0.0.0.0:53: bind: address already in use).
Projects that do not override the VIRTUAL_HOST variable will switch to the new docksal.site base domain after running
fin project restart. Projects that hardcode VIRTUAL_HOST will either need to update the value
(e.g., VIRTUAL_HOST=myproject.docksal.site) or use fin hosts command to manage host records.
semi-automatic mode.
Default: 60
How many seconds to give project containers to reach healthy state before fin considers the stack startup as failed.
The value should be a multiple of 5.
Default: 0
When set to 1, this will prevent Docksal from installing and checking for updates.
This is usually good in combination with CI=true.
Default: /Users
macOS only.
Sets the location of the folder on the host machine to mount to VirtualBox or Docker Desktop with NFS.
See file sharing for more information.
Defaults to 0 for non-CI environments and to 1 for CI environments.
When set to 1, project’s stack will prefer the host’s SSH agent (SSH_AUTH_SOCK socket) over the built-in docksal-ssh-agent.
Can be used in conjunction with SSH agent forwarding.
Warning: on Mac and Windows, this will open up an SSH proxy over TCP listening on the internal DOCKSAL_HOST_IP address.
Other users on your system are able to connect to this address and use your SSH agent.
Default: 30001
The TCP port to use to listen on DOCKSAL_HOST_IP when proxying SSH authentication to an agent running on the host.
Only used on Mac and Windows if DOCKSAL_SSH_AGENT_USE_HOST is set to 1.
Default: 0
When set to 1, fin will not send minimal statistic information.
Default: master
Allows for overriding the Docksal version used for checking for updates. Can be used to pin Docksal version.
Can be used to override IP binding for the docksal-vhost-proxy system service (Linux only).
This is automatically set to 0.0.0.0 (meaning “listen on all network interfaces”) for:
CI variable is set to true)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+).
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.
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.
Docker image to use for dns service.
Docker image to use for ssh-agent service.
Docker image to use as the vhost-proxy service.
Acquia Cloud API Email Address. See Acquia Drush Commands.
Acquia Cloud API Key. See Acquia Drush Commands.
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.
Token used for logging in to Pantheon’s CLI Tool Terminus.
Username to use for basic authentication.
Password to use for basic authentication.
Default: local
Allow for environment specific YML and ENV files. fin will load additional configuration from
docksal-${DOCKSAL_ENVIRONMENT}.yml and docksal-${DOCKSAL_ENVIRONMENT}.env.
Default usage is creating docksal-local.yml and/or docksal-local.env for local overrides that are not intended
to be committed.
In CI, you might set the value via export DOCKSAL_ENVIRONMENT=ci in your build script or globally for all projects
on a build/sandbox server via fin config set --global DOCKSAL_ENVIRONMENT=ci. fin will then load
docksal-ci.env and/or docksal-ci.yml (these you do commit) on top of the default configuration files.
Note: DOCKSAL_ENVIRONMENT should not be set and will not work in the project’s docksal.env file (this is by design).
Default: docroot
Defines a relative path to the Document Root of the web server. Final path will be /var/www/$DOCROOT, so by default it is /var/www/docroot. Change it to the desired directory (like http) or sub-directory as needed, or set to . to use the project root as web server Document Root.
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.
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.
Skip Timezone Checking when initializing the the DB engine.
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.
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.
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: root
This variable is mandatory and specifies the password that will be set for the MySQL root superuser account.
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: 5432
The port to use when setting up PostgreSQL.
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 set the newly created user’s password.
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: 0
Enables PHP XDebug Service for debugging. See XDebug.
Default: 0
Enables PHP Xhprof Service for debugging. See Xhprof.
Default: /tmp/xhprof
Location where the Xhprof output should be sent to.
The following variables are used to set images to a specified version. Using them will prevent the images from being udpated when Docksal is updated.
Defaults to the current db image with the default MySQL version defined in ~/.docksal/stacks/services.yml.
See usage
Defaults to the current cli image with the default PHP version defined in ~/.docksal/stacks/services.yml.
See usage
Defaults to the current web image with the default Apache version defined in ~/.docksal/stacks/services.yml.
See usage
The following variables are generally only used within a CI system.
Only use on Linux servers.
When set, enables CI mode:
DOCKSAL_VHOST_PROXY_IP=0.0.0.0, which opens vhost-proxy to the world.DOCKSAL_SSH_AGENT_USE_HOST=1, which enables reuse of the hosts SSH_AUTH_SOCK socket (Linux only).This should be used on sandbox servers (and in CI) at the time of Docksal installation like this:
curl -fsSL https://get.docksal.io | CI=1 bash
Sets path to the Projects directory on the server. Used in conjunction with PROJECT_DANGLING_TIMEOUT.
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!
Defines the timeout of inactivity after which the project stack will be stopped (e.g., 0.5h).
Setting this variable to 0 will disable autostart projects by visiting project url. This option is active by default (set to 1).
If set to true, the sandbox environment will not be removed event after the PROJECT_DANGLING_TIMEOUT timeout.
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.
For simple locally-trusted HTTPS certs for local development needs see mkcert integration.