CommandBox Docker镜像文档

标签 (Tags)

注意：有关镜像版本中使用的CommandBox具体版本，请参阅变更日志。

• :latest (Dockerfile) - 最新稳定版本
• :3.9.0 - 镜像的标记版本 - 请勿与镜像中CommandBox的版本混淆
• :snapshot - 开发/BE版本
• :[tag]-snapshot - 标记变体的开发/BE版本（例如 - :adobe2021-snapshot）
• :jdk8 - 使用OpenJDK8的基础镜像
• :jre11 - 使用OpenJDK11 JRE的基础镜像
• :jdk11 - 使用OpenJDK11完整JDK的基础镜像
• :jre17 - 使用OpenJDK17 JRE的基础镜像
• :jdk17 - 使用OpenJDK17完整JDK的基础镜像
• :alpine (Dockerfile) - Alpine Linux版本的镜像 - 总体大小略有减少，并针对容器化运行时进行了优化
• :ubi9 (Dockerfile) - RHEL通用基础镜像版本的镜像
• :[engine][version] - 包含预热引擎的容器 - 无需在容器启动时下载服务器WAR：:lucee5(Dockerfile), :lucee-light(Dockerfile), :adobe2018(Dockerfile), :adobe2021(Dockerfile), :adobe2023(Dockerfile)
• :[engine][version]-alpine - 包含预热引擎的Alpine Linux版本镜像：:lucee5-alpine(Dockerfile), :lucee-light-alpine(Dockerfile), :adobe2018-alpine(Dockerfile), :adobe2021-alpine(Dockerfile)
• :[engine][version]-ubi9 - 包含预热引擎的RHEL ubi9版本镜像：:lucee5-ubi9(Dockerfile), :lucee-light-ubi9(Dockerfile), :adobe2018-ubi9(Dockerfile), :adobe2021-ubi9(Dockerfile)

注意：:latest标签当前使用OpenJDK11，所有其他预构建引擎镜像也是如此。如果您的应用程序或引擎需要JDK 8或JDK 17支持，请分别使用:jdk8或:jdk17标签。

概述 (Description)

CommandBox允许您在运行时使用基于文件或环境的约定配置整个CFML引擎环境。有关如何利用CommandBox开发和部署应用程序的更多信息，请参阅***文档。

此外，这些预构建镜像中包含了CommandBox模块dotenv和cfconfig，使您能够利用其他运行时环境和服务器配置选项。

当前支持的CFML引擎：

• Lucee: 5+
• Adobe ColdFusion 2018+

您还可以使用server.json配置指定自定义WAR进行部署。

使用方法 (Usage)

本节假设您使用的是***Docker镜像。

默认情况下，容器中的/app目录被映射为CommandBox主目录。要部署新应用程序，请先拉取镜像：

bash
docker pull ortussolutions/commandbox

然后，从项目根目录执行以下命令启动：

bash
docker run -p 8080:8080 -p 8443:8443 -v "/path/to/your/app:/app" ortussolutions/commandbox

默认情况下，容器的进程端口为8080（不安全）和8443（安全 - 如果在server.json中启用），因此容器启动后，您可以通过浏览器使用相应端口访问应用程序（我们在上面的run命令中显式暴露了这些端口以供外部访问）。您也可以在run命令中指定不同的端口参数，以分配容器中使用和暴露的端口，避免与Docker机器上的其他实例端口冲突：

bash
docker run -p 80:80 -p 443:443 -e "PORT=80" -e "SSL_PORT=443" -v "/path/to/your/app:/app" ortussolutions/commandbox

支持的架构和操作系统

所有基于Debian的镜像目前支持linux/amd64、linux/arm64和linux/arm/v7架构。Alpine构建目前仅支持linux/amd64。

环境变量 (Environment Variables)

CommandBox Docker镜像支持使用环境变量配置服务器。具体而言，该镜像包含cfconfig CommandBox模块，允许您为引擎提供自定义设置，包括管理员密码。

端口变量

• $PORT - 服务器应启动的端口。默认值为8080。
• $SSL_PORT - （如适用）服务器使用的SSL端口。默认值为8443。

负载均衡器配置

