Skip to content

A single-page reference of the configuration keys read by the core modules and the reference webapp. - #248

Merged
jampukka merged 1 commit into
nlsfi:mainfrom
jampukka:docs-config-reference-192
Oct 22, 2026
Merged

jampukka merged 1 commit into
nlsfi:mainfrom
jampukka:docs-config-reference-192

Conversation

@jampukka

Copy link
Copy Markdown
Collaborator

Should fix #192. A single-page reference of the configuration keys read by the core modules and the reference webapp.

  • docs/overview/configuration.md
    • Every key read by src/ and webapp-jakarta/, with default, whether it is required, and a short description, grouped as the config is: service, collections, properties and columns, databases
    • Describes what the code actually does, including the traps: an empty value is not always "unset", an unknown output format is silently skipped, the metadata path must be absolute
    • "Not read by the code" lists keys that appear in example files or older docs but that nothing reads
    • Community modules (src-community/: tiles, smile, esbulk) are not covered; their READMEs are the reference
    • PostGIS joins are marked experimental
  • Keeping it current
    • CONTRIBUTING.md and the changelog say a PR that changes a key is expected to update the page

Few functional changes noticed when documenting this stuff:

  • servers=a, b is now trimmed like every other list key; before, it failed startup with a NullPointerException (one line in HakunaConfigParser.readServers, with a test)
  • The PostGIS source no longer reads collections.<id>.id.alias, geometry.alias and properties.<p>.alias. They were a not-working and unfinished idea (properties.<p>.alias made startup fail with a NullPointerException). The keys are now ignored; ColumnAlias is replaced by a plain set of column names, as in the GPKG source
  • docker/cfg: the example configs no longer set collections.<id>.writeNulls and geometry.storageSrid, which nothing reads. addresses_view declares its storage SRID with srid.storage instead

…webapp

docs/overview/configuration.md lists every configuration key read by src/
and webapp-jakarta/ with its default, and the traps (blank values, trimming,
silently skipped formats). Community modules are not covered.

CONTRIBUTING.md and the changelog say a PR that changes a key is expected
to update the page.

Related changes found while checking the keys against the code:
- servers=a, b is trimmed like every other list key (it used to fail
  startup with a NullPointerException)
- the PostGIS source no longer reads id.alias, geometry.alias and
  properties.<p>.alias. They were a not-working and unfinished idea:
  properties.<p>.alias made startup fail with a NullPointerException
- the example configs no longer set writeNulls and geometry.storageSrid,
  which nothing reads; addresses_view declares its storage SRID with
  srid.storage
@jampukka
jampukka merged commit 162a694 into nlsfi:main Oct 22, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a new documentation page of all supported Hakunapi configuration options in a single place

1 participant