configuration.md

Configuration

To setup a configuration parameter, use set function, and to get it inside task use get function.

set('param', 'value');

task('deploy', function () {
    $param = get('param');
});

Each parameter can be overridden for each host:

host(...)
    ->set('param', 'new value');

Configuration parameters also can be specified as callback function, which will be executed on remote host on first get call:

set('current_path', function () {
    return run('pwd');
});

You can use a param's values inside run calls with {{ }}, instead of doing this:

run('cd ' . get('release_path') . ' && command');

You can do this:

run('cd {{release_path}} && command');

Common recipe comes with a few predefined config params listed below.

To get list of available params run:

dep config:dump

Show current deployed release:

dep config:current

Show inventory:

dep config:hosts

Below is a list of common variables.

deploy_path

Where to deploy application on remote host. You should define this variable for all of your hosts. For example, if you want to deploy your app to home directory:

host(...)
    ->set('deploy_path', '~/project');

hostname

Current hostname. Automatically set by host function.

user

Current user name. Defaults to the current git user name:

set('user', function () {
    return runLocally('git config --get user.name');
});

You can override it in deploy.php for example to use env var:

set('user', function () {
    return getenv('DEP_USER');
});

user parameter can be used to configure notification systems:

set('slack_text', '{{user}} deploying {{branch}} to {{hostname}}');

release_path

Full path to the current release directory. Current dir path in non-deploy contexts. Use it as working path for your build:

task('build', function () {
    cd('{{release_path}}');
    // ...
});

By default, working path is release_path for simple task:

task('build', 'webpack -p');

previous_release

Points to previous release if it exists. Otherwise variable doesn't exist.

task('npm', function () {
    if (has('previous_release')) {
        run('cp -R {{previous_release}}/node_modules {{release_path}}/node_modules');
    }
    
    run('cd {{release_path}} && npm install');
});

ssh_multiplexing

Use ssh multiplexing to speedup the native ssh client.

set('ssh_multiplexing', true);

default_stage

If the hosts declaration has stages, this option allows you to select the default stage to deploy with dep deploy.

set('default_stage', 'prod');

host(...)
    ->stage('prod');

You can also set callable as an argument if you need some more complex ways to determine default stage.

Having callable in set() allows you to not set the value when declaring it, but later when it is used. There is no difference when we assign a simple string. But when we assign value of a function, then this function must be called at once, if not used as callable. With callable, it can be called when used, so a function which determines a variable can be overwritten by the user with its own function. This is the great power of having callable in set() instead of direct in function calls.

Example 1: Direct function assign in set()

Lets assume that we must include some third party recipe that is setting 'default_stage' like this:

set('default_stage', \ThirdPartyVendor\getDefaultStage());

And we want to overwrite this in our deploy.php with our own value:

set('default_stage', \MyVendor\getDefaultStage());

Third party recipe should avoid a direct function call, because it will be called always even if we overwrite it with our own set('default_stage', \MyVendor\getDefaultStage()). Look at the next example how the third party recipe should use callable in that case.

Example 2: Callable assign in set()

Lets assume that we must include some third party recipe that is setting 'default_stage' like this:

set('default_stage', function() {
    return \ThirdPartyVendor\getDefaultStage();
});

And we want to overwrite this in our deploy.php:

set('default_stage', function() {
    return \MyVendor\getDefaultStage();
});

The result is that only \MyVendor\getDefaultStage() is run.

keep_releases

Number of releases to keep. -1 for unlimited releases. Default to 5.

repository

Git repository of the application.

To use a private repository, you need to generate a SSH-key on your host and add it to the repository as a Deploy Key (a.k.a. Access Key). This key allows your host to pull out the code. Or use can use agent forwarding.

Note that the first time a host connects, it can ask to add host in known_hosts file. The easiest way to do this is by running git clone <repo> on your host and saying yes when prompted.

git_tty

Allocate TTY for git clone command. false by default. This allow you to enter a passphrase for keys or add host to known_hosts.

set('git_tty', true);

git_recursive

Set the --recursive flag for git clone. true by default. Setting this to false will prevent submodules from being cloned as well.

set('git_recursive', false);

branch

Branch to deploy.

If you want to deploy a specific tag or a revision, you can use --tag and --revision options while running dep deploy. E.g.

dep deploy --tag="v0.1"
dep deploy --revision="5daefb59edbaa75"

Note that tag has higher priority than branch and lower than revision.

shared_dirs

List of shared dirs.

set('shared_dirs', [
    'logs',
    'var',
    ...
]);

shared_files

List of shared files.

copy_dirs

List of files to copy between release.

writable_dirs

List of dirs which must be writable for web server.

writable_mode

Writable mode

• acl (default) use setfacl for changing ACL of dirs.
• chmod use unix chmod command,
• chown use unix chown command,
• chgrp use unix chgrp command,

writable_use_sudo

Whether to use sudo with writable command. Default to false.

writable_chmod_mode

Mode for setting writable_mode in chmod. Default: 0755.

writable_chmod_recursive

Whether to set chmod on dirs recursively or not. Default: true.

http_user

User the web server runs as. If this parameter is not configured, deployer try to detect it from the process list.

clear_paths

List of paths which need to be deleted in release after updating code.

clear_use_sudo

Use or not sudo with clear_paths. Default to false.

cleanup_use_sudo

Whether to use sudo with cleanup task. Default to false.

use_relative_symlink

Whether to use relative symlinks. By default deployer will detect if the system supports relative symlinks and use them.

Relative symlink used by default, if your system supports it.

use_atomic_symlink

Whether to use atomic symlinks. By default deployer will detect if system supports atomic symlinks and use them.

Atomic symlinking is used by default, if your system supports it.

composer_action

Composer action. Default is install.

composer_options

Options for Composer.

env

Array of environment variables.

set('env', [
    'VARIABLE' => 'value',
]);

Read more about task definitions.