herokuish

![Circle CI]([] ![IRC Channel]([] ![Docker Hub]([***]

一个用于在容器中模拟Heroku构建和运行时任务的命令行工具。

Herokuish专为平台作者设计。该项目整合并解耦了Heroku兼容性逻辑（运行构建包、解析Procfile）和支持工作流（导入/导出slug包），使其独立于特定平台镜像（如Dokku/Buildstep、Deis、Flynn等中的镜像）。

其目标是成为所有平台共享的、权威的、维护良好且经过严格测试的Heroku模拟工具。它基于Heroku:18和Heroku:20系统镜像，共同构成实现Heroku兼容性的工具集。

Herokuish是社区项目，与Heroku无任何关联。

获取herokuish

从发布页面下载并解压最新的二进制tarball。

例如，可直接在Dockerfile中通过一步操作安装到/bin目录：

RUN curl --location --silent [***] \
		  | tar -xzC /bin

Herokuish依赖Bash（4.0或更高版本）和一些标准GNU工具（通常已预装）。它可能无法在Busybox上运行，Heroku构建包同样如此。

使用herokuish

Herokuish旨在在容器后台工作，不强制规定容器的构建和操作方式。实际上，它并不特定绑定于Docker。其专注于精确模拟Heroku功能，让用户可围绕其设计和编排容器。

$ herokuish

可用命令:
  buildpack                使用和安装构建包
    build                    使用已安装的构建包构建应用
    install                  从Git URL安装构建包（可选指定提交哈希）
    list                     列出已安装的构建包
    test                     使用已安装的构建包构建并运行应用测试
  help                     显示命令帮助信息
  paths                    显示路径设置
  procfile                 使用Procfile并运行应用命令
    exec                     以非特权用户身份使用类Heroku环境运行
    parse                    从Procfile获取进程类型的命令字符串
    start                    通过exec运行Procfile中的进程类型命令
  slug                     管理应用slug包
    export                   将生成的slug包tarball导出到URL（PUT）或STDOUT
    generate                 从当前应用生成gzip压缩的slug包tarball
    import                   从URL或STDIN导入gzip压缩的slug包tarball
  test                     通过Herokuish测试运行应用
  version                  显示版本和支持的版本信息

主要功能围绕构建包命令、procfile/exec命令和slug命令。这些命令可协同工作，也可独立使用。

例如，生成Docker镜像而不产生中间slug包的构建流程可忽略slug命令；非构建包运行时镜像（如google/python-runtime）可能仅使用procfile命令来支持Procfile。

herokuish exec默认通过setuidgid降低root权限，若已以非root用户运行，setuidgid将失败，可通过设置环境变量HEROKUISH_SETUIDGUID=false禁用此行为。

构建包

Herokuish不自带构建包，但针对Heroku支持的最新构建包版本进行测试。可通过herokuish version查看支持信息，示例输出：

$ herokuish version
herokuish: 0.3.0
buildpacks:
  heroku-buildpack-multi     cddec34
  heroku-buildpack-nodejs    v60
  heroku-buildpack-php       v43
  heroku-buildpack-python    v52
  heroku-buildpack-ruby      v127
  ...

可通过herokuish buildpack install安装所有支持的构建包，或通过herokuish buildpack install <url> [committish]手动安装单个构建包。也可挂载包含平台支持构建包的目录（见下节“路径”），或将构建包烘焙到镜像中，这些决策由用户自行决定。

路径

使用herokuish paths查看其使用的相关系统路径。可通过这些路径在容器内导入或挂载数据，也可通过设置相应环境变量覆盖默认路径。

$ herokuish paths
APP_PATH=/app                    # 运行时应用路径
ENV_PATH=/tmp/env                # 定义基础环境的文件路径
BUILD_PATH=/tmp/build            # 构建期间的工作目录
CACHE_PATH=/tmp/cache            # 构建包缓存位置
IMPORT_PATH=/tmp/app             # 挂载后需复制到应用路径的路径
BUILDPACK_PATH=/tmp/buildpacks   # 已安装构建包的路径

入口点

部分子命令设计为容器的默认命令或入口点命令。具体而言，herokuish会检测自身是否以/start、/exec或/build调用，从而直接运行相应子命令。这意味着可将二进制文件安装到这些位置或创建符号链接，使其作为容器入口点。

帮助

无需担心帮助命令，它会准确说明命令功能：

$ herokuish help slug export
slug-export <url>
  将生成的slug包tarball导出到URL（PUT）或STDOUT

slug-export ()
{
    declare desc="将生成的slug包tarball导出到URL（PUT）或STDOUT";
    declare url="$1";
    if [[ ! -f "$slug_path" ]]; then
        return 1;
    fi;
    if [[ -n "$url" ]]; then
        curl -0 -s -o /dev/null --retry 2 -X PUT -T "$slug_path" "$url";
    else
        cat "$slug_path";
    fi
}

使用Herokuish测试Heroku/Dokku应用

推送应用到Dokku或Heroku时遇到问题？可使用Herokuish和本地Docker实例进行调试。这对Dokku尤其有用，可帮助判断是构建包问题还是Dokku自身问题。构建包问题应提交给Herokuish。

运行应用测试

$ docker run --rm -v /abs/app/path:/tmp/app gliderlabs/herokuish /bin/herokuish test

将本地应用源目录挂载到/tmp/app并运行/bin/herokuish test，会通过构建包编译过程运行应用，然后启动web进程并尝试连接Web根路径。若出现问题，将非零退出。

::: 构建应用 :::
-----> 检测到Ruby应用
-----> 编译Ruby/Rack
-----> 使用Ruby版本：ruby-1.9.3
  ...

提交问题时可使用此输出。

使用Heroku构建包运行应用测试用例

$ docker run --rm -v /abs/app/path:/tmp/app gliderlabs/herokuish /bin/herokuish buildpack test

将本地应用源目录挂载到/tmp/app并运行/bin/herokuish buildpack test，会通过构建包测试编译过程运行应用，然后执行test命令运行应用测试。

-----> 检测到Ruby应用
-----> 设置Ruby/Rack测试环境
-----> 使用Ruby版本：ruby-2.3.3
  ...
-----> 检测rake任务
-----> 运行测试：bundle exec rspec
       .
       0.00239秒内完成（文件加载耗时0.07525秒）
       1个示例，0个失败

故障排除

若需深入了解herokuish的执行过程，可设置$TRACE环境变量。

$ docker run --rm -e TRACE=true -v /abs/app/path:/tmp/app gliderlabs/herokuish /bin/herokuish test
+ [[ -d /tmp/app ]]
+ rm -rf /app
+ cp -r /tmp/app /app
+ cmd-export paths
+ declare 'desc=将函数导出为命令'
+ declare fn=paths as=paths
+ local ns=
++ cmd-list-ns
++ sort
++ grep -v :
++ for k in '"${!CMDS[@]}"'
++ echo :help
...
++ unprivileged /tmp/buildpacks/custom/bin/detect /tmp/build
++ setuidgid u33467 /tmp/buildpacks/custom/bin/detect /tmp/build
++ true
+ selected_name=
+ [[ -n /tmp/buildpacks/custom ]]
+ [[ -n '' ]]
+ title '无法选择构建包'
-----> 无法选择构建包
+ exit 1

贡献

欢迎提交拉取请求！Herokuish使用Bash和Go编写。编写Bash代码时，请遵循本项目使用的Bash风格指南。

开发者需安装Go并支持Darwin和Linux交叉编译。测试需要Docker环境。若使用OS X，建议使用boot2docker。

除Github Issues外，可在Freenode的#gliderlabs频道参与帮助和讨论。

发布

任何人都可提议发布。首先在Makefile和Dockerfile中更新版本号，确保CHANGELOG.md更新，测试通过，然后从master分支向release分支提交拉取请求。维护者批准合并后，CircleCI将构建发布版本并上传到Github。

致谢

本项目由Deis Project赞助并使其成为可能。

Herokuish的设计基于在Dokku、Deis和Flynn中开发和重新开发Heroku兼容性的经验，代码基于这三个项目，感谢这些项目的所有贡献者。

最后，感谢Heroku开创了如此出色的平台，并激励我们进一步发展。

许可

BSD