Skip to content

ADR-0005 — Official image, plugins at build time, ephemeral data dir, security/ in the database

Date: 2026-09-01 · Status: accepted (validated by prototype 2)

Context

In a cluster, a GeoServer data dir shared or persisted per pod creates divergence between the disk and the database (prior operational experience: styles, GWC, master key generated per pod → undecipherable store passwords). The image must be reproducible and download nothing at startup.

Decision

  1. Base = official image docker.osgeo.org/geoserver:<version>; stable extensions and community modules downloaded at build time (the image's install-extensions.sh + OSGeo Nexus), in-house plugin compiled in a Maven stage. Nothing at runtime.
  2. Data dir = emptyDir regenerated at every startup by bootstrap-datadir.sh from environment variables; JDBCConfig and JDBCStore via JNDI; initdb/import inferred from the presence of the tables.
  3. security/ is carried in the database by JDBCStore (it is not in ignoreDirs): master key, keystore, users and roles are imported at first boot then re-read by all replicas. Verified: after pod replacement, the admin account from the Secret remains valid and the default password remains rejected.
  4. JNDI resources in an overridden server.xml generated from the image's template (the image's <Context override="true"> ignores conf/context.xml).

Rejected alternatives

Alternative Why rejected
Shared PVC (RWX) for the data dir Disk/database divergence experienced; dependency on RWX storage
Bare tomcat + war Reinvents startup, probes, hardening, admin management
Kartoza image Opinionated, lags behind 3.0
INSTALL_EXTENSIONS=true at runtime Downloads at every boot, non-reproducible, network-dependent
security/ seeded from a Secret at every boot Unnecessary since JDBCStore carries it; would remain an option if JDBCStore were dropped

Consequences

  • Any configuration change goes through the database (plugin, ADR-0006) or through the image; never through a pod's disk.
  • Admin password rotation: GEOSERVER_ADMIN_PASSWORD is only applied at the first boot (import); after that, the change is made in GeoServer (UI or security API) — recorded in the risks.
  • The overridden server.xml must be regenerated at every image version upgrade (gen-server-xml.sh).