18f-pages-server 中文文档教程

Question

18f-pages-server

此服务器为 18F 页面 发布静态网站。 它的工作方式与 GitHub 页面 非常相似。 它 自动发布基于 Jekyll 的网站 每当对发布分支进行更新时（如 gh-pages，但在哪里 分支的名称由服务器的配置定义）。 它也是 如果发布，则支持通过 rsync 发布 分支不包含基于 Jekyll 的站点。

Reusability

服务器可能由其他组织运行，因为它是完全可配置的 通过 pages-config.json 文件。 你可以想象更换 您自己的说明中的所有“18F”实例 组织的句柄。

Publishing

一旦服务器已经按照 服务器安装说明，提交到存储库的 发布分支（例如 18f-pages）将在 https://PAGES_HOST/REPO_NAME，其中 PAGES_HOST 是主机名 运行 18f-pages-server 并且 REPO_NAME 是存储库的名称 没有组织前缀。

例如，18F/guides-template 将发布到 https://pages.18f.gov/guides-template/。

最近构建尝试的状态将显示在 <代码>https://PAGES_HOST/REPO_NAME/build.log。

Prefixing Jekyll links with {{ site.baseurl }}

Jekyll 站点中以以下开头的指向另一个页面或资源的每个链接 / 或使用 {{ post.url }} 等指令定义的必须 以 {{ site.baseurl }} 为前缀。 18f-pages-server 依赖于此 财产以确保您的网站可以在主机上正确发布为 https://PAGES_HOST/REPO_NAME/，如 额外的服务器生成的 Jekyll 配置部分。 这完全类似于 GitHub 项目页面 URL 结构。

例如：

[This link will be broken when published.](/another/page)
[This link will continue to work.]({{ site.baseurl }}/another/page)

将 {{ site.baseurl }} 应用于每个需要它的链接，您的网站将 在本地服务时正确呈现并表现相同 http://localhost:4000/ 通过 jekyll serve and 发布到 <代码>https://PAGES_HOST/REPO_NAME/。

Repository configuration

在以下说明中，18f-pages 是发布的名称 分支。 此名称对于每个 builders 条目都是可配置的 pages-config.json 文件。

• Create the 18f-pages publishing branch. If you already have a gh-pages branch, you can do this on the command line via:

$ git checkout -b 18f-pages gh-pages
$ git push origin 18f-pages

• If your repo is primarily an 18F Pages site (as opposed to a project site with an 18f-pages branch for documentation), you may optionally set the default branch on GitHub to 18f-pages.
• Configure a webhook for the repository if there isn't already a webhook configured for the entire GitHub organization.
• Push a change to the 18f-pages branch to publish your site.

New sites are not published before the first push to the publishing branch

服务器当前未检测到发布分支的创建（例如 18f-pages)，或创建带有发布分支的存储库。 因此，必须先将更改推送到发布分支，然后站点才会 出现在服务主机上。 目前还不清楚我们是否会实施检测 将来的新存储库或发布分支。

Multiple publishing branches

一个版本库可以包含多个发布分支，每个分支 对应于 pages-config.json 中的一个 builders 项目 文件。

几个 18F 存储库同时具有 18f-pages 和 18f-pages-staging 分支，想法是大多数更改将首先应用于 18f-pages-staging 并发布在 https://pages-staging.18f.gov/。 当。。。的时候 站点已准备好公开发布，18f-pages-staging 分支将 合并到 18f-pages，将站点发布在 https://pages.18f.gov/。

Publishing to internal and external sites from the same branch

可以将您的网站配置为同时发布到内部网站 和来自同一分支的外部站点。

• 将 _config_internal.yml 文件添加到您的 Jekyll 站点，其中包含 过滤掉仅限内部的内容所需的配置。 例如，您的 仅供内部使用的内容可以使用以下内容进行包装 Liquid conditional：
  

  {% if site.internal %}REDACTED TO PROTECT THE INNOCENT AND THEIR VICTIMS{% endif %}
  

