Brightspot本地开发Docker容器

这些容器仅用于本地开发，专为该场景优化。生产环境使用请联系Brightspot。

[!NOTE] 自2025年7月24日起，不带构建号的容器镜像标签（如 brightspot/tomcat:9.0-jdk11）已弃用且不再支持。您现在应在项目中使用带构建号的完整镜像标签（如 brightspot/tomcat:9.0.107-jdk11-57）。详见弃用标签。

最新版本及其推荐的Docker Compose配置将始终在此文档中更新。

Docker Compose使用说明

1. 下载并安装Docker Desktop，确保其运行：[***]
2. 在项目根目录创建名为 docker-compose.yml 的文件，内容如下（将 ${my-project} 替换为项目名称或适当值）：

yaml
services:
  mysql:
    image: brightspot/mysql:percona80-11
    ports:
      - 3306:3306
    volumes:
      - mysql-data:/var/lib/mysql
      - mysql-logs:/var/log/mysql
  solr:
    image: brightspot/solr:8.11.1-52
    environment:
      - SOLR_CONFIG=dari-solr-11
    ports:
      - 8983:8983
    volumes:
      - solr-data:/var/solr
  tomcat:
    image: brightspot/tomcat:9.0.107-jdk11-57
    hostname: "${my-project}.brightspot"
    depends_on:
      mysql:
        condition: service_healthy
      solr:
        condition: service_healthy
    ports:
      - 5005:5005
      - 9010:9010
    volumes:
      - .:/code:cached
      - $HOME/.aws/credentials:/etc/aws/credentials:cached
      - storage-data:/servers/tomcat/storage
    environment:
      - ROOT_WAR="/code/web/build/libs/${my-project}-web-1.0.0-SNAPSHOT.war"
      - CONTEXT_PROPERTIES=/code/docker-context.properties
      - CONTEXT_PROPERTIES_OVERRIDES=/code/docker-context-overrides.properties
      - LOGGING_PROPERTIES=/code/docker-logging.properties
      - AWS_PROFILE="psd-${my-project}"
      - ENABLE_JACOCO=false
      - ENABLE_JFR=false
  apache:
    image: brightspot/apache:2.4-dims3.3.25-44
    depends_on:
      tomcat:
        condition: service_healthy
    ports:
      - 80:80
      - 443:443
    volumes:
      - storage-data:/var/www/localhost/htdocs/storage
volumes:
  mysql-data:
  mysql-logs:
  solr-data:
  storage-data:

• 确保war文件的相对路径正确！
• 如果计划使用恢复脚本恢复MySQL备份，请确保MySQL版本与生产环境一致。

3. 在项目根目录创建 docker-context.properties 文件，内容如下：

注意：这些上下文属性特定于 brightspot/solr:8.11.1-52。如果使用其他SOLR版本，请替换为相应版本的属性。

properties
dari/database/brightspot/delegate/solr/class=com.psddev.dari.solr.SolrDatabase
dari/database/brightspot/delegate/solr/groups=-* +cms.content.searchable
dari/database/brightspot/delegate/solr/clientSupplierClass=com.psddev.dari.solr.client.HttpSolrClientSupplier
dari/database/brightspot/delegate/solr/client/baseServerUrl=[***]
dari/database/brightspot/delegate/solr/collection=collection1
dari/database/brightspot/delegate/solr/saveData=false

4. 使用 docker-compose up 或 docker-compose up -d 启动容器。其他选项参见docker-compose文档。

• 注意： 每个发布端口只能同时运行一个容器。如果要同时运行两个Docker容器，请确保发布不同的端口号（详见Docker文档）。

5. 通过 http://localhost/cms 访问Brightspot。

环境变量

ROOT_WAR

ROOT_WAR 包含容器中项目war文件的路径。

CONTEXT_PROPERTIES

CONTEXT_PROPERTIES 包含属性文件的路径，该文件将被解析并作为 <Environment> 元素添加到Tomcat的context.xml中。

例如，docker-context.properties：

properties
dari/debugUsername=debug
dari/debugPassword=***
dari/debugRealm=Brightspot-Docker

将转换为 context.xml：

xml
   <Environment name="dari/debugUsername" value="debug" type="java.lang.String"/>
   <Environment name="dari/debugPassword" value="***" type="java.lang.String"/>
   <Environment name="dari/debugRealm" value="Brightspot-Docker" type="java.lang.String"/>

CONTEXT_PROPERTIES_OVERRIDES

CONTEXT_PROPERTIES_OVERRIDES 包含属性文件的路径，该文件将在 CONTEXT_PROPERTIES 之后解析并添加（见上文）。这允许您维护共享的项目级配置，并添加本地（即不受版本控制）的值。

