README

在海姆里希 & 汉诺特 GmbH使用的 Deployer 脚本。

安装

要使用我们的脚本，需要使用 composer 安装此包。

composer require --dev heimrichhannot/deployer-recipes

不需要单独安装 Deployer，但可以使用以下命令进行安装。

composer require --dev deployer/deployer

Contao 4.13+ 的使用方法

在您的 Contao 项目根目录下创建一个 deploy.php 文件，并根据您的需求自定义以下内容。

<?php # deploy.php

namespace Deployer;

date_default_timezone_set('Europe/Berlin');

import(__DIR__ . '/vendor/heimrichhannot/deployer-recipes/autoload.php');
recipe('contao');

set('rsync_src', __DIR__);

host('www.example.org')
    ->setPort(22)
    ->setRemoteUser('www_data')
    ->set('public_url', 'https://www.example.org')
    ->set('http_user', 'www_data')
    ->set('public_dir', 'public')
    ->set('deploy_path', '/usr/www/users/{{remote_user}}/docroot')
    ->set('bin/php', 'php82')
    ->set('bin/composer', 'composer')
    ->set('release_name', fn() => date('y-m-d_H-i-s'))
    /** In case ACL is unavailable, use chmod instead */
    // ->set('writable_mode', 'chmod')
;

/** @example Add project-specific files */
add('project_files', [
    'config/routes.yaml',
    'translations',
]);

/** @example Remove values from any variable */
remove('project_files', [
   'files/themes',
   'templates'
]);

/** @example Add project-specific files to exclude from deploy */
add('exclude', [
    '.githooks',
]);

/** @example Add a shared .htpasswd or any other file */
add('shared_files', [
    '{{public_path}}/.htpasswd'
]);

/** @example Ask confirmation before running migrations */
set('ask_confirm_migrate', true);

/** @example Do not create backup on migration */
set('create_db_backup', false);

/** @example Reload PHP-FPM after deployment */
set('reload_php_fcgi', true);

/** @example Don't automatically deploy contao-manager */
set('contao_manager_deploy', false);

/** @example Disable confirmation input when going live */
set('confirm_prod', false);

/** @example Add yarn build task before deploying */
before('deploy', 'ddev:yp');

/** @example Deploy `files/themes`, which are shared and not updated by default */
after('deploy:shared', 'deploy:themes');

/** @example Create symlinks on deployment */
add('symlinks', [
    '{{public_dir}}/example' => '../relative/path/to/target',
]);

多个主机或环境的设置

您可以通过多次使用 host() 函数来设置多个主机或环境。如果您在运行 deployer 命令时没有指定 选择器（如标签），则会提示您选择运行该命令的主机。

如果您想为所有主机设置通用变量，请使用提供的方法链工厂方法（注意：），在所有先前定义的主机上调用任意数量的方法。

重要

在定义多个主机时，务必使用 标签 来区分环境。

host('stage')
    ->set('public_url', 'https://stage.example.org')
    ->setLabels(['env' => 'stage'])
;

host('production')
    ->set('public_url', 'https://www.example.org')
    ->setLabels(['env' => 'prod'])
;

// use the method chain factory
onAllHosts()
    ->setHostname('www.example.org')
    ->setPort(22)
    ->setRemoteUser('www_data')
    ->set('http_user', 'www_data')
    ->set('public_dir', 'public')
    ->set('deploy_path', '/usr/www/users/{{remote_user}}/docroot/{{alias}}')
    ->set('bin/php', 'php82')
    ->set('bin/composer', 'composer')
    ->set('release_name', fn() => date('y-m-d_H-i-s'))
;

或者，您也可以遍历所有主机

foreach (getHosts() as $host) {
    $host
        ->setHostname('www.example.org')
        ->setPort(22)
        ->setRemoteUser('www_data')
        ->set('http_user', 'www_data')
        ->set('public_dir', 'public')
        ->set('deploy_path', '/usr/www/users/{{remote_user}}/docroot/{{alias}}')
        ->set('bin/php', 'php82')
        ->set('bin/composer', 'composer')
        ->set('release_name', fn() => date('y-m-d_H-i-s'))
    ;
}

getHosts() 是 Deployer::get()->hosts 的简写。

注意

随着技术的发展，此文档可能在未来发生变化。请保持关注。

别名占位符

根据您的设置，您可能希望将不同的环境自动放置在同一个主机上，并在相应的目录中。您可以使用 {{alias}} 占位符来区分主机别名作为环境名称。

例如

host('stage') // <- this is the alias
    ->setRemoteUser('www_data')
    ->set('deploy_path', '/usr/www/users/{{remote_user}}/docroot/{{alias}}')
; // will be evaluated to /usr/www/users/www_data/docroot/stage

实用命令

在远程服务器上清除缓存

dep cache:clear

清除 opcache

dep opcache:clear

仅部署资产（encore 构建文件夹）

dep deploy:assets

数据库操作

您也可以使用其别名 dep db:clone 来替换 dep db:pull。

当 mysql 或 mysqldump 不可用时的处理方法

您可以将 pull 和 push 命令更改为使用 contao:backup 命令而不是 mysql 和 mysqldump

set('db_dump_mode', 'contao');

注意

此操作仅当您的本地和远程数据库兼容时才有效。

Contao-Manager 自动部署

Contao-Manager 默认设置为自动部署。如果您希望禁用此自动部署，您可以在部署脚本中配置以下变量

set('contao_manager_deploy', false);

Contao-Manager 将下载 Contao-Manager phar 文件的最新版本，并将其部署到 {{deploy_path}}/shared/{{public_dir}}/contao-manager.phar.php。之后，它将被符号链接到 {{release_or_current_path}}/{{public_dir}}/contao-manager.phar.php。

如果它已经存在，它将执行自更新。

条件部署

如果您的 shared_files 中存在名为 contao-manager.phar.php 的文件，则 Contao-Manager 的自动部署将不会进行。

自动部署被跳过的示例

add('shared_files', [
    '{{public_path}}/contao-manager.phar.php',
]);

这样，如果您不希望远程主机从互联网自动获取 Contao-Manager，您可以相应地设置共享文件，而无需修改 contao_manager_deploy。

从不同位置获取 Contao-Manager

如果您想更改 contao-manager.phar 的源 URL，例如，如果您托管自己的 Contao-Manager 镜像，您可以设置以下变量

// this is the default value
set('contao_manager_source', 'https://download.contao.org/contao-manager/stable/contao-manager.phar');

添加符号链接

您可以通过使用 symlinks 配置变量来向您的部署添加符号链接。

add('symlinks', [
    'path/to/link' => '../relative/path/to/target',
    '{{public_dir}}/example' => '../relative/path/to/another/target',
]);

链接路径相对于 {{release_or_current_path}} 目录。

在部署后重新生成符号链接，可以使用以下命令

dep deploy:symlinks

工作正在进行中

这些模板仍在开发中，尚未完全实现。请谨慎使用或完全不要使用。

/** WIP: Deploy an htaccess file which will be renamed to .htaccess */
set('htaccess_filename', '.htaccess.prod');
after('deploy:shared', 'deploy:htaccess');