Stack configuration

It is recommended that you familiarize yourself with the Docksal stack documentation before reading this manual. You should understand what project containers are and which project containers exist by default.

Understanding stack configurations

  1. Basics
  2. Project configuration files
  3. Default stacks
  4. Configuration files loading order

Using stack configurations

  1. Zero-configuration
  2. Custom configuration
  3. Don't break your Docksal setup! List of must have values.
  4. Checking your configuration

Docksal images

  1. Switching PHP version
  2. Switching MySQL version
  3. Finding supported PHP/MySQL/etc. versions

Basics

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.

REMEMBER DOCKSAL REQUIREMENTS

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].

Project configuration files

docksal.yml

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

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 (for example, to override MYSQL_ROOT_PASSWORD) or to provide additional environment variables for your automation scripts (see custom commands.)

docksal-local.yml, docksal-local.env

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 port 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.

Default stacks

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

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.

Configuration files loading order

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:

  1. $HOME/.docksal/stacks/volumes-*.yml - only volumes-bind.yml loads at the moment (volumes in Docksal.)
  2. $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.env.
  3. docksal.yml - extends the stack if DOCKSAL_STACK is set in docksal.env or completely overrides it otherwise.
  4. docksal.env - sets or modifies environment variables.
  5. docksal-local.yml - extends the loaded stack or docksal.yml.
  6. docksal-local.env - sets or modifies environment variables set previously.

To see the files loaded for a particular project run fin config show.

Zero-configuration

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.

Zero-configuration stacks

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 configuration

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.

Don't break your Docksal setup! List of must have values.

REQUIREMENTS

Some must have values for your Docksal stack to work properly.

There are some values that are not required for docker-compose to work but are required for your Docksal stack to function.

web

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}
      - io.docksal.project-root=${PROJECT_ROOT}
    environment:
      - APACHE_DOCUMENTROOT=/var/www/${DOCROOT:-docroot}
    # cli has to be up before web
    depends_on:
      - cli

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

Checking project configuration

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.0-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

---------------------

Switching PHP versions

The PHP version is defined by the cli service. The default image used is docksal/cli:2.0-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.0-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.

How to find out all supported PHP versions?

Extend or modify config with docksal-local.yml or docksal.yml

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.0-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.

Override config with docksal.yml

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.0-php7.2
    volumes:
    - docksal_ssh_agent:/.ssh-agent:ro
    - project_root:/var/www:rw,nocopy

Note, that when not using a predefined stack, you must fully describe all other services (web, db, etc.) as well.

Switching MySQL versions

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.

Docksal images and versions

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. E.g.:

fin image registry docksal/db

Automate the initialization process

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:

  • initialize the Docksal configuration.
  • import databases or perform a site install.
  • compile SASS.
  • run DB updates, special commands, etc.
  • run Behat tests.

For a working example of a Docksal powered project with fin init take a look at: