README

由Digital Pulp支持开发的本地开发工具集。

主要贡献者

适用于Docker的Drupal和WordPress项目的Composer模板

此项目模板使用DDEV作为基础，自动化基于Docker的本地开发。

网站依赖项使用Composer管理，初始Composer插件与Composer 2兼容。
DDEV的自动设置。

入门指南

首先您需要安装composer。 注意：以下说明适用于全局composer安装。您可能需要将composer替换为php composer.phar（或类似）以适应您的设置。
Ballast将检查您的系统是否需要软件。如果缺少任何东西，将提供缺少包的列表。
我们建议您将所有Ballast项目放置在单个父目录中，例如~/BallastSites/。
操作系统特定说明

macOS：您的Docker站点需要一个家。DDEV使用Docker for Mac管理文件导出到Docker。这在macOS上已知存在性能问题。一旦确认项目可以正确加载，我们建议您过渡到使用NFS来挂载文件系统。我们已经提取并自动化了DDEV文档中描述的设置：ahoy setup-nfs
Windows Linux子系统：在Linux中构建和管理您的Ballast站点。DDev 推荐此方法供Windows用户使用。
原生Linux：遵循DDev的安装方法之一。

升级到3.x

您将在Docker Desktop中看到一个运行中的http-proxy容器。此容器将与ddev发生冲突。如果您只是测试3.x，则只需停止此容器。如果您完全切换到3.x，则可以删除此容器。如果您在删除后必须运行2.x，则2.x版本的ahoy harbor将恢复它。

管理主题任务

ahoy命令用于在前端容器中运行主题任务，因此您可以选择不在主机上安装node。当您首次设置具有既定主题的站点时，您可能需要运行ahoy npm install --no-save来安装基于node的主题工具。可以通过ahoy --help找到更多用于前端任务的前端ahoy命令。

初始设置

在初始设置后，您应删除此README中的“初始设置”部分。

在“入门指南”下选择的或创建的文件夹中，运行composer create-project digitalpulp/ballast your_project。

编辑`composer.json`

这里还有一个特定于项目的值需要设置，即自定义主题文件中bower组件的路径。编辑extra部分以添加到主题bower_components目录的路径。下面的代码片段中显示了示例条目，位于最后一行。

{
"extra": {
        "installer-types": ["bower-asset"],
        "installer-paths": {
            "docroot/core": ["type:drupal-core"],
            "docroot/libraries/{$name}": ["type:drupal-library"],
            "docroot/modules/contrib/{$name}": ["type:drupal-module"],
            "docroot/profiles/contrib/{$name}": ["type:drupal-profile"],
            "docroot/themes/contrib/{$name}": ["type:drupal-theme"],
            "drush/contrib/{$name}": ["type:drupal-drush"],
            "docroot/themes/custom/theme_name/bower_components/{$name}": ["type:bower-asset"]
        }
    }
}

如果适合您的项目，可以将其更改为npm-asset。

此外，在extra属性中的drupal-scaffold键下还有一个额外的属性。

{
"file-mapping": {
        "[web-root]/.htaccess": false,
        "[web-root]/.eslintrc.json": false,
        "[web-root]/.ht.router.php": false,
        "[web-root]/INSTALL.txt": false,
        "[web-root]/README.txt": false,
        "[web-root]/autoload.php": false,
        "[web-root]/example.gitignore": false,
        "[web-root]/index.php": false,
        "[web-root]/robots.txt": false,
        "[web-root]/update.php": false,
        "[web-root]/web.config": false,
        "[web-root]/sites/default/settings.php": false
      }
}

这些将阻止在更新核心或将其添加到项目时更改该文件。

WordPress

用wordpress-composer.json替换原始的composer.json文件，并运行composer update。

初始Composer安装

您可能希望要求一组初始的共享模块或WordPress插件。（见下面的更新和维护）。如果您最初没有添加模块，可以运行composer update nothing来生成初始的composer.lock文件。无论哪种方式，提交结果都将加快团队其他成员的设置。

运行`composer robo setup:cloned`

将运行一次访谈和自动化设置，为您配置大部分项目。注意：测试表明Composer 1.x不支持交互式脚本。如果您仍在使用Composer 1，请使用php scripts/robo/BallastRunner.php setup:clone代替。如果接受运行setup:project的提议，此过程将设置Ahoy命令，这将启用ahoy robo以运行其他高级命令。

在您的自定义主题中设置节点版本。

前端容器期望在主题目录中有一个.node-version文件。参见nodenv文档。

为Codeship Pro做准备

我们使用Codeship Pro来部署基于此模板构建的项目。提供免费层。所有对develop分支的提交都将构建和部署。

Docker环境变量

需要在项目仓库根目录中的codeship-services.yml中设置两个环境变量和一个路径。