然后，您的 _config_internal.yml 应该包含属性：

  internal: true
  

但是，您可以自由实施任何过滤和配置方案 这对您的网站有意义。

• Add a internalSiteDir attribute to one of the builders in your configuration. The internal version of your site will be generated in this directory, and the external version will be generated into the generatedSiteDir directory for the builder.
• Configure your web server to serve from internalSiteDir and generatedSiteDir from two different virtual hosts. Configure the internalSiteDir host to provide authenticated access. For an example, see the 18F Pages Nginx configuration for https://pages-internal.18f.gov/.

您还可以添加一个 _config_external.yml 文件以进行额外配置， 但是 _config_internal.yml 文件必须仍然存在。

如果您需要一个网站只供内部使用，请设置一个单独的 builders 配置中的条目 用于仅限内部的分支。

Webhook configuration

您将需要配置一个或多个 GitHub webhooks 发送push 事件到 https://PAGES_HOST/deploy，其中 PAGES_HOST 是主机名 您组织的页面服务器实例，例如 pages.18f.gov。 这 webhook 必须是内容类型application/json。 Webhooks 可以是 为单个存储库配置，或者可以配置单个 webhook 对于整个 GitHub 组织。 请参阅 18F 指南模板 webhook 设置 说明 举个例子。

Stale sites and repositories require manual deletion

目前没有自动删除陈旧存储库的工具 或当存储库或其发布分支被创建时由它们生成的站点 重命名或删除，或者当站点通过自己的更新自己的 baseurl 时 pagesYaml 文件。 目前，此类存储库 并且生成的站点目录必须从主机中手动删除。 我们可能 将来实施自动站点和存储库删除。

Additional server-generated Jekyll configuration

对于 Jekyll 站点，服务器将生成一个临时的 Jekyll 配置文件，其中包含 由 pagesConfig 配置属性 定义的名称。 对于 18F 页面，此文件称为 _config_18f_pages.yml。 它将定义 以下值将覆盖站点的任何现有值 _config.yml 文件：

• baseurl: - set to the name of the repository without the organization prefix, e.g. /guides-template for the 18F/guides-template repo
• asset_root: - set to the assetRoot configuration property

在大多数情况下，已发布的站点不应具有这些属性中的任何一个 在他们的 _config.yml 文件中定义，也不应该发布他们自己的 _config_18f_pages.yml 文件。 但是，如果站点确实包含自己的 _config_18f_pages.yml 文件，服务器将使用该文件中的设置 而不是自己生成。

如果一个网站使用这个文件来定义它自己的 baseurl 属性，那 property不是/或者空字符串，那么生成的输出目录 将匹配定义的 baseurl。 在这种情况下，baseurl 必须以 <代码>/。

如果 baseurl 为 / 或空字符串，或未在文件中定义，则 生成的输出目录将匹配任何其他站点的默认值，即 没有组织前缀的存储库名称。 请参阅以下部分 为生成的主页创建符号链接了解详情 关于这个用例。

Installing the 18f-pages server

如果您的系统上尚不存在以下内容，请安装：

• Node.js version 0.12.7 or higher; check with node -v
• Ruby version 2.2.3 or higher; check with ruby -v
• Git version 1.9.1 or higher; check with git --version

对于 Ruby，我们强烈建议使用版本管理器，例如 rbenv 或 rvm， 虽然这不是必需的。

rsync 应该已经安装在大多数类 UNIX 系统上，但是 rsyncOpts 配置选项可能需要调整， 特别是在 OS X 上。您可能希望手动尝试使用 rsync 来 确定最适合您的选项。

使用正确的 Node.js、Ruby 和 Git 版本，运行以下命令：

$ gem install jekyll bundler
$ npm install -g 18f-pages-server forever

最后，作为将运行服务器的主机上的用户， 生成 SSH 密钥以添加到您的 GitHub 帐号。 新钥匙可以 如果您离开组织，则由另一名团队成员生成。

Generate and configure pages-config.json

运行 18f-pages print-template > path/to/pages-config.json 生成一个 pages-config.json 文件。 编辑此文件以支持您的安装。

该模板是 pages-config.json 的副本 这个存储库，它基于 18F 页面的实际配置，以及 说明了以下每个设置：

• port: the port on which the server will listen for GitHub webhooks
• home: the parent directory for all of the generated site content
• git: path to git on the host machine
• bundler: path to bundle on the host machine
• bundlerCacheDir: path to bundle cache relative to home
• jekyll: path to jekyll on the host machine
• rsync: path to rsync on the host machine
• rsyncOpts: options to pass to rsync that control Jekyll-less builds; OS X installations in particular may need to adjust these
• s3 (optional): if present, will back up each generated site to Amazon S3; attributes are:
• awscli: path to the aws command on the host machine
• bucket: address of the S3 bucket to which to sync generated sites
• payloadLimit: maximum allowable size (in bytes) for incoming webhooks
• githubOrg: GitHub organization to which all published repositories belong
• pagesConfig: name of the server-generated Jekyll config file that sets the baseurl: and asset_root: Jekyll properties
• pagesYaml: name of the file from which properties such as baseurl: will be read
• fileLockWaitTime: max time for an incoming build request to wait for the lock file, in milliseconds
• fileLockPollTime: max interval for an incoming build request to poll for the lock file, in milliseconds
• secretKeyFile (optional): if you defined a Secret for your webhook, you must enter the path to a file containing the secret value; otherwise ignore this
• assetRoot: the value that the generated pagesConfig file will contain for the asset_root: Jekyll configuration variable; see the guides_style_18f gem's source code for how 18F Pages share common style sheets and JavaScript files across 18F Pages sites, so that updates to the theme are shared across all 18F Pages once they are pushed to the 18F Guides Template
• builders: a list of individual webhook listeners/document publishers; each item contains the following fields, each of which must contain a unique value relative to all other builders entries:
• branch: the publishing branch from which to generate sites
• repositoryDir: the directory within home into which all repositories will be cloned
• generatedSiteDir: the directory within home into which all sites will be generated
• internalSiteDir: the directory within home into which internal views of sites will be generated

此外，每个 builders 条目都可以覆盖以下一个或多个 顶级值：

• githubOrg
• pagesConfig
• pagesYaml
• secretKeyFile
• assetRoot

builders 列表允许我们运行一个服务器来发布两个 https://pages.18f.gov/ 和经过身份验证的 https://pages-staging.18f.gov/。

Branch-specific secret keys

顶级 secretKeyFile 中的值将用于验证所有 默认情况下跨所有分支传入的有效负载。 但是，可以 配置分支特定的 secretKeyFile 值，如果有效负载 对应于特定分支的信息由额外的 webhook 生成。

例如，如果你想为多个 GitHub 运行一个页面服务器 组织，而不是跨组织共享密钥，每个 组织将有自己的分支，有自己的 secretKeyFile。

Run the 18f-pages server

之后，运行以下命令启动服务器 Forever，其中 /path/to/ 和 /usr/local/bin/ 替换为适当的绝对路径：

$ forever start -l /path/to/pages.log -a /usr/local/bin/18f-pages /path/to/pages-config.json

您可以通过运行 which 18f-pages18f-pages 的绝对路径代码>。

Create a symlink to the index.html of the generated homepage

如果您希望发布您的主页，请遵循此示例 18f-pages-server 主机也使用 18f-pages-server。

18F Pages 主页本身是从 18F/pages 存储库。 它定义了自己的 _config_18f_pages.yml 文件，以便 baseurl: 覆盖 额外的服务器生成的 Jekyll 配置部分 不会发生：

baseurl:
asset_root: /guides-template

主页字面上是一个单页网站，但它仍然发布到 名为 pages 的目录。 让它出现在的根部的技巧 https://pages.18f.gov/ 是手动 符号链接 pages/index.html 到 它的父目录：

