ADR-0006 — Reproducible configuration via a Java plugin (GeoServerInitializer), not via REST¶
Date: 2026-09-01 · Status: accepted
Context¶
Prior operational experience: on a GeoServer with a database-backed catalog and several replicas, changes made through the REST API (or in the UI) turned out to be non-persisted or non-propagated (in-memory configuration of a single replica, GWC files not written, objects recreated at restart). Post-startup scripts (Jobs calling REST) are fragile: ordering, races, dependency on service availability.
Decision¶
All reproducible configuration (workspaces, stores, layers, styles, GWC
settings, services) is created by a Java plugin embedded in the image,
implementing GeoServerInitializer (called after the catalog is loaded),
idempotent (looks up before creating, updates if different), driven by
environment variables, and logging what it does. Datastores reference
JNDI names, never URLs.
REST and the UI remain reserved for one-off manual operations (diagnostics, cache purge, tests) — never as a source of truth.
Rejected alternatives¶
| Alternative | Why rejected |
|---|---|
| REST Jobs after deployment | Non-persistence and races experienced; depends on the service being up |
| Direct SQL into the JDBCConfig tables | Internal format (serialized XML), unsupported, silently ignored |
| Versioned and copied data dir | Contradicts "the database is the single source of truth"; one-time import |
Consequences¶
- Adding a layer = code + image build (or, for continuously produced data, an ingestion service using the catalog API — sub-project 5).
- The plugin is the natural home for the configuration of sub-projects 3 to 8.
- GeoServer developers must know the
Catalog/CatalogBuilderAPI.