前端：环境：THEME_NAME - 您自定义主题的文件夹/机器名。此文件夹应存在于docroot/themes/custom中。如果您在setup/config.yml中设置了site_theme_path，则还必须在此处设置THEME_PATH为相同的值。
前端：工作目录 - 将此值设置为容器中主题文件夹的完整路径。通常为/var/www/docroot/themes/custom/yourtheme
部署：环境：DEPLOY_TARGET - Codeship将推送到git远程的构建工件URL。

加密环境变量

部署凭证不应以明文形式存储在仓库中，但Codeship将在每次构建时解密这些环境变量。您需要安装Codeship CLI工具Jet来完成这些步骤。

创建一个新的Codeship Pro项目。
打开项目设置并浏览到常规选项卡。
向下滚动并下载AES密钥。
将此密钥移动到项目根目录并重命名为codeship.aes
创建一个名为env的新文件（此文件和codeship.aes都设置为git忽略）。
将匹配安装在您的目标git远程的公钥的私钥复制或创建到项目根目录或项目的/keys目录中。
使用ahoy命令启动本地项目。
使用高级命令ahoy key-prep path/to/private_key将您的私钥以单行格式提取并附加到env文件中。
如果您之前未访问过此git远程，请执行ssh user@git_remote_url以将远程添加到您的~/.ssh/known_hosts。

在env文件中定义环境变量，复制自~/.ssh/known_hosts的相应行，以及提交构建时使用的名称和电子邮件，如下所示

SSH_PRIVATE_KEY=one-line-key copied from the terminal
GIT_KNOWN_HOST=entire line matching the git remote copied from `~/.ssh/known_hosts`
GIT_NAME=Codeship-Deploy
GIT_EMAIL=name@example.com

使用Jet加密文件：jet encrypt env env.encrypted
删除或移动第6步中创建的密钥 - 不要提交私钥！
将env.encrypted提交到仓库。

在CI服务中使用带密码保护的密钥

一些项目，如电子商务项目，应使用带密码保护的ssh密钥。对于人类使用的密钥来说这不是一个问题，但对于连续集成服务使用的密钥则需要自动化。这里使用的方法假设CI环境使用我们的容器，因此为每个构建创建。此示例假设CI服务为Codeship，如果您使用不同的服务，则可以对其进行调整。

附加环境变量

将密码添加到上面描述的env文件中，作为SSHPASS=key，并重新加密文件。
将环境变量添加到codeship-services.yml文件中deploy服务的environment部分

GIT_SSH_COMMAND: SSH_AUTH_SOCK=/root/.ssh/ssh_auth_sock ssh

手动连接一次

如果相关的密钥从未被用来认证远程git服务，则ssh-agent将如本StackExchange评论中所述提示输入密码。使用ssh -i从本地命令行通过CI密钥连接到git服务。在提示下提供密码，git服务将为CI用户的使用做好准备。

为技术负责人提供的`ahoy`高级命令

在ahoy.yml文件中有一些标记为“高级”的额外命令，这些命令不会在ahoy --help的响应中出现。这些命令是为可能需要以某些目的进入docker容器的技术负责人准备的。

安装项目

composer install

所有docker依赖项、Drupal核心依赖项以及Drupal核心都将被安装。

您应该提交所有未被.gitignore文件排除的文件。

模板做什么？

在安装给定的composer.json时，会处理一些任务

Drupal将在docroot目录中安装。
实现了自动加载器，使用在vendor/autoload.php中生成的composer自动加载器，而不是Drupal提供的自动加载器（docroot/vendor/autoload.php）。
模块（类型为drupal-module的包）将放置在docroot/modules/contrib/。
主题（类型为drupal-theme的包）将放置在docroot/themes/contrib/。
配置文件（类型为drupal-profile的包）将放置在docroot/profiles/contrib/。
创建默认可写版本的settings.php和services.yml。
创建docroot/sites/default/files目录。
在本地安装最新版本的drush，以便在vendor/bin/drush中使用。
在本地安装最新版本的DrupalConsole，以便在vendor/bin/drupal中使用。
检查本地机器以运行docker开发设置所需的依赖项。任何缺失的依赖项都通过homebrew安装。以下是在Mac上所需的依赖项
- DDEV Local
- Docker Desktop
- Docker Compose
- pre-commit by Yelp
强烈推荐但不是必需的
- Ahoy

更新和维护

更新Drupal核心

本项目旨在确保您的Drupal核心文件始终保持最新；使用drupal/core-composer-scaffold项目来确保每次更新drupal/core时，您的框架文件都会更新。如果您自定义了任何“框架”文件（通常是.htaccess），则在Drupal核心的新版本发布时，您可能需要合并冲突，如果您的修改文件之一已更新。请参阅上面的drupal-scaffold部分以阻止这些文件更新。

按照以下步骤更新您的核心文件。

