axiom/docker-erddap

ERDDAP Docker镜像

http://coastwatch.pfeg.noaa.gov/erddap/index.html Docker镜像，包含实验性功能（下文所述的datasets.d）。

上游官方ERDDAP Docker镜像

从v2.27.0版本开始，本镜像（axiom/docker-erddap）基于官方ERDDAP Docker镜像（erddap/erddap）构建。

如果您未使用axiom镜像提供的任何实验性功能（特别是datasets.d），建议使用官方ERDDAP Docker镜像。

更多详情请参见https://hub.docker.com/r/erddap/erddap%E3%80%82

版本

最新版本：

• axiom/docker-erddap:latest
• axiom/docker-erddap:v2.28.1
• axiom/docker-erddap:v2.27.0
• axiom/docker-erddap:2.25.1-jdk21-openjdk

查看所有可用版本https://hub.docker.com/r/axiom/docker-erddap/tags%E3%80%82%E5%8D%87%E7%BA%A7%E6%9C%8D%E5%8A%A1%E5%99%A8%E5%89%8D%EF%BC%8C%E8%AF%B7%E5%8A%A1%E5%BF%85%E6%9F%A5%E9%98%85https://coastwatch.pfeg.noaa.gov/erddap/download/changes.html%E6%96%87%E6%A1%A3%E3%80%82

使用任何latest-*镜像时需谨慎，它们跟踪上游镜像，未经过标记版本镜像那样彻底的测试。

重大变更

重大变更仅针对本镜像添加的功能。升级前还请查阅https://erddap.github.io/changes%E3%80%82

• v2.27.0
  • CORS默认关闭。如需启用，设置ERDDAP_enableCors=true。

快速启动

bash
docker run -d -p 8080:8080 docker.xuanyuan.run/axiom/docker-erddap:latest-jdk21-openjdk

运行ERDDAP CLI工具

GenerateDatasetsXml

bash
docker run --rm -it \
  -v $(pwd)/logs:/erddapData/logs \
  --workdir /usr/local/tomcat/webapps/erddap/WEB-INF \
  docker.xuanyuan.run/axiom/docker-erddap:latest \
  bash GenerateDatasetsXml.sh -verbose

或者，生成基础数据集配置（无需输入，供后续自定义）：

bash
./make-dataset-xml.sh /path/to/your.csv EDDTableFromAsciiFiles > /path/to/your-dataset.xml

配置

Tomcat

有关配置Tomcat的说明，请参见https://github.com/unidata/tomcat-docker%EF%BC%88%E6%9C%AC%E9%95%9C%E5%83%8F%E5%80%9F%E9%89%B4%E8%87%AA%E6%AD%A4Tomcat%E9%95%9C%E5%83%8F%EF%BC%89%E3%80%82

CORS

CORS默认关闭。如需启用，设置环境变量ERDDAP_enableCors=true。

ERDDAP

可通过以下任一方式配置ERDDAP容器实例，以满足需求。

1. 挂载自定义content/erddap目录：

   bash
   docker run \
       -p 8080:8080 \
       -v /path/to/your/erddap/directory:/usr/local/tomcat/content/erddap \
       ... \
       axiom/docker-erddap
   

   自定义内容目录应包含http://coastwatch.pfeg.noaa.gov/erddap/download/setup.html#setup.xml%E5%92%8Chttp://coastwatch.pfeg.noaa.gov/erddap/download/setupDatasetsXml.html%E6%96%87%E4%BB%B6%E3%80%82%E8%BF%98%E5%8F%AF%E5%8C%85%E5%90%AB%E5%9C%A8%E8%87%AA%E5%AE%9A%E4%B9%89%60setup.xml%60%E4%B8%AD%E5%BC%95%E7%94%A8%E7%9A%84CSS%E8%B5%84%E6%BA%90%E3%80%82

   若只需修改http://coastwatch.pfeg.noaa.gov/erddap/download/setup.html#setup.xml%E5%92%8Chttp://coastwatch.pfeg.noaa.gov/erddap/download/setupDatasetsXml.html%EF%BC%8C%E5%8F%AF%E5%8D%95%E7%8B%AC%E6%8C%82%E8%BD%BD%E5%AE%83%E4%BB%AC%EF%BC%9A

   bash
   docker run \
       -p 8080:8080 \
       -v /path/to/your/setup.xml:/usr/local/tomcat/content/erddap/setup.xml \
       -v /path/to/your/datasets.xml:/usr/local/tomcat/content/erddap/datasets.xml \
       ... \
       axiom/docker-erddap
   

   若挂载setup.xml文件，请确保设置<bigParentDirectory>/erddapData/</bigParentDirectory>

