README

oc-bootstrapper 是一个命令行工具，允许您从一个配置文件中重建 October CMS 安装。

它可以用来快速启动项目的本地开发环境，或者在建站时构建和更新生产安装。

特性

• 安装和更新私有和公共插件（通过 Git 或市场）
• 通过智能管理您的 .gitignore 文件，确保您的 git 仓库中只有必要的文件
• 内置对 GitLab CI 部署的支持
• 内置对共享配置文件模板的支持
• 使用 .env 文件为生产环境和开发环境设置合理的默认配置

依赖项

• Zip PHP 扩展（sudo apt-get install php-zip）
• Composer（通过全局二进制文件或在您的工作目录中的 composer.phar）

测试于

• Ubuntu 15.10
• Ubuntu 16.04
• Ubuntu 18.04
• OSX 10.11 (El Capitan)

通过 Ubuntu Bash 或 Git Bash 在 Windows 上运行。

示例项目

在使用 oc-bootstrapper 的过程中，建议将 october.yaml、项目的主题和项目插件（那些在项目之间共享的插件）保留在项目的仓库中。

请查看 OFFLINE-GmbH/octobertricks.com 仓库以了解 oc-bootstrapper 的示例设置。

安装

composer global require offline/oc-bootstrapper

您现在可以从命令行运行 october。

$ october -v
October CMS Bootstrapper version 0.5.0

Docker 镜像

一个官方的 Docker 镜像，包含 oc-bootstrapper、composer 和 Envoy，可在 hub.docker.com 上找到，名称为 offlinegmbh/oc-bootstrapper。

docker run offlinegmbh/oc-bootstrapper october -v
docker run offlinegmbh/oc-bootstrapper envoy -v
docker run offlinegmbh/oc-bootstrapper composer -v

它旨在与 CI 管道一起使用，但也可以使开始 October 项目变得更加容易，因为它不需要在本地安装 PHP 和 Composer。

您可以使用以下 docker 命令在当前工作目录的上下文中执行任何命令

# alias this to "october" for easier access
docker run -it --rm -v "$(pwd)":/app offlinegmbh/oc-bootstrapper october

请注意，这对于像 october init 这样的命令非常适用，因为它不依赖于任何外部服务。要运行 october install，则需要一些额外的设置，以便容器可以连接到您的数据库。

用法

初始化项目

使用 october init 命令创建一个新的空项目并带有配置文件

october init myproject.com
cd myproject.com

更改配置

在您新建的项目目录中，您将找到一个 october.yaml 文件。编辑其内容以满足您的需求。

app:
    name: my-new-project       # Give the project a unique name
    url: http://october.dev
    locale: en
    debug: true

cms:
    theme: name (user@remote.git)
    edgeUpdates: false
    disableCoreUpdates: false
    enableSafeMode: false
    # project: XXXX            # Marketplace project ID

database:
    connection: mysql
    username: root
    password: 
    database: bootstrapper
    host: localhost

git:
    deployment: gitlab
    keepRepo: false       # Keep .git in plugins

# deployment:            # Automatically configure the Envoy file for GitLab deployments      
#     user: hostinguser  
#     server: servername                    

