🅷📦 - hbox

hbox是一个利用容器技术管理软件包的命令行接口（CLI），由Rust 🦀 编写。

特性

hbox提供以下特性

• 容器隔离：使用容器隔离软件包，允许多个版本共存而不冲突。
• 强大的配置选项：通过配置文件实现高度定制，允许您定义软件包别名并通过config.json设置自动卷挂载。
• 支持管道：在hbox run中支持管道的使用，实现高效的命令链。
• 方便的shim：为所有已安装的软件包创建shim（别名快捷方式），简化命令输入，从hbox run <package alias> <commands>到<package alias> <commands>。
• 可访问内部二进制文件：提供对镜像内部二进制文件的直接访问。用户可以覆盖默认的入口点，直接访问容器内的工具和实用程序。
• 可定制环境变量：允许为每个软件包设置环境变量，以实现对运行时配置的更精细控制。
• 支持Docker和Podman：提供对Docker和Podman容器引擎的无缝支持，提供在容器运行时选择上的灵活性。
• 自定义镜像:
  • 构建自定义镜像：允许用户根据需要构建自定义镜像，可以是替换现有软件包或引入新的软件包。用户可以在配置文件中定义构建上下文、Dockerfile和构建参数。
  • 动态构建参数：支持动态和用户定义的构建参数，使用内部变量如hbox_package_name和hbox_package_version来定制构建过程以满足特定需求。
  • 注册表和本地镜像：管理从注册表中拉取的镜像和本地构建的镜像，提供在hbox环境中如何获取和使用镜像的灵活性。

安装

要通过cargo安装hbox，请运行以下命令

cargo install hbox

设置

为了确保所有hbox二进制文件和shim都可以找到，请将这些行添加到您的.bashrc或.zshrc文件中

export HBOX_DIR="$HOME/.hbox"
export PATH="$HBOX_DIR/shims":$PATH

如果您通过 cargo 安装了 hbox，当执行 shims 时，hbox 二进制文件应该已经存在于您的 PATH 环境变量中。

命令

> hbox help
CLI tool that leverages container technology to manage packages.

Usage: hbox <COMMAND>

Commands:
  info    Print debug information about the hbox environment and configuration
  list    List all installed packages and their versions
  add     Add and install a specific version of a package
  remove  Remove a specific version of a package
  use     Set the current version of a package as the default
  run     Run a command from a package
  config  Configure hbox settings
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

用法

以下是一些演示如何使用 hbox 的示例

> hbox version
0.6.0
> hbox info
[System Information]
OS Details:
  Name           : linux
  Architecture   : x86_64
  Family         : unix

[Application Configuration]
Version          : 0.6.0
Engine           : docker
Directories and Files:
  base dir       : /home/helton/.hbox
  config file    : /home/helton/.hbox/config.json
  overrides dir  : /home/helton/.hbox/overrides
  versions dir   : /home/helton/.hbox/versions
  logs dir       : /home/helton/.hbox/logs
  shims dir      : /home/helton/.hbox/shims
  index dir      : /home/helton/.hbox/index
Environment Vars:
  HBOX_DIR       : /home/helton/.hbox
> hbox list
> hbox add jq
latest: Pulling from jqlang/jq
...
Added 'jq' version latest.
> hbox list jq
- jq:
  - latest ✔
> jq --version
jq-1.7.1
> hbox add node latest
latest: Pulling from library/node
...
Added 'node' version 'latest'. Current version is 'latest'.
> hbox list
- [jq]
  - versions
    - latest ✔
- [node]
  - versions
    - latest ✔
> hbox list node
- [node]
  - versions
    - latest ✔
> node --version
v22.0.0
> hbox add node 14 --set-default
14: Pulling from library/node
...
Added 'node' version '14'. Current version is '14'.
> hbox list node
- [node]
  - versions
    - 14 ✔
    - latest
> node --version
v14.21.3
> hbox use node latest
Package 'node' set to version 'latest'
> node --version
v22.0.0
> hbox list node
- [node]
  - versions
    - 14
    - latest ✔

这些示例应为您提供快速入门指南，帮助您了解您可以使用 hbox 执行的基本操作。

配置

通过 config.json 进行配置

hbox 的一般配置由 $HBOX_DIR/config.json 文件管理。目前，您可以通过该文件控制容器引擎、日志的使用方式以及启用一些实验性功能。

{
  "engine": "docker",
  "logs": {
    "enabled": true,
    "level": "debug",
    "strategy": "truncate"
  },
  "experimental": {
    "capture_stdout": false,
    "capture_stderr": false
  }
}

您可以通过手动编辑该文件或使用 hbox config 命令来更新它。该 hbox config 命令提供了一种方便的方法来读取和写入配置设置，而无需直接编辑 JSON 文件。您可以使用 hbox config 或其别名 hbox configure。

