geosolutionsit/geoserver

docker-geoserver

在Docker中运行GeoServer。基于官方Tomcat Docker镜像，具体包括：

• Tomcat 9
• JDK 11（Eclipse Temurin）
• Ubuntu Jammy（22.04 LTS）

!当前构建 diagram

核心功能特性

• 支持从主机挂载数据目录以实现持久化。
• 通过环境变量设置ADMIN_PASSWORD。
• 灵活挂载其他路径实现持久化。
• 从本地/远程URL构建GeoServer Web应用（WAR）文件。
• 运行时使用自定义GeoServer WAR文件。
• 提供运行时重载GeoServer的辅助脚本。
• 提供运行时测试插件的辅助脚本。
• CORS（跨域资源共享）支持。
• 构建时指定自定义字体。

重要说明

大多数从主机挂载到容器的路径（如$GEOSERVER_LOG_DIR、$CATALINA_BASE、$GEOWEBCACHE_CACHE_DIR、$GEOWEBCACHE_CONFIG_DIR、$NETCDF_DATA_DIR、$GRIB_CACHE_DIR、$GEOSERVER_DATA_DIR）应归属于GeoServer运行用户的UID，目前该UID为1000。这些路径需递归设置该UID的所有权。更多信息见权限调整。

如何运行

bash
docker run --name gs -p 8080:8080 geosolutionsit/geoserver

或使用默认GeoServer数据目录实现数据持久化（以下示例中GEOSERVER_DATA_DIR指向/var/geoserver/datadir）：

bash
docker run --rm --name gs -p 8080:8080 geosolutionsit/geoserver

将数据目录保存到本地作为初始数据目录：

bash
docker cp gs:/var/geoserver/datadir ./datadir
docker stop gs

使用保存的数据目录启动带数据持久化的GeoServer：

bash
docker run -v ./datadir:/var/geoserver/datadir --name gs -p 8080:8080 geosolutionsit/geoserver

带数据持久化启动GeoServer

启动带数据持久化的GeoServer并修改管理员密码：

bash
docker run -e ADMIN_PASSWORD=securepassword -v datadir:/var/geoserver/datadir --name gs -p 8080:8080 geosolutionsit/geoserver

打开浏览器访问http://localhost:8080/geoserver。GeoServer Web界面将显示，可使用管理员用户admin和密码geoserver登录。

环境变量

运行时可使用以下环境变量：

路径相关环境变量

• GEOSERVER_LOG_DIR：自定义日志存放路径
• GEOSERVER_DATA_DIR：自定义GeoServer数据目录路径
• GEOWEBCACHE_CONFIG_DIR：自定义GeoServer缓存配置目录路径
• GEOWEBCACHE_CACHE_DIR：自定义GeoServer缓存目录路径
• NETCDF_DATA_DIR：自定义GeoServer NETCDF数据目录路径
• GRIB_CACHE_DIR：自定义GeoServer GRIB缓存目录路径

这些变量可关联到外部卷，以在Docker Compose等场景中持久化数据。

其他环境变量

• CATALINA_OPTS：自定义容器的CATALINA_OPTS参数
• EXTRA_GEOSERVER_OPTS：追加到CATALINA_OPTS的额外参数
• JAIEXT_ENABLED：默认true，详情见JAI扩展文档
• APP_LOCATION：重命名GeoServer Web应用目录（默认为geoserver）

Java堆大小调整环境变量

• INITIAL_MEMORY：默认2G（对应-Xms）
• MAXIMUM_MEMORY：默认4G（对应-Xmx）

CORS变量

可通过环境变量配置CORS头（同时支持构建参数）：

• CORS_ENABLED：设为true启用CORS支持，以下变量用于自定义CORS配置
• CORS_ALLOWED_ORIGINS：默认*（允许的源）
• CORS_ALLOWED_METHODS：默认GET,POST,PUT,DELETE,HEAD,OPTIONS（允许的方法）
• CORS_ALLOWED_HEADERS：默认*（允许的请求头）
• CORS_ALLOW_CREDENTIALS：默认false（是否允许凭证）。设为true时，CORS_ALLOWED_ORIGINS必须指定具体源（不能为*）

使用WAR文件和插件构建

以下示例演示如何构建仅包含GeoServer WAR的Docker镜像，然后在运行时添加插件：

bash
docker build -t geoserver:test-2.19.1 \
--build-arg GIT_HASH=`git show -s --format=%H` \
--build-arg GEOSERVER_WEBAPP_SRC=https://sourceforge.net/projects/geoserver/files/GeoServer/2.19.1/geoserver-2.19.1-war.zip/download  .