注意： 如果在 CONTEXT_PROPERTIES 和 CONTEXT_PROPERTIES_OVERRIDES 中存在重复值，CONTEXT_PROPERTIES 中的原始值将被 CONTEXT_PROPERTIES_OVERRIDES 中的值替换。如果需要替换整个配置，也可以在 docker-compose.override.yml 中为 CONTEXT_PROPERTIES 设置不同的路径，使用修改后的版本。

LOGGING_PROPERTIES

LOGGING_PROPERTIES 包含将附加到Tomcat的logging.properties的属性文件路径。

例如，docker-logging.properties：

properties
com.my.package.level = FINE
com.my.package.MyClass.level = FINE
com.other.package.NoisyClass.level = SEVERE

INIT_SH

INIT_SH 包含容器启动时将执行的初始化脚本路径。

示例：

yaml
environment:
  - INIT_SH=/code/docker-tomcat-init.sh

注意： 确保 docker-tomcat-init.sh 是可执行的！

AWS_PROFILE

通过主机凭证文件访问AWS服务需两步：

1. 确保 ~/.aws/credentials 文件挂载到Docker容器中的 /etc/aws/credentials（见上文 docker-compose.yml）

2. 在 docker-compose.yml 的 environment: 下添加如下行并运行 docker-compose up 应用更改：

yaml
   - AWS_PROFILE=psd-${my-project}
   - AWS_REGION=us-east-1

注意，us-east-1已作为默认区域提供，仅在需要测试其他区域时才需覆盖。

现在，对主机凭证文件的任何更改（例如通过 beam credentials）都将对容器中的 DefaultAWSCredentialsProviderChain 可见。

ENABLE_JFR

在Tomcat进程上启用Java Flight Recorder。

如果Tomcat以 ENABLE_JFR=true 启动，可使用以下命令生成JFR转储：

sh
docker-compose exec tomcat jfr-dump.sh

默认情况下，将在/code中创建文件。可使用 JFR_DIR 环境变量覆盖默认路径，或在调用jfr-dump.sh时指定文件名作为第一个参数。

JFR转储文件可使用JDK Mission Control分析。

ENABLE_JACOCO

启用JaCoCo进行代码覆盖率分析。注意这将禁用Reloader。

shell
ENABLE_JACOCO=true

JACOCO_OPTS

传递给Jacoco的选项。这些将自动包含在 CATALINA_OPTS 中。

默认为 append=false。

shell
JACOCO_ARGS=destfile=/code/web/build/jacoco/playwright.exec,append=false,classdumpdir=/code/web/build/jacoco-classes/

TEMPLATE_CONFIG

如果 TEMPLATE_CONFIG 包含YAML文件路径（例如 TEMPLATE_CONFIG=/code/docker-template.yml），该文件将用于填充/etc/docker/templates中列出的ERB模板。

例如：

yaml
data:
  brightspot:
      extra_dari_db: otherdatabase
      extra_resources:
        - name: database1 # 必需
          minimum_idle: 4 # 默认：2
          idle_timeout: 20000 # 默认：***
          maximum_pool_size: 16 # 默认：12
          max_lifetime: 60000 # 默认：30000
          connection_timeout: 2000 # 默认：1000
          host: host # 默认：localhost
          port: 3306 # 默认：3306
          database_name: database1 # 默认：'name'属性值
          user: user # 必需
          password: password # 必需
        - name: database2
          minimum_idle: 4
          idle_timeout: 20000
          maximum_pool_size: 16
          max_lifetime: 60000
          connection_timeout: 2000
          host: host
          port: 3306
          database_name: database2
          user: user
          password: password

这将填充/servers/tomcat/conf/context.xml.erb和/servers/tomcat/conf/server.xml.erb中的 @data['brightspot']['extra_dari_db'] 设置。

还将在/servers/tomcat/conf/server.xml.erb中创建额外的资源链接。

未来的模板配置将在此处记录。

SSL

Apache服务器上启用了SSL。要信任证书以便任何域都能正常工作，请在Mac上运行以下命令：

curl -O [***]
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain brightspot-docker-ca.pem

缓存

HTTP请求缓存仅在响应中存在Cache-Control头时通过Apache mod_cache提供。

要完全禁用mod_cache，向 apache 容器添加环境变量：DISABLE_CACHE=true

任务主机

hostname 属性的唯一目的是提供一致的主机名，可在站点设置中发布为任务主机。

调试器

远程调试在端口5005上公开。

JMX

JMX提供了监控Brightspot性能、资源消耗和管理各种运行时方面的标准方式。默认启用。

使用JConsole或VisualVM等工具连接到 localhost:9010。