2. 使用环境变量配置

   从2.14版本开始，可通过环境变量配置ERDDAP的setup.xml。详情参见https://coastwatch.pfeg.noaa.gov/erddap/download/setup.html#setupEnvironmentVariables%E3%80%82%E8%BF%99%E7%A7%8D%E6%96%B9%E5%BC%8F%E6%97%A0%E9%9C%80%E6%8C%82%E8%BD%BD%E8%87%AA%E5%AE%9A%E4%B9%89%60setup.xml%60%EF%BC%8C%E9%9D%9E%E5%B8%B8%E5%AE%9E%E7%94%A8%E3%80%82%E5%BB%BA%E8%AE%AE%E8%AE%BE%E7%BD%AE%E4%BB%A5%E4%B8%8BERDDAP%E9%85%8D%E7%BD%AE%E9%80%89%E9%A1%B9%EF%BC%9A

   • ERDDAP_baseUrl
   • ERDDAP_baseHttpsUrl
   • ERDDAP_flagKeyKey
   • ERDDAP_emailEverythingTo
   • ERDDAP_emailFromAddress
   • ERDDAP_emailUserName
   • ERDDAP_emailPassword
   • ERDDAP_emailSmtpHost
   • ERDDAP_emailSmtpPort
   • ERDDAP_adminInstitution
   • ERDDAP_adminInstitutionUrl
   • ERDDAP_adminIndividualName
   • ERDDAP_adminPosition
   • ERDDAP_adminPhone
   • ERDDAP_adminAddress
   • ERDDAP_adminCity
   • ERDDAP_adminStateOrProvince
   • ERDDAP_adminPostalCode
   • ERDDAP_adminCountry
   • ERDDAP_adminEmail

   示例：

   bash
   docker run \
       -p 8080:8080 \
       -e ERDDAP_baseURL="http://localhost:8080" \
       -e ERDDAP_adminEmail="set_via_container_env@example.com" \
       docker.xuanyuan.run/axiom/docker-erddap
   

   根据容器环境，可能会传入与资源相关的环境变量。若资源名称以ERDDAP开头，可能与ERDDAP_*配置变量冲突。

3. 使用shell脚本配置

   可挂载名为config.sh的文件至${CATALINA_HOME}/bin/config.sh，该文件可设置任何ERDDAP配置环境变量。容器提供的setenv.sh会 sourcing 此文件，并导出所有变量供ERDDAP使用。这些变量优先级高于运行容器时指定的环境变量。

   bash
   docker run \
       -p 8080:8080 \
       -e ERDDAP_adminEmail="overridden_by_config_file@example.com" \
       -v /path/to/your/config.sh:/usr/local/tomcat/bin/config.sh \
       ... \
       axiom/docker-erddap
   

   其中config.sh包含ERDDAP环境配置变量：

   sh
   ERDDAP_adminEmail="this_is_used@example.com"
   ERDDAP_bigParentDirectory="/erddapData/"
   ERDDAP_baseUrl="http://localhost:8080"
   ERDDAP_baseHttpsUrl="https://localhost:8443"
   ERDDAP_flagKeyKey="73976bb0-9cd4-11e3-a5e2-0800200c9a66"
   
   ERDDAP_emailEverythingTo="nobody@example.com"
   ERDDAP_emailDailyReportTo="nobody@example.com"
   ERDDAP_emailFromAddress="nothing@example.com"
   ERDDAP_emailUserName=""
   ERDDAP_emailPassword=""
   ERDDAP_emailProperties=""
   ERDDAP_emailSmtpHost=""
   ERDDAP_emailSmtpPort=""
   
   ERDDAP_adminInstitution="Axiom Docker Install"
   ERDDAP_adminInstitutionUrl="https://github.com/axiom-data-science/docker-erddap"
   ERDDAP_adminIndividualName="Axiom Docker Install"
   ERDDAP_adminPosition="Software Engineer"
   ERDDAP_adminPhone="555-555-5555"
   ERDDAP_adminAddress="123 Irrelevant St."
   ERDDAP_adminCity="Nowhere"
   ERDDAP_adminStateOrProvince="AK"
   ERDDAP_adminPostalCode="99504"
   ERDDAP_adminCountry="USA"
   