运行composer update drupal/core-recommended drupal/core-composer-scaffold drupal/core-dev --with-all-dependencies以更新Drupal核心及其依赖项。
运行git diff以确定是否有任何框架文件已更改。检查文件中的更改，并将任何对.htaccess或robots.txt的定制恢复。
将所有内容合并为一个单独的提交，这样在检出分支或运行git bisect时，docroot将与core保持同步。
如果在步骤2中存在非平凡的冲突，您可能希望在分支上执行这些步骤，并使用git merge将更新的核心文件与您的自定义文件合并。这有助于使用kdiff3等三路合并工具。如果您的更改很简单，则不需要此设置；将所有更改放在文件的开头或结尾是一个使合并变得容易的好策略。

更新WordPress

编辑composer.json中嵌入的包定义中的版本号和url。请参阅

更新和维护`composer.json`

在DrupalCon巴尔的摩的“使用Composer管理Drupal项目”BOF中，一个常见的问题是composer.json和composer.lock中的合并冲突。与会者一致认为，对于开发团队，应该有一个指定的维护者负责这些文件。新的模块、更新等应从维护者那里请求，维护者通常是项目负责人。

使用composer require ...，您可以为您的安装下载新的依赖项，包括Drupal贡献的模块。要安装多个模块的最新版本

composer require drupal/block_visibility_groups drupal/config_split drupal/easy_breadcrumb drupal/focal_point drupal/media_entity_image drupal/media_entity_browser drupal/field_formatter drupal/paragraphs drupal/inline_entity_form drupal/pathauto drupal/page_manager drupal/viewsreference

您还可以要求bowser组件

composer require bower-asset/formstone

最小稳定性设置为稳定。如果您需要更低的稳定性，则需要标记特定的包。

本地开发命令

docker的最佳实践是在主机上工作，并在需要时向容器发送命令。本项目使用Ahoy作为抽象工具，以进一步简化开发人员的此流程。Ahoy命令可在项目的根目录或以下任何位置运行。

ahoy -h将列出所有Ahoy命令。

常见问题解答

我应该提交我下载的贡献模块吗？

Composer建议不。他们提供了反对的论点，但也提供了如果项目决定这样做的话的解决方案。

我应该提交框架文件吗？

drupal-scaffold插件可以将框架文件（如index.php、update.php等）下载到您的项目的docroot/目录中。我们通常会将这些文件提交。如果您没有自定义这些文件，您可以选择不将它们检入到您的版本控制系统（例如git）。如果您的项目是这样的，那么在每次安装或更新您的项目后自动运行drupal-scaffold插件可能很方便。您可以通过在composer.json中将@drupal-scaffold注册为安装和更新命令来实现这一点。

{
"scripts": {
    "drupal-scaffold": "DrupalComposer\\DrupalScaffold\\Plugin::scaffold",
    "post-install-cmd": [
        "@drupal-scaffold",
        "..."
    ],
    "post-update-cmd": [
        "@drupal-scaffold",
        "..."
    ]
  }
}

我如何将补丁应用到下载的模块中？

如果您需要应用补丁（根据正在修改的项目，通常拉取请求是更好的解决方案），您可以使用 composer-patches 插件来完成。

要将补丁添加到foobar Drupal模块，请将patches部分插入composer.json的extra部分。

{
"extra": {
    "patches": {
        "drupal/foobar": {
            "Patch description": "URL to patch"
        }
    }
  }
}

感谢

我们感谢以下开源项目，使本项目成为可能！

digitalpulp / ballast

维护者

详细信息

README

适用于Docker的Drupal和WordPress项目的Composer模板

入门指南

升级到3.x

管理主题任务

初始设置

编辑`composer.json`

WordPress

初始Composer安装

运行`composer robo setup:cloned`

在您的自定义主题中设置节点版本。

为Codeship Pro做准备

Docker环境变量

加密环境变量

在CI服务中使用带密码保护的密钥

附加环境变量

手动连接一次

为技术负责人提供的`ahoy`高级命令

安装项目

模板做什么？

更新和维护

更新Drupal核心

更新WordPress

更新和维护`composer.json`

本地开发命令

常见问题解答

我应该提交我下载的贡献模块吗？

我应该提交框架文件吗？

我如何将补丁应用到下载的模块中？

感谢

digitalpulp / ballast

维护者

详细信息

README

适用于Docker的Drupal和WordPress项目的Composer模板

入门指南

升级到3.x

管理主题任务

初始设置

编辑composer.json

WordPress

初始Composer安装

运行composer robo setup:cloned

在您的自定义主题中设置节点版本。

为Codeship Pro做准备

Docker环境变量

加密环境变量

在CI服务中使用带密码保护的密钥

附加环境变量

手动连接一次

为技术负责人提供的ahoy高级命令

安装项目

模板做什么？

更新和维护

更新Drupal核心

更新WordPress

更新和维护composer.json

本地开发命令

常见问题解答

我应该提交我下载的贡献模块吗？

我应该提交框架文件吗？

我如何将补丁应用到下载的模块中？

感谢

编辑`composer.json`

运行`composer robo setup:cloned`

为技术负责人提供的`ahoy`高级命令

更新和维护`composer.json`