可使用环境变量 JMX_PORT 自定义此端口。确保在 ports 配置中内外使用相同值——Docker网络内外必须是相同端口。

本地开发（Reloader）

注意：如果使用4.1.8或更高版本的Brightspot Gradle插件，并在gradle.properties中添加了'systemProp.codePath=/code'，则此步骤不必要。

在项目根目录创建第二个文件 docker-compose.override.yml，内容如下：

yaml
services:
  tomcat:
    volumes:
      - $PWD:$PWD:cached

这将允许Brightspot扫描主机文件系统以自动重新编译Java源文件。

有用的命令和提示

将此函数添加到 ~/.bash_profile：

bash
function d() {
  docker-compose exec $1 bash --login;
}

使用此函数从项目目录按名称登录到每个容器，例如：

$ d tomcat
[brightspot tomcat:~]$ cat /servers/tomcat/conf/context.xml

以下命令可在当前工作目录位于项目内时在命令行执行。

• 重启单个容器
  • docker-compose restart tomcat
• 停止项目Docker容器（不删除数据）
  • docker-compose stop
• 启动已停止的Docker容器
  • docker-compose start 或 docker-compose start -d 在后台运行
• 删除容器
  • docker-compose down
  • 注意：这不删除命名卷中存储的数据。
• 删除未使用的卷
  • docker volume prune
• 使用Docker Sync启动
  • docker-sync-stack start
• 跟踪Tomcat日志
  • docker-compose logs -f tomcat
• 增加Docker可用内存到4 GB
  • [***]
• 在项目Docker容器中运行交互式shell
  • docker-compose exec tomcat bash
• 恢复数据库备份
  • 首先关闭所有容器：
    • docker-compose stop 或在前台运行时按Ctrl+C
    • 注意： 仅当mysql服务至少成功启动过一次时才有效。
  • 然后在mysql服务上运行恢复脚本：
    • docker-compose run mysql restore mysql -e qa --user ${UserName} --project ${DatabaseName} --account ${Account} --renamedb ${Project} --region=${Region}
      • Container - 容器名称，通常为项目名称
      • UserName - Ldap用户名
      • Project - 项目名称
      • DatabaseName - 通常为项目名称
      • Account - AWS账户
      • Region - （可选）AWS区域
    • 示例 docker-compose run mysql restore mysql -e qa --user bob --project myproject --account psd-myproject --renamedb myproject --region=us-west-1
  • 然后重启所有容器：
    • docker-compose start

升级MySQL镜像

对于运行 mysql5.6 或 percona5.6 的项目，按以下步骤升级到 percona57，然后可选择升级到 percona80。每个用户都需要单独执行这些步骤，因为每个用户都有自己独立的MySQL数据。

如果不关心现有数据，可跳过这些步骤，只需删除mysql卷，然后将mysql镜像更新为所需的 percona57 或 percona80。

1. 如果现有数据重要，备份当前MySQL卷。

2. 关闭Docker

   shell
   $ docker compose down
   

3. 在 docker-compose.yml 中将mysql镜像更新为 percona57-3

   yaml
   mysql:
     image: brightspot/mysql:percona57-3
   

4. 运行以下命令：

   shell
   $ docker compose up -d mysql
   $ docker compose exec mysql mysql_upgrade
   $ docker compose down mysql
   

5. 正常启动Docker，确保CMS和前端加载。此时已成功升级到Percona 5.7，可停止。

6. 如果要继续升级到 percona80，运行以下命令：

   shell
   $ docker compose exec mysql mysql --user=root --password
   mysql> SET GLOBAL innodb_fast_shutdown = 0;
   mysql> exit
   

   然后关闭Docker：

   shell
   $ docker compose down
   

7. 在 docker-compose.yml 中将mysql镜像更新为 percona80-11

   yaml
   mysql:
     image: brightspot/mysql:percona80-11
   

8. 运行以下命令（mysql uid已更改，因此需要将现有文件更新为新uid）：

   shell
   $ docker compose run --rm mysql sh
   $ sudo find /var/lib/mysql -user 999 -exec chown mysql {} \;
   $ sudo find /var/lib/mysql -group 999 -exec chown :mysql {} \;
   

9. 测试mysql

   shell
   $ docker compose up mysql
   

   如果mysql启动失败，类似：

   [ERROR] [MY-012526] [InnoDB] Upgrade is not supported after a crash or shutdown with innodb_fast_shutdown = 2. This redo log was created with MySQL 5.7.32-35, and it appears logically non empty. Please follow the instructions at [***]
   

   则运行以下命令：

   shell
   $ docker compose run --rm mysql sh
   $ rm /var/lib/mysql/ib_logfile0
   $ rm /var/lib/mysql/ib_logfile1