Deployer Documentation

To use Slack notifications in your deployment process, require the Slack recipe file in your deployment script:

require 'contrib/slack.php';

You will also need a Slack incoming webhook URL to provide to the configuration.

To use Yammer notifications in your deployment process, require the Yammer recipe file in your deployment configuration (usually deploy.php).

require 'contrib/yammer.php';

When setting up your host for Shopware deployment, you must define the repository and host-specific configurations. Key settings include deploy_path, http_user, http_group, and become (to ensure tasks run with correct permissions for cache files).

set('repository', 'git@github.com:shopware/production.git');

host('SSH-HOSTNAME')
    ->set('remote_user', 'SSH-USER')
    ->set('deploy_path', '/var/www/shopware')
    ->set('http_user', 'www-data')
    ->set('http_group', 'www-data')
    ->set('writable_mode', 'chmod')
    ->set('writable_recursive', true)
    ->set('become', 'www-data');

For project-based installs, it is recommended to alias dep to the vendor binary to simplify command execution.

alias dep='vendor/bin/dep'

The Crontab recipe allows you to manage a specific section of the server's crontab file. It creates a section identified by a unique identifier (defaulting to the application name) so that Deployer can manage only the jobs related to your application without interfering with other system cron jobs.

To use it, require the recipe in your deployment script, configure your jobs, and hook the crontab:sync task to run after a successful deployment.

require 'contrib/crontab.php';

// Sync jobs after a successful deployment
after('deploy:success', 'crontab:sync');

// Define your cron jobs
add('crontab:jobs', [
    '* * * * * cd {{current_path}} && {{bin/php}} artisan schedule:run >> /dev/null 2>&1',
]);

To monitor the lifecycle of a deployment, hook the CIMonitor tasks into your deployment process using before and after hooks.

• To notify when a deployment starts: before('deploy', 'cimonitor:notify');
• To notify on success: after('deploy:success', 'cimonitor:notify:success');
• To notify on failure: after('deploy:failed', 'cimonitor:notify:failure');

You can trigger Mattermost notifications at different stages of your deployment by attaching specific tasks to deployment hooks.

• Notify at start of deployment: Use mattermost:notify on the before('deploy', ...) hook.
• Notify on success: Use mattermost:notify:success on the after('deploy:success', ...) hook.
• Notify on failure: Use mattermost:notify:failure on the after('deploy:failed', ...) hook.

To use the pre-configured Laravel deployment workflow, include the Laravel recipe in your deployment script using require 'recipe/laravel.php';.

The deploy task for Laravel includes several automated steps:

• Preparation: deploy:prepare (includes deploy:info, deploy:setup, deploy:lock, deploy:release, deploy:update_code, deploy:env, deploy:shared, and deploy:writable).
• Dependencies: deploy:vendors installs composer dependencies.
• Laravel Specifics: artisan:storage:link (creates symbolic links), artisan:optimize (caches bootstrap files), and artisan:migrate (runs database migrations).
• Publishing: deploy:publish (includes deploy:symlink, deploy:unlock, and deploy:cleanup).
• Post-deployment: artisan:reload (reloads running services).

Branch Option Priority

In v6, if a host has a branch(...) parameter, the --branch CLI option will no longer override it. To restore old behavior, use a callback:

host('prod')->set('branch', function () {
    return input()->getOption('branch') ?: 'production';
});

API Changes

• run and runLocally now return a string instead of a Deployer\Type\Result object.
  • Replace run('...')->toString() with run('...').
  • Replace run('...')->toBool() with test('...').
• env_vars is renamed to env.
  • set('env_vars', 'FOO=bar') $\rightarrow$ set('env', ['FOO' => 'bar']).
  • If using the Symfony recipe, use set('symfony_env', 'prod') instead of set('env', 'prod').

To enable the writable directory management features in your deployment, include the writable recipe in your deploy.php file.

This recipe provides configuration options to manage directory permissions (via chown, chgrp, chmod, acl, etc.) and a deploy:writable task to apply these permissions.

require 'recipe/deploy/writable.php';