4. 挂载自定义bigParentDirectory：

   bash
   docker run \
       -p 8080:8080 \
       -v /path/to/your/erddap/bigParentDirectory:/erddapData \
       ... \
       axiom/docker-erddap
   

   强烈建议此操作，否则容器重启后日志、缓存等数据将丢失。

5. 指定堆内存分配（使用Java的Xms和Xmx）：

   bash
   docker run \
       -p 8080:8080 \
       --env ERDDAP_MEMORY=10G \
       ... \
       axiom/docker-erddap
   

   也可显式设置ERDDAP_MIN_MEMORY和ERDDAP_MAX_MEMORY（分别对应Xms和Xmx），但最佳实践是将两者设为相同值，避免运行时堆调整的性能开销。

   bash
   docker run \
       -p 8080:8080 \
       --env ERDDAP_MIN_MEMORY=8G --env ERDDAP_MAX_MEMORY=8G \
       ... \
       axiom/docker-erddap
   

   或者，设置ERDDAP_MAX_RAM_PERCENTAGE将Java堆大小限制为容器可用内存的百分比（设置JVM选项-XX:MaxRAMPercentage）。例如，限制容器内存为10GB，允许Java堆使用其中90%：

   bash
   docker run \
       -p 8080:8080 \
       --memory 10g \
       --env ERDDAP_MAX_RAM_PERCENTAGE=90 \
       ... \
       axiom/docker-erddap
   

datasets.d模式 - 实验性

通常ERDDAP通过单个datasets.xml配置文件描述所有数据集及全局配置，详见https://coastwatch.pfeg.noaa.gov/erddap/download/setupDatasetsXml.html%E3%80%82

docker-erddap提供datasets.d模式，可将datasets.xml的dataset元素存储在datasets.d目录下的多个.xml文件中。启动时，会扫描/datasets.d目录中所有以.xml结尾的文件，按路径排序后拼接为生成的datasets.xml文件（包含空的<erddapDatasets />元素）。

此模式下，datasets.xml的顶层元素（如<cacheMinutes>、<standardLicense>等）可通过ERDDAP_DATASET_*环境变量配置，与ERDDAP_*环境变量影响setup.xml的方式类似（详见https://coastwatch.pfeg.noaa.gov/erddap/download/setup.html#setupEnvironmentVariables%EF%BC%89%E3%80%82%E4%BE%8B%E5%A6%82%EF%BC%8C%E8%AE%BE%E7%BD%AE%60standardLicense%60%EF%BC%9A

bash
docker run -d -v $(pwd)/datasets.d:/datasets.d:ro \
  -e ERDDAP_DATASETS_standardLicense="<h1>Use as you wish</h1>" \
  --name erddap \
  docker.xuanyuan.run/axiom/docker-erddap

注意：此模式下，ERDDAP内容目录（/usr/local/tomcat/content/erddap）中的datasets.xml会被生成的文件替换。若原datasets.xml存在且无备份，会创建备份。

因此，使用datasets.d模式时无需挂载ERDDAP内容目录，数据集配置由datasets.d提供，顶层datasets.xml配置通过ERDDAP_DATASETS_*环境变量完成。

datasets.d模式运行示例，参见examples中的docker-compose配置。

datasets.xml的生成由脚本datasets.d.sh处理，可输出到stdout，支持容器外测试：

