Custom configurations are useful when you have a larger or more complex project. Once a CI server is involved
or many people are on a project team, then 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 a docksal.yml
file in the project directory. You can update this file with 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 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,cached
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,cached
# Shared ssh-agent socket
- docksal_ssh_agent:/.ssh-agent:ro
Docksal defines several default stacks that can be used
by setting DOCKSAL_STACK
in your project’s docksal.env
. But if you want to create a custom stack from services
already defined by Docksal, you can declare those services in your docksal.yml
file.
version: "2.1"
services:
db:
extends:
file: ${HOME}/.docksal/stacks/services.yml
service: pgsql
Allowed configuration value overrides are set in the docksal.env
or docksal-local.env
file.
You may add environment
variables that you can pass in through the docksal.env
or docksal-local.env
file or enter as a static value.
MY_CUSTOM_VARIBLE='test key'
cli:
environment:
- MY_CUSTOM_VARIABLE
- MY_STATIC_VARIABLE=api_test_key