docker run \
--env PLUGIN_DYNAMIC_URLS="http://sourceforge.net/projects/geoserver/files/GeoServer/2.19.1/extensions/geoserver-2.19.1-control-flow-plugin.zip \
http://sourceforge.net/projects/geoserver/files/GeoServer/2.19.1/extensions/geoserver-2.19.1-libjpeg-turbo-plugin.zip" \
--rm --name gs -p 8080:8080 geoserver:test-2.19.1

使用Docker Compose运行GeoServer

Docker Compose是简化多容器管理的工具。安装说明见Docker文档（Docker Desktop已预装，无需额外安装）。使用前需正确配置docker-compose.yml文件。

外部化GeoServer容器的数据目录

要持久化并外部访问GeoServer容器数据，需在容器中设置环境变量，并关联到外部卷。步骤如下：

1. 在docker-compose.yml同目录创建.env文件，定义环境变量：

bash
GEOSERVER_LOG_DIR=/var/geoserver/logs
GEOSERVER_DATA_DIR=/var/geoserver/datadir
GEOWEBCACHE_CONFIG_DIR=/var/geoserver/datadir/gwc
GEOWEBCACHE_CACHE_DIR=/var/geoserver/gwc_cache_dir
NETCDF_DATA_DIR=/var/geoserver/netcdf_data_dir
GRIB_CACHE_DIR=/var/geoserver/grib_cache_dir

更多.env文件说明见https://github.com/compose-spec/compose-spec/blob/master/spec.md#env_file%E3%80%82

2. 在docker-compose.yml中配置环境变量和卷：

yml
services:
  geoserver:
    build:
      context: .
      dockerfile: ./Dockerfile
    environment:
      - GEOSERVER_LOG_DIR=${GEOSERVER_LOG_DIR}
      - GEOSERVER_DATA_DIR=${GEOSERVER_DATA_DIR}
      - GEOWEBCACHE_CONFIG_DIR=${GEOWEBCACHE_CONFIG_DIR}
      - GEOWEBCACHE_CACHE_DIR=${GEOWEBCACHE_CACHE_DIR}
      - NETCDF_DATA_DIR=${NETCDF_DATA_DIR}
      - GRIB_CACHE_DIR=${GRIB_CACHE_DIR}
    volumes:
      - logs:${GEOSERVER_LOG_DIR}
      - datadir:${GEOSERVER_DATA_DIR}
      - gwc_config:${GEOWEBCACHE_CONFIG_DIR}
      - gwc:${GEOWEBCACHE_CACHE_DIR}
      - netcfd:${NETCDF_DATA_DIR}
      - grib_cache:${GRIB_CACHE_DIR}
volumes:
  pg_data:
  logs:
  datadir:
  gwc_config:
  gwc:
  netcfd:
  grib_cache:

可设置环境变量默认值（未在.env中定义时使用）：

yml
environment:
  - GEOSERVER_LOG_DIR=${GEOSERVER_LOG_DIR:-/var/geoserver/logs}

卷配置详情见Docker卷文档。

使用自定义WAR文件构建GeoServer容器

默认通过URL构建GeoServer容器，可修改docker-compose.yml使用本地WAR文件：

yml
geoserver:
  build:
    context: .
    dockerfile: ./Dockerfile
    args:
      GEOSERVER_WEBAPP_SRC: "/host/directory/alternativegeoserver.war"
  container_name: geoserver 

支持URL和本地文件，详情见Docker ADD文档。

在Docker Compose运行时使用自定义WAR文件

• GeoServer服务配置示例：

yml
geoserver:
  image: geosolutionsit/geoserver:2.23.0  # 初始指定镜像避免Docker报错
  volumes:
    - /path/custom-war:/usr/local/tomcat/webapps/geoserver  # 挂载自定义WAR（需解压）
  environment:
    - EXTRA_GEOSERVER_OPTS="-DGEOSERVER_CSRF_WHITELIST=example.org -DENABLE_JSONP=true"
  container_name: geoserver
  depends_on:
    postgres:
      condition: service_healthy
  ports:
    - 8080
  networks:
    - geoserver-network

调整绑定挂载的权限

1. 确定用户ID：通过docker exec进入容器，运行id命令获取GeoServer运行用户ID（默认为1000）。
2. 调整权限：在主机上使用chown设置目录所有者为该ID，chmod设置权限。

示例（假设用户ID为1000，目录为/path/custom-war）：

bash
sudo chown -R 1000:1000 /path/custom-war
sudo chmod -R 755 /path/custom-war

自定义字体

构建时通过CUSTOM_FONTS参数指定主机字体路径，构建过程中会复制到镜像：

bash
docker build --build-arg CUSTOM_FONTS=/path/to/host/fonts -t geoserver:with-fonts .

从容器外部访问GeoServer PostgreSQL服务器

容器间通过Docker Compose创建的网络通信。要从主机访问容器，需通过ports关键字暴露端口：