示例

• 设置配置值:

  hbox config logs.enabled false
  hbox config logs.level debug
  hbox config engine podman
  

• 获取配置值:

  hbox config logs.enabled
  hbox config engine
  

根据是否提供了值，该命令将更新配置文件或打印配置设置的当前值。

通过使用 hbox config 命令，您可以确保您的配置更改被正确应用，而无需将语法错误引入 JSON 文件的风险。

属性

config.json 文件用于控制 hbox 的行为。以下是配置文件中可用的每个属性的详细信息。

属性详细信息

• engine：指定是否使用 docker 或 podman 作为容器引擎。默认为 docker。

• logs：此对象配置 hbox 的日志行为。

  • enabled：一个布尔值，表示是否启用日志记录。如果设置为 true，则日志记录处于活动状态。
  • level：指定日志的详细程度。选项包括
    • debug：通常对开发人员有用的详细信息。
    • info：有关应用程序操作的一般信息。
    • warn：有关可能有问题的情况的警告。
    • error：指示严重问题的错误消息。
  • strategy：确定如何管理日志文件。选项包括
    • append：将新的日志条目添加到现有日志文件的末尾。
    • truncate：用新条目覆盖现有的日志文件。

• 实验性：此对象包含尚未完全支持的实验性功能的设置。

  • capture_stdout：一个布尔值，指示是否应捕获命令的标准输出并将其发送到日志。无论此选项如何，stdout 都将正常打印。
  • capture_stderr：一个布尔值，指示是否应捕获命令的标准错误并将其发送到日志。无论此选项如何，stderr 都将正常打印。

这些属性允许您自定义 hbox 的行为，特别是它如何处理日志和实验性功能，从而更好地控制应用程序的操作。

模拟器

hbox 使用模拟器来有效地管理您的已安装包。有两种类型的模拟器：包模拟器和二进制模拟器。

包模拟器

对于普通包，模拟器将使用包名和任何提供的参数调用 hbox run。例如，名为 node 的包的模拟器

#!/bin/sh
hbox run node "$@"

二进制模拟器

对于包内的二进制文件，模拟器将包括包名和二进制名。这通知 hbox 使用哪个包和二进制文件。例如，位于 busybox 包内的二进制文件 mysh 的模拟器

#!/bin/sh
hbox run busybox::mysh "$@"

包注册表/索引

hbox 中的包注册表/索引由 $HBOX_DIR/index 目录管理。此目录具有分片结构，其中每个包都有一个单独的文件来存储配置信息。将来，它将集中在其自己的存储库/服务器中，允许您按需获取它。

属性

以下配置是用于索引（$HBOX_DIR/index/<shard>/<package>.json）和覆盖（$HBOX_DIR/overrides/<package>.json）文件。

属性详细信息

• image：指定镜像配置，可以包括构建指令。这允许使用内部变量如 hbox_package_name 和 hbox_package_version 进行动态和用户定义的构建参数。

• ports：定义主机和容器之间的端口映射。每个端口映射包括

  • host：主机机器上的端口。
  • container：容器内部的端口。

• volumes：定义主机和容器之间的卷映射。每个卷映射包括

  • source：主机机器上的路径。
  • target：容器内部的路径。

• current_directory：设置容器内部的当前工作目录。这是默认执行命令的位置。

• binaries：列出容器内可用的二进制文件。每个二进制文件包括

  • name：二进制文件的名字。
  • path：容器内部二进制文件的路径。
  • cmd（可选）：默认命令参数数组。
  • wrap_args（可选）：一个布尔值，表示是否将参数用引号括起来。

• only_shim_binaries：表示是否只为包配置中的二进制文件创建shim。默认情况下，为包名创建shim。如果启用，则只有二进制文件会有shim。

• environment_variables：指定容器中要设置的环境变量。每个变量包括

  • name：环境变量的名字。
  • value：环境变量的值，可以引用主机环境变量。

这些属性允许您自定义每个包在容器中的运行方式，提供对运行时环境的灵活性和控制。

示例

示例：$HBOX_DIR/index/g/golang.json

{
  "image": {
    "name": "docker.io/golang"
  },
  "volumes": [
    {
      "source": ".",
      "target": "/app"
    }
  ],
  "current_directory": "/app",
  "binaries": [
    {
      "name": "go",
      "path": "/usr/local/go/bin/go"
    },
    {
      "name": "gofmt",
      "path": "/usr/local/go/bin/gofmt"
    }
  ],
  "only_shim_binaries": true
}

覆盖配置

要覆盖包配置，请创建一个覆盖文件，位于 $HBOX_DIR/overrides 而不是修改 $HBOX_DIR/index 文件夹。此目录未分割，因此您可以直接将您的 <package>.json 文件放置在那里。覆盖配置将优先于索引配置，内容不会在内存中合并。

有关覆盖配置的属性，请参阅 包注册表/索引。

示例

以下是一个 $HBOX_DIR/overrides/busybox.json 的示例

{
  "image": {
    "name": "docker.io/busybox"
  },
  "ports": [
    {
      "host": 8090,
      "container": 8000
    },
    {
      "host": 8091,
      "container": 8001
    }
  ],  
  "volumes": [
    {
      "source": ".",
      "target": "/app"
    }
  ],
  "current_directory": "/app",
  "binaries": [
    {
      "name": "tree",
      "path": "/bin/tree"
    },
    {
      "name": "mysh",
      "path": "/bin/sh",
      "cmd": ["-c"],
      "wrap_args": true
    }
  ],
  "only_shim_binaries": true,
  "environment_variables": [
    {
      "name": "HTTP_PROXY",
      "value": "$HTTP_PROXY"
    },
    {
      "name": "HTTPS_PROXY",
      "value": "$HTTPS_PROXY"
    },
    {
      "name": "NO_PROXY",
      "value": "$NO_PROXY"
    }
  ]
}

在上面的示例中，我们将 mysh 定义为指向 /bin/sh 的二进制文件，在 busybox 映像内部。您可以使用它如下

> mysh ls -alh

我们还设置了 -c 作为默认命令，并指定所有参数都应该用引号括起来。执行的完整命令将是

docker run -it --rm --name hbox-busybox-latest-qNDyEVzrUb -v .:/app -w /app -e HTTP_PROXY=$HTTP_PROXY -e HTTPS_PROXY=$HTTPS_PROXY -e NO_PROXY=$NO_PROXY --entrypoint /bin/sh docker.io/busybox:latest -c "ls -alh"

包版本管理

hbox 维护一个目录 $HBOX_DIR/versions，该目录跟踪每个包的当前版本。每个包在该目录中都有一个文件，由 hbox 管理，不应手动编辑。

属性

使用 hbox 安装的每个包都有一个位于 $HBOX_DIR/versions 目录中的版本文件。这些文件的命名格式为 <package>.json，并跟踪已安装的所有包版本。以下是一个版本文件中所有可用的属性的详细信息。

属性详细信息

• name: 包的名称。这是一个必需的属性，用于唯一标识包。

• versions: 列出已安装的包的所有版本。数组中的每个条目都是表示版本的字符串。

• current: 当前活动的包版本。当执行包时将使用此版本。

示例

node 包的版本文件示例

{
  "name": "node",
  "versions": [
    "latest",
    "14",
    "15"
  ],
  "current": "15"
}

此示例表明，node 包已安装三个版本（latest、14 和 15），当前将 15 设置为活动版本。

日志

如果您在 $HBOX_DIR/config.json 文件中启用日志，它们将出现在 $HBOX_DIR/logs 文件夹中。使用此功能可以查看在用户界面中通常不会显示的底层执行了哪些命令。

注意：分享日志时请小心，因为它们可能包含敏感信息，例如API密钥和环境变量。

如何操作

从自定义镜像创建包

要构建自定义镜像，您需要有一个Dockerfile和一个 .json hbox配置文件。

以 pkl 为例，创建一个 Dockerfile 文件

FROM alpine:latest

ARG VERSION=0.25.3

RUN apk add --no-cache curl

WORKDIR /usr/local/bin

RUN curl -L -o pkl https://github.com/apple/pkl/releases/download/${VERSION}/pkl-alpine-linux-amd64 && \
    chmod +x pkl

ENTRYPOINT ["pkl"]

由于这是一个自定义包，我们需要让它对hbox可见，所以我们将将其添加到 $HBOX_DIR/overrides 文件夹中的 pkl.json。我们还可以使用hbox内部变量将值传递给Dockerfile并相应地标记镜像

{
  "image": {
    "name": "hbox.${hbox_package_name}",
    "build": {
      "context": "/home/helton/dockerfiles",
      "dockerfile": "/home/helton/dockerfiles/pkl.Dockerfile",
      "args": {
        "VERSION": "${hbox_package_version}"
      }
    }
  }
}

现在我们可以安全地将 pkl 添加到hbox中的包

> hbox add pkl 0.25.3
[+] Building 4.8s (8/8) FINISHED
...
 => => naming to docker.io/library/hbox.pkl:0.25.3  
Added 'pkl' version '0.25.3'. Current version is '0.25.3'.
> which pkl
/home/helton/.hbox/shims/pkl
> pkl --version
Pkl 0.25.3 (Linux 5.15.0-1053-aws, native)

下一步

如果您想查看我对项目未来的想法，请查看 路线图。