plugins:
    - Rainlab.Pages
    - Rainlab.Builder
    - Indikator.Backend
    - OFFLINE.SiteSearch
    - OFFLINE.ResponsiveImages
    - OFFLINE.GDPR (https://github.com/OFFLINE-GmbH/oc-gdpr-plugin.git)
    - ^OFFLINE.Mall (https://github.com/OFFLINE-GmbH/oc-mall-plugin.git#develop)
    # - Vendor.Private (user@remote.git)
    # - Vendor.PrivateCustomBranch (user@remote.git#branch)

mail:
    host: smtp.mailgun.org
    name: User Name
    address: email@example.com
    driver: log

主题和插件语法

oc-bootstrapper 允许您从您的自己的 Git 仓库安装插件和主题。只需在 () 中附加您的仓库地址，告诉 oc-bootstrapper 检出它即可。如果没有定义仓库，则插件将从 October 市场加载。

示例

# Install a plugin from the official October Marketplace
- OFFLINE.Mall 

# Install a plugin from a git repository. The plugin will be cloned
# into your local repository and become part of it. You can change the
# plugin and modify it to your needs. It won't be checked out again (no updates).
- OFFLINE.Mall (https://github.com/OFFLINE-GmbH/oc-mall-plugin.git)

# The ^ marks this plugin as updateable. It will be removed and checked out again
# during each call to `october install`. Local changes will be overwritten.
# This plugin will stay up to date with the changes of your original plugin repo.
- ^OFFLINE.Mall (https://github.com/OFFLINE-GmbH/oc-mall-plugin.git)

# Install a specific branch of a plugin. Keep it up-to-date.
- ^OFFLINE.Mall (https://github.com/OFFLINE-GmbH/oc-mall-plugin.git#develop)

安装 October CMS

完成编辑配置文件后，只需运行 october install 即可安装 October。 oc-bootstrapper 将为您设置一切。您可以在检出项目仓库后或在建站时运行此命令。

此命令是 幂等的，它只会安装后续调用中缺少的组件。

october install 

使用--help标志查看所有可用选项。

october install --help 

安装额外的插件

如果您需要安装任何额外的插件，只需将它们添加到您的october.yaml中，然后重新运行october install。缺少的插件将被安装。

使用自定义的php二进制文件

通过--php标志，您可以指定用于安装命令的自定义php二进制文件。

october install --php=/usr/local/bin/php72

更新October CMS

如果您想更新安装，可以运行

october update

将更改推送到远程git仓库

要将本地更改推送到当前git远程仓库，运行

october push

此命令可以作为cron作业运行，以保持您的git仓库与生产环境中的更改同步。

SSH部署

如果不想设置部署，将deployment选项设置为false。

设置

您可以使用oc-bootstrapper与任何类型的部署软件一起使用。您需要设置以下步骤

1. 通过SSH连接到目标服务器
2. 安装composer和oc-bootstrapper
3. 运行october install

您可以为每次向您的仓库推送运行此“脚本”。october install命令将只安装目标服务器中缺少的内容。

GitLab CI的示例设置

要初始化一个具有GitLab CI支持的工程，请在您的配置文件中将deployment选项设置为gitlab。

这将设置一个.gitlab-ci.yml和一个Envoy.blade.php。

1. 创建一个SSH密钥对以登录到您的部署目标服务器
2. 在您的GitLab CI设置中创建一个SSH_PRIVATE_KEY变量，其中包含创建的私钥
3. 编辑Envoy.blade.php脚本来满足您的需求
4. 将更改推送到您的仓库。GitLab将运行示例.gitlab-ci.yml配置

Cron作业以将prod更改提交到git

如果客户直接在生产服务器上编辑了已部署的网站，您可能希望将这些更改提交回您的git仓库。

为此，只需创建一个cron作业，每X分钟执行一次october push。此命令将自动将所有更改提交到您的git仓库，消息为[ci skip] 从$hostname添加更改。

文件模板

您可以通过在您的全局composer目录中创建一个名为october的文件夹来覆盖所有默认文件模板。通常它位于~/.config/composer下。

将您想要用作默认文件的文件放在~/.config/composer/october中。可以覆盖templates目录中的所有文件。

在Windows上，您可以在%USERPROFILE%/AppData/Roaming/Composer/october/中存储您的文件

变量替换

您可以在配置文件中使用占位符，这些占位符将被来自您的october.yaml配置的值替换

// Example Envoy.blade.php
$url = '%app.url%'; // Will be replaced by the app.url value from your october.yaml file

有一个特殊的占位符%app.hostname%可用，它将被替换为app.url的主机部分

%app.url%      = http://october.dev
%app.hostname% = october.dev

从git仓库的文件模板

如果您的模板文件夹是一个git仓库，oc-bootstrapper将在每次您运行october init时从仓库拉取最新的更改。

如果您想通过中央git仓库与您的团队共享模板文件，这是一个很棒的功能。只需确保您能够通过git pull获取最新的更改即可！

cd ~/.config/composer/october
git clone your-central-templates-repo.git .
git branch --set-upstream-to=origin/master master
git pull # Make sure this works without any user interaction

开发环境

oc-bootstrapper可以为您设置开发环境。目前，只有Lando支持开箱即用。

要启用Lando集成，运行october init并选择lando作为开发环境。一个.lando.yml文件将被放置在您的项目中。

现在您可以简单地运行 lando start 命令，在由 Lando 创建的 Docker 环境中启动所有服务。