yml
ports:
  - "bind_address:hostport:containerport"  # 需用引号括起，避免YAML浮点型解析冲突

主机端口与容器端口可不同，避免端口冲突。建议显式指定bind_address以避免安全问题。

示例docker-compose.yml配置：

yml
services:
  postgres:
    image: postgis/postgis
    container_name: postgres
    ports:
      - "5432:5432"  # 暴露PostgreSQL端口
  geoserver:
    container_name: geoserver
    ports:
      - "8080:8080"  # 暴露GeoServer端口

容器启停命令

• 首次启动/应用配置变更：

bash
docker compose up

• 启动已创建容器：

bash
docker compose start

输出示例：

Starting postgres ... done
Starting geoserver ... done
Starting proxy ... done

• 停止容器：

bash
docker compose stop

输出示例：

Stopping proxy ... done
Stopping geoserver ... done
Stopping postgres  ... done

• 重置容器（保留外部卷）：

bash
docker compose down

使用自定义geoserver.war构建Docker镜像

确保./geoserver.war存在，执行以下命令：

bash
docker build --build-arg GEOSERVER_WEBAPP_SRC="./geoserver.war" -t geoserver:test .

构建参数

可通过构建参数自定义镜像：

• PLUG_IN_URLS：空格分隔的GeoServer插件URL列表（支持扩展和社区插件）
• GEOSERVER_DATA_DIR_SRC：自定义数据目录（本地zip、目录或远程URL，见ADD文档）
• GEOSERVER_WEBAPP_SRC：自定义Web应用（本地zip、目录或远程URL）。从GeoServer官网下载时，URL需以/download结尾（见官方下载页）

构建示例

bash
# 使用本地WAR构建
docker build -t geoserver:test . --build-arg GEOSERVER_WEBAPP_SRC="./resources/geoserver/geoserver.war"

# 构建包含自定义数据目录的镜像
docker build -t geoserver:test . --build-arg GEOSERVER_WEBAPP_SRC="./resources/geoserver/geoserver.war" --build-arg GEOSERVER_DATA_DIR_SRC="./resources/geoserver-datadir/"

# 构建带插件的稳定版镜像
docker build -t geoserver:luca-test-2.19.1 --build-arg GEOSERVER_WEBAPP_SRC="https://sourceforge.net/projects/geoserver/files/GeoServer/2.19.1/geoserver-2.19.1-war.zip/download" --build-arg PLUG_IN_URLS="http://sourceforge.net/projects/geoserver/files/GeoServer/2.19.1/extensions/geoserver-2.19.1-control-flow-plugin.zip http://sourceforge.net/projects/geoserver/files/GeoServer/2.19.1/extensions/geoserver-2.19.1-libjpeg-turbo-plugin.zip" .

GeoServer REST重载

运行中容器可通过以下命令重载GeoServer：

bash
docker exec -it <容器名称> bash /usr/local/bin/geoserver-rest-reload.sh

在运行中容器上测试插件

bash
docker exec -it <容器名称> bash -c 'geoserver-plugin-download.sh $CATALINA_BASE/webapps/$APP_LOCATION/WEB-INF/lib <空格分隔的插件URL列表>'

Docker Hub构建流程及辅助脚本

hooks目录下提供Docker Hub构建相关脚本。hooks/build脚本使用以下环境变量定义GeoServer版本：

bash
export MAINT_VERSION="2.17.3 2.17.2 2.17.1"
export MIDDLE_STABLE="18"
export NIGHTLY_MAINT_VERSION="2.17.x"
export NIGHTLY_MASTER_VERSION="master foobar"
export NIGHTLY_STABLE_VERSION="2.18.x"
export STABLE_VERSION="2.18.1 2.18.0"

注：foobar为测试用无效版本，用于验证构建失败逻辑；MIDDLE_STABLE用于脚本逻辑，需设为最新稳定版次要版本号。可通过test_hooks.sh脚本本地测试构建钩子。

custom_build.sh脚本使用

运行脚本不带参数可显示帮助：

bash
./custom_build.sh
Usage: ./custom_build.sh [docker image tag] [geoserver version] [geoserver master version] [datadir| nodatadir] [pull|no pull];

参数说明：

• [docker image tag]：镜像标签
• [geoserver version]：GeoServer版本（设为master获取最新版）
• [geoserver master version]：主版本号（如使用发布版，设为发布号）
• [datadir|nodatadir]：nodatadir表示不将数据目录打包进镜像
• [pull|no pull]：pull表示构建时拉取远程镜像，no pull使用本地镜像

使用示例

bash
./custom_build.sh my-docker-tag 2.18.x 2.18.x nodatadir no_pull

GIT_HASH信息

构建时添加GIT_HASH参数可嵌入Git哈希：

bash
docker build --build-