为了使用CommandBox v6及更高版本的多站点功能，如果您的多站点设置支持域名感知，则需要设置环境变量BOX_SERVER_WEB_useProxyForwardedIP=true（有关详细信息）。但请注意，启用此设置会使容器面临安全威胁，因为访问者可能绕过：

• 仅限内部的主机匹配
• 管理员阻塞的IP限制

以及可能允许欺骗客户端证书和/或SSL重定向/验证。因此，如果您选择启用此设置，应确保容器仅通过负载均衡器公开访问，并且Docker主机上的暴露容器端口不公开可用。启用此设置后，上游负载均衡器发送的X-Forwarded-Host等标头将在处理多站点流量时被识别。

HTTP/2支持

从Commandbox v5.3.0开始，所有CommandBox服务器默认启用HTTP/2。要获得浏览器对该协议的支持，您需要启用SSL并提供证书。

服务器配置变量

以下环境变量可用于修改运行时服务器配置。请注意，环境变量区分大小写，虽然考虑了一些小写/大写别名，但为确保这些变量生效，应使用一致的大小写。

• BOX_SERVER_APP_SERVERHOMEDIRECTORY - 提供时，将指定服务器主目录的自定义路径。默认情况下，此路径设置为${LIB_DIR}/serverHome，在大多数构建中解析为/usr/local/lib/serverHome。基于Alpine的构建默认路径为/usr/lib/serverHome。（注意：您也可以在应用程序的自定义server.json文件中提供此变量）
• APP_DIR - 应用程序目录（web根目录）。默认值为/app。如果部署的应用程序在根目录外有映射，应提供此环境变量以指向web根目录（例如/app/wwwroot）
• USER - 提供时，服务器进程将在指定的用户账户下运行
• USER_ID - 数字。与USER环境变量一起提供时，用户的UID将被分配此数字。这有助于确保挂载卷和文件的权限
• cfconfig_[engine setting] - 任何包含cfconfig_前缀的环境变量将被视为cfconfig设置，前缀后的部分被视为设置名称
• BOX_SERVER_CFCONFIGFILE - 可通过此环境变量提供兼容cfconfig的JSON文件。该文件将被加载并应用于服务器。如果存在adminPassword键，它将被用作Lucee引擎的服务器和Web上下文密码。您也可以在APP_DIR的根目录添加.cfconfig.json文件，它将被自动检测
• BOX_SERVER_APP_CFENGINE - 使用server.json语法，允许您指定容器的CFML引擎（例如lucee@5）。默认为CommandBox默认值（当前为lucee@4.5）
• BOX_SERVER_RUNWAR_CONSOLE_APPENDERLAYOUT - 设置为JSONTemplateLayout时，容器的日志输出将采用ndjson格式。有关此设置的更多信息，请参阅CommandBox文档中关于自定义日志布局的部分
• FINALIZE_STARTUP - 提供时，将生成最终启动脚本，该脚本在下次容器/镜像启动时被视为权威脚本。但请注意，最终启动脚本将绕过此列表中所有其他环境变量的评估检查，因为这些值将在启动文件中显式导出
• BOX_SERVER_PROFILE - 设置后，将用作运行时CommandBox服务器配置文件。默认情况下，由于容器服务器绑定到0.0.0.0的所有接口，CommandBox会将此值设置为production模式。如果您希望降低安全级别，需要提供此变量或在server.json文件中设置
• BOX_SERVER_WEB_REWRITES_ENABLE - 布尔值，指定是否启用/禁用服务器的URL重写。应用程序server.json文件中提供的重写配置将覆盖此参数
• CFPM_INSTALL 和 CFPM_UNINSTALL - 支持Adobe Coldfusion 2021引擎。当提供Coldfusion包管理器包的分隔列表时，这些包将在服务器启动前安装（或卸载）。需要预热的服务器才能使用这些变量
• BOX_INSTALL/box_install - 设置为true时，将在服务器启动前运行box install命令，以确保安装box.json文件中配置的所有依赖项

Docker运行时变量

• $HEALTHCHECK_URI - 指定容器健康检查的URI端点。默认情况下，每隔20秒检查[***]{PORT}/，超时30秒，重试15次后容器被标记为失败。注意：由于间隔、超时和重试设置无法动态设置，如果需要调整这些值，您需要从提供新HEALTHCHECK命令的Dockerfile构建

已弃用的环境变量