$ ln -s /home/ubuntu/pages-generated/pages/index.html /home/ubuntu/pages-generated/index.html

这个基于符号链接的解决方案导致主页也保持可用 在 https://pages.18f.gov/pages/，但这似乎不值得修复。 如果 避免这是您组织的优先事项，主页可以是 使用自己专用的 builder 生成并通过自己专用的服务 网络服务器规则。 尝试自动生成符号链接或复制 生成的主页文件可能是另一种选择，但似乎风险更大且 可能深奥。

Webserver configuration

最后的必需步骤是设置您的网络服务器以公开18f-pages webhook 端点并提供由 18f-pages 生成的静态内容 服务器。 最后的可选步骤是在组织范围内设置一个 webhook 配置并运行网络服务器后。

以下摘录自完整 18F页面nginx配置 对于 https://pages.18f.gov/ 和 https://pages-staging.18f.gov/。 注意如何 值与 pages-config.json 文件 中的值匹配， 在配置部分中解释。

https://pages.18f.gov/ server 块的第一个摘录定义了 https://pages.18f.gov/deploy webhook 端点。 这个端点代理 向运行在端口 5000 上的 18f-pages 服务器发出请求。请注意，只有一个 webhook 端点是必需的，因为单个服务器实例同时发布 https://pages.18f.gov/ 和 https://pages-staging.18f.gov/。

server {
  listen 443 ssl spdy;
  server_name  pages.18f.gov;
  include ssl/star.18f.gov.conf;

  ...

  location /deploy {
    proxy_pass http://localhost:5000/;
    proxy_http_version 1.1;
    proxy_redirect off;

    proxy_set_header Host   $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto https;
    proxy_max_temp_file_size 0;

    proxy_connect_timeout 10;
    proxy_send_timeout    30;
    proxy_read_timeout    30;
  }

  ...
}

https://pages.18f.gov/ server 块的第二个摘录对应 到 pages-config.json 的第一个 builders 条目：

server {
  listen 443 ssl spdy;
  server_name  pages.18f.gov;
  include ssl/star.18f.gov.conf;

  ...

  location / {
    root   /home/ubuntu/pages-generated;
    index  index.html;
    default_type text/html;
  }

  ...
}

这些最终的server 块定义经过身份验证的 https://pages-staging.18f.gov/ 主机。 127.0.0.1:8080 块对应于 pages-config.json 中的第二个 builders 条目。 请注意，该网站使用 bitly/oauth2_proxy 用于身份验证， 您可以在 18F Hub 的 OAuth2 代理部分了解更多信息 部署自述文件。

server {
  listen 443 ssl spdy;
  server_name  pages-staging.18f.gov;
  include ssl/star.18f.gov.conf;

  include vhosts/auth-locations.conf;
}

server {
  listen 127.0.0.1:8080;
  server_name  pages-staging.18f.gov;
  port_in_redirect off;

  location / {
    root  /home/ubuntu/pages-staging;
    index  index.html;
    default_type text/html;
  }
}

Contributing

1. Fork the repo (or just clone it if you're an 18F team member)
2. Create your feature branch (git checkout -b my-new-feature)
3. Make your changes and test them via npm test or gulp test
4. Lint your changes with gulp lint
5. Commit your changes (git commit -am 'Add some feature')
6. Push to the branch (git push origin my-new-feature)
7. Create a new Pull Request

欢迎提交问题或 ping @ertzeid、@jbarnicle 或@mtorres253 询问您可能有的任何问题， 特别是如果当前文档应该已经解决了您的需求，但是 没有。

Public domain

该项目属于全球公共领域。 如中所述 CONTRIBUTING：

该项目在美国属于公共领域，版权所有 和世界范围内的工作相关权利通过放弃 CC0 1.0 通用公共领域贡献。

所有对该项目的贡献都将在 CC0 奉献精神下发布。 通过提交拉取请求，您同意遵守此放弃 版权权益。