Configuration variables can be specified 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.site 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
To disable the docksal-dns built-in service and switch to using the public .docksal.site base domain, run:
fin config set --global DOCKSAL_DNS_DISABLED=1
fin system reset
This automatically sets DOCKSAL_DNS_DOMAIN=docksal.site and DOCKSAL_NO_DNS_RESOLVER=1.
Useful when docksal-dns conflicts with corporate rules or if some other software restricts binding to UDP:53 port
(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 manually.
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: "<unset>"
If set, overrides the internal DOCKER_HOST variable used by Docker / Docker Compose.
This allows pointing Docker client to a different/external Docker host and can be useful in CI scenarios.
Note: Consider using Docker Contexts instead.
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.
When set to 1, fin will check for the availability of release candidate versions. If the newest version available
is a release candidate, it will be download when you run fin update.
fin config set --global DOCKSAL_USE_RC=1
Default: master
Allows for overriding the Docksal version used for checking for updates. Can be used to pin Docksal version.
Install or update to a specific version:
DOCKSAL_VERSION=v1.15.0 bash <(curl -fsSL https://get.docksal.io)
Switch to a specific version (after Docksal is installed)
DOCKSAL_VERSION=v1.15.0 fin update
Pin a specific version for good (no updates)
fin config set --global DOCKSAL_VERSION=v1.15.0
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 CLI Secret. See Acquia CLI.
Acquia CLI Key. See Acquia CLI.
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 variable is part of the hosting integration variable set. Use the environment designation of your hosting provider,
e.g., prod, test, dev. WordPress is the only provider that doesn’t need this. This variable can be overridden by
using the --hosting-env parameter in the fin pull command.
This variable is part of the hosting integration variable set. Use the platform hosting provider associated with your
project acquia, pantheon, platform.sh, or set it to drush or wp. This variable can be overridden by using the
--hosting-platform parameter in the fin pull command.
This variable is part of the hosting integration variable set. Use the site id given by your hosting provider. This
variable can be overridden by using the --hosting-env parameter in the fin pull command.
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!
Enables the auto-stop feature and defines the period after which a project stack is considered inactive and is stopped (e.g., 0.5h).
This feature is disabled by default (set to 0).
Toggles the auto-start feature for projects (automatic start by visiting project url).
This feature is disabled by default (set to 0).
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.