以下变量仍受支持，但已弃用，将在镜像的下一个主要版本中移除支持：

• SERVER_HOME_DIRECTORY - 改用BOX_SERVER_APP_SERVERHOMEDIRECTORY
• CFCONFIG 和 cfconfigfile - 改用BOX_SERVER_CFCONFIGFILE
• CFENGINE - 改用BOX_SERVER_APP_CFENGINE
• HEADLESS=true - 改用BOX_SERVER_PROFILE=production
• SERVER_PROFILE - 改用BOX_SERVER_PROFILE
• URL_REWRITES/url_rewrites - 改用BOX_SERVER_WEB_REWRITES_ENABLE

Docker Secrets

Docker secrets可以使用两种存储机制：

• 存储为主机上文件的密钥值（非swarm模式）。
• docker secret管理的键/值对（swarm模式）。

密钥扩展可通过以下两种机制之一（或两者）实现：

<<SECRET:*>>前缀

要将密钥用作此镜像中的变量，请指定占位符（例如<<SECRET:test_docker_secret>>）作为变量的值。在运行时，环境变量的值将被密钥替换。

使用主机文件存储的密钥示例：

yaml
version: '3.1'

services:

  sut:
    environment:
      - IMAGE_TESTING_IN_PROGRESS=true
      #- ENV_SECRETS_DEBUG # 取消注释以调试占位符替换
      # 这是将在运行时被密钥值替换的占位符
      - TEST_DOCKER_SECRET=<<SECRET:test_docker_secret>>
    ...
    
secrets:
  test_docker_secret:
    # 包含密钥值的文件
    file: ./build/tests/secrets/test_docker_secret

_FILE后缀约定

当任何环境变量以_FILE为后缀时，右侧赋值将被加载并扩展为后缀前的环境变量。最常见的用例是获取Docker密钥，但也可用于将运行时挂载的文件作为变量源。

例如，变量REINIT_PASSWORD_FILE=/run/secrets/reinit_password会将右侧文件路径的内容作为REINIT_PASSWORD环境变量的源。

最佳实践和自定义

自定义镜像

要创建自己的自定义Docker镜像，请以我们的Dockerfile仓库为参考开始自定义。您可以扩展任何基础镜像并添加自己的额外功能或模块。例如，安装Ortus Couchbase Lucee扩展：

dockerfile
FROM ortussolutions/commandbox:lucee5

ARG REDIS_EMAIL
ARG REDIS_LICENSE_KEY
ARG REDIS_ACTIVATION_CODE


# 从Forgebox安装Ortus Redis缓存扩展
RUN box install 5C558CC6-1E67-4776-96A60F9726D580F1

# 为扩展激活设置参数
REDIS_EXTENSION_EMAIL=$REDIS_EMAIL
REDIS_EXTENSION_LICENSE_KEY=$REDIS_LICENSE_KEY
REDIS_EXTENSION_ACTIVATION_CODE=$REDIS_ACTIVATION_CODE
REDIS_EXTENSION_SERVER_TYPE=Production

# 使用新扩展预热服务器
RUN ${BUILD_DIR}/util/warmup-server.sh

我们建议使用预标记的镜像作为基础，而不是从头开始。

优化启动时间

除了CommandBox默认引擎Lucee 5外，CFML服务器引擎在容器运行时下载和安装，这可能导致启动时间显著增加（即使基础镜像中已下载Lucee 5，"冷启动"也会有时间损失）。建议生产环境构建使用特定引擎变体，确保服务器在容器启动时已下载、就位并预热。

基本示例如下：

dockerfile
FROM ortussolutions/commandbox:lucee5

# 将应用程序文件复制到根目录
COPY ./ ${APP_DIR}/

在许多情况下，您会有特定环境的构建，带有自定义配置选项。以下示例使用build目录，其中包含特定环境部署的其他配置文件：

dockerfile
FROM ortussolutions/commandbox:lucee5

ARG CI_ENVIRONMENT_NAME

# 将应用程序文件复制到根目录
COPY ./ ${APP_DIR}/

# 复制特定环境的文件
COPY ./build/env/${CI_ENVIRONMENT_NAME}/tier/ ${APP_DIR}/

# 安装box.json依赖项
RUN cd ${APP_DIR} &&