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 配置

将生产更改提交到git的cron作业

如果客户直接在生产服务器上编辑已部署的网站，您可能希望将这些更改提交回您的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环境中的所有内容。