shell
ERDDAP_DATASETS_cacheMinutes=20 ./datasets.d.sh -d examples/datasets.d

从v2.27.0版本开始，生成的datasets.xml文件中的环境变量会通过envsubst替换。

datasets.d模式下优雅移除数据集

ERDDAP有https://coastwatch.pfeg.noaa.gov/erddap/download/setupDatasetsXml.html#active%E7%A7%BB%E9%99%A4%E5%B7%B2%E6%9C%8D%E5%8A%A1%E7%9A%84%E6%95%B0%E6%8D%AE%E9%9B%86%EF%BC%9A

• 编辑数据集的datasets.xml元素，设置active属性为false。
• 等待ERDDAP下次更新检测到非活动数据集（或设置重载标志立即检测）。
• ERDDAP移除数据集后，删除该数据集的datasets.xml元素（或保留active="false"）。

若未遵循此流程，会导致ERDDAP配置中出现“孤立”数据集。

要使datasets.d模式自动检测已移除的数据集（运行中的ERDDAP配置包含但新生成的datasets.xml中不存在的数据集ID），可设置环境变量DATASETSD_MARK_REMOVED_DATASETS_INACTIVE=1，或手动运行./datasets.d.sh时传递-i标志。此行为未来可能成为默认。

初始化脚本（/init.d）- 实验性

可在/init.d目录中放置可执行文件或shell脚本，容器启动时会运行这些脚本（必须是幂等的）。功能类似postgres Docker镜像的https://github.com/docker-library/docs/blob/master/postgres/README.md#initialization-scripts%E3%80%82

示例：

shell
# 从范围请求排除中移除.hdf和.nc文件
mkdir -p init.d
cat << 'EOF' > init.d/10-remove-hdf-nc-range-request-exclusion.sh
sed -i 's/.hdf, .nc, //g' ${CATALINA_HOME}/webapps/erddap/WEB-INF/classes/gov/noaa/pfel/erddap/util/messages.xml
EOF

chmod +x init.d/10-remove-hdf-nc-range-request-exclusion.sh

docker run -d -p 8080:8080 -v $(pwd)/init.d:/init.d:ro --name erddap docker.xuanyuan.run/axiom/docker-erddap

日志整合 - 实验性

ERDDAP将日志写入bigParentDirectory下的logs/log.txt，格式不标准且不易解析，也无时间戳。使用此docker镜像时，可运行rsyslog sidecar容器增强日志体验：

• 整合ERDDAP和Tomcat的日志（应用日志和访问日志）。
• 为ERDDAP日志添加时间戳。
• 过滤部分ERDDAP日志“噪音”（主观）。
• 将整合和过滤后的日志输出到stdout。

rsyslog sidecar容器运行示例，参见examples中的docker-compose配置。相关rsyslog配置文件位于rsyslog。需将ERDDAP的bigParentDirectory和Tomcat日志目录通过bind mount挂载到主机，或使用Docker命名卷挂载到ERDDAP和rsyslog容器。

整合日志示例：

log
erddap-rsyslogd_1  | [TOMCAT] 08-Jul-2022T04:44:14.004 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["http-nio-8080"]
erddap-rsyslogd_1  | [TOMCAT] 08-Jul-2022T04:44:14.011 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in 3582 ms
...
erddap-rsyslogd_1  | [ERDDAP] 2022-07-08T04:44:19Z Major LoadDatasets Time Series: MLD    Datasets Loaded            Requests (median times in ms)              Number of Threads      MB    Open
erddap-rsyslogd_1  |   timestamp                    time   nTry nFail nTotal  nSuccess (median) nFail (median) memFail tooMany  tomWait inotify other  inUse  Files
erddap-rsyslogd_1  | ----------------------------  -----   -----------------  ------------------------------------------------  ---------------------  -----  -----
erddap-rsyslogd_1  |   2022-07-08T04:44:18+00:00      1s      1     0      2         1 (     8)     0 (     0)       0       0       10       1    17     44     0%
...
erddap-rsyslogd_1  | [ACCESS] 127.0.0.1 - - [08/Jul/202