Crab 🦀

crab 是一个用于处理本地开发环境的简单Unix工具集。

它旨在允许开发者在本地运行多个十二要素风格的Web应用程序，并通过主机名而不是端口号来访问它们。它故意设计得尽可能简单，因此不会尝试管理多个进程。

它做什么？

Crab执行以下操作

1. 理解env文件。
2. 理解procfiles。
3. 可以操作$PATH环境变量。
4. 管理端口并提供本地虚拟主机路由器。

crab二进制文件可以通过三种方式调用

1. 使用要运行的文字命令：crab python manage.py shell
2. 使用来自procfile的进程名称：crab web
3. 作为一个特殊情况来启动虚拟主机路由器：crab router（见下文）。

Crab本身完全通过环境变量进行配置，因此开发人员可以设置一些简单的环境变量（例如在.bashrc中），以匹配他们的项目布局，然后Crab只需做“正确的事”。

env文件

env文件是一个包含键值对的文本文件，如下所示

SOME_VARIABLE=somevalue
ANOTHER_VARIABLE=anothervalue

遵循12要素指南，应用程序的配置（所有可能在不同环境之间变化的项）应存储在环境变量中。env文件为开发人员提供了一个指定项目环境变量的简单方法。

默认情况下，Crab会在项目目录内部寻找名为.env的env文件（即从哪里执行crab）。这可以通过使用ENV_FILE环境变量来覆盖。ENV_FILE可以是一个以逗号分隔的文件路径列表，将按顺序解析。例如，您可以使用configs/development/env作为已签入的env文件，然后有一个本地的.env来覆盖单个变量。在这种情况下，使用export ENV_FILE=configs/development/env,.env。

示例

$ echo 'FOO=bar' > .env
$ crab sh -c 'echo $FOO'
bar

procfiles

Procfile 是一个文本文件，它定义了应用程序正常运行所需运行的过程。它包含从进程名称到命令的映射，如下所示

web: python manage.py runserver
worker: python manage.py worker

默认情况下，Crab 会在项目目录内（即执行 crab 的位置）查找名为 Procfile 的文件。这可以通过 PROC_FILE 环境变量来覆盖。例如 export PROC_FILE=configs/development/procfile。要指定多个 procfile 位置，并按顺序使用，请使用 export PROC_FILE="configs/development/Procfile,configs/development/procfile"

要运行 procfile 中定义的进程，请使用 crab <processname>。例如，crab web 将启动上面示例 procfile 中定义的 web 进程。请注意，Crab 仅从 procfile 中运行 单个 进程。它不能同时启动 procfile 中的所有进程。这是设计上的。如果您想使用 procfile 中的多个进程，只需在每个单独的终端分割或标签中分别使用 crab 启动每个进程。

$PATH

设计用于隔离每个项目依赖环境工具通常通过在项目特定子目录中复制语言二进制和库来实现。Python 的 virtualenv 工具是主要例子。

Crab 可以将虚拟env的路径添加到 $PATH 环境变量之前。这意味着您在使用虚拟env之前不需要“激活”它——只需运行 crab python manage.py runserver 即可自动使用虚拟env中的 python 二进制文件。

默认情况下，路径 env/bin 将添加到 $PATH 之前。您可以通过设置 BIN_DIRS 环境变量来覆盖此设置。

端口

许多开发者同时处理多个项目以及/或者多个服务。当每个都需要自己的 web 服务器时，每个服务器进程需要不同的端口进行绑定。例如，Django 的 manage.py runserver 默认绑定到端口 8000。如果您同时工作在两个 Django 项目中，您必须将第二个项目运行在不同的端口上，比如 manage.py runserver 0.0.0.0:8001。当您在开发五个或十个微服务时，这可能会变得非常难以管理。

Crab 通过提供空闲端口来帮助解决这个问题。端口作为环境变量（作为 $PORT）提供，并替换到命令中。例如

crab python manage.py '0.0.0.0:$PORT'

您会看到 Django 的开发服务器以（比如）的方式启动

Django version 2.2, using settings 'project.settings'
Starting development server at http://0.0.0.0:63601/
Quit the server with CONTROL-C.

Procfile 中具有名为 "web" 的任何命令或包含字符串 "$PORT" 的任何命令都将提供端口。在其他情况下，可以通过设置环境变量 CRAB_PROVIDE_PORT 明确请求。

（请注意，对于非 procfile 命令，变量必须加引号，否则 shell 将尝试替换 $PORT，这是不可行的）。

虚拟主机路由

上面的端口功能仅在与 Crab 的另一个组件结合使用时有用：虚拟主机路由器。通过在单独的终端标签或分割中输入 crab router 来启动它。默认情况下，路由器绑定到端口 8080（下面将详细介绍此问题）。

现在，如果您运行的任何其他进程具有名为 VIRTUAL_HOST 的环境变量，路由器可以“看到”它们，并自动将流量路由到它们提供的端口。

您可以在项目的 .env 文件中设置此环境变量，例如

VIRTUAL_HOST=mywebsite.localhost

然后您可以通过启动（或重启）您的项目，在浏览器中访问 http://mywebsite.localhost:8080，流量将神奇地被路由到正确的位置。

（请注意，至少 Chrome 会自动将所有以 TLD .localhost 结尾的流量路由到 127.0.0.1。其他浏览器可能或可能不会遵循此标准）。

路由器绑定的端口可以通过设置 CRAB_ROUTER_PORT 环境变量进行更改。如果未设置，路由器将首先尝试绑定到端口号 80，如果失败，则回退到 8080。这意味着如果您使用 sudo crab router 启动路由器，您就可以在浏览器中使用 http://mywebsite.localhost - 更好！

路由器仅设计用于本地开发，因此默认绑定到 127.0.0.1。您可以将 CRAB_ROUTER_HOST 设置为自定义此值。

如何安装Crab

Python没有很好的内置方式来安装命令行工具。有一些选择

使用homebrew

可以从我们的homebrew tap下载Crab

brew install dabapps/tap/crab

这还会将路由器添加为服务，可以使用 brew services start crab 启动。

全局安装

您可以尝试使用 pip install --user crabtools。这将全局安装 crab 及其依赖项。根据您如何设置您的开发环境，这可能不是您想要的。

在虚拟环境中安装

您可以在您的机器上创建一个虚拟环境，然后在其中安装 pip install crabtools，然后将该虚拟环境的 bin 目录添加到您的 $PATH 中（例如，通过在 .bashrc 中设置 $PATH）或将二进制文件链接到已经在您的 $PATH 上的某个地方（例如，使用 sudo ln -s /path/to/your/venv/bin/crab /usr/local/bin/crab）。

使用pipx

pipx 是管理用Python编写的命令行程序的出色工具。它基本上创建和管理包含隔离命令行工具的虚拟环境。按照说明安装 pipx，然后执行 pipx install crabtools。

在Crab上开发

请确保所有代码都符合Black格式规则。在您的虚拟环境中安装 black，然后执行 crab black crab/ setup.py。