docs: add Configuration Reference to Quick Reference section

[jamesfredley]

Summary

• Add a comprehensive Application Properties reference page under ref/Configuration/ in the Quick Reference section of the documentation
• Lists ~160 Grails-specific application.yml configuration keys across 21 categories with descriptions and default values
• All external links use doc variables ({springBootVersion}, {hibernate5Reference}) for version-safe URLs

Sections

Core Framework (16 sections):
Core Properties, Web & Controllers, CORS, Views & GSP, Content Negotiation & MIME Types, Data Binding, Internationalization, Static Resources, URL Mappings, Scaffolding, Development & Reloading, Events, JSON & Converters, GORM (+ Multi-Tenancy), DataSource, Hibernate

Bundled Plugins (5 sections):
Database Migration Plugin, Cache Plugin, Asset Pipeline Plugin, Spring Security Plugin, MongoDB GORM Plugin

Sources

Default values verified against source code:

• grails.config.Settings (grails-core) - 40+ core framework constants
• org.grails.datastore.mapping.config.Settings (grails-datastore-core) - GORM constants
• DatabaseMigrationGrailsPlugin + DatabaseMigrationCommand - migration plugin keys
• DataBindingConfigurationProperties - data binding defaults
• DefaultSecurityConfig.groovy (grails-spring-security) - all Spring Security defaults
• AssetPipelineGrailsPlugin + AssetPipelineExtension (wondrify/asset-pipeline) - asset pipeline keys
• MongoSettings (grails-data-mongodb) - MongoDB GORM keys
• Grails Forge feature classes (config.put() calls) - programmatic config generation
• Profile skeleton application.yml files - web/rest-api/base profile defaults

[jamesfredley]

A decent start. There is a gray area in terms of what is included and what is not, more feels better, but I am not apposed to cutting things that are rarely used.

[jdaugherty]

so we aren't going to try to make a technical change to generate this?

[jamesfredley]

I thought about it, but it is spread across so many different locations and some external repos if we leave asset-pipeline, etc. So I think for this PR having a static adoc will allow it to move forward and it could be potentially automated in some way in the future.

[Copilot]

Pull request overview

This PR adds a comprehensive Application Properties reference page to the Quick Reference section of the Grails documentation. The new file grails-doc/src/en/ref/Configuration/Application Properties.adoc provides a centralized reference for approximately 160 Grails-specific configuration keys organized into 21 categories covering core framework settings and bundled plugins.

Changes:

• Added comprehensive configuration reference documentation covering core Grails framework properties, GORM settings, and major bundled plugins (Database Migration, Cache, Asset Pipeline, Spring Security, MongoDB GORM)
• Uses AsciiDoc table format with Property/Description/Default columns for consistent presentation
• Properly uses doc variables ({springBootVersion}, {hibernate5Reference}) for version-safe external links

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jdaugherty]

@jamesfredley I strongly disagree here. A static doc is just ripe for getting out of date. We need an actual technical solution to this problem so it can be generated as needed. Why not have an app that starts up and dump the config in bootstrap / stop the app? This could be an easy task and would make sure the defaults are always properly reflected.

[jamesfredley]

I think this is a POC and potentially a placeholder due to the following.

Config is scattered across 4 different mechanisms with no unified registry:

1. Settings interfaces with string constants - grails.config.Settings (~45 keys) and org.grails.datastore.mapping.config.Settings (GORM keys). These are plain String constants with Javadoc. Discoverable via reflection at build time.
2. @ConfigurationProperties classes - Only ~5 in grails-core (grails.cors, grails.cache, grails.views.markup, grails.views.json, grails.databinding). These ARE Spring Boot's standard mechanism and would show up in metadata - but there are no spring-configuration-metadata.json files anywhere in the repo.
3. Hard-coded string literals - Many config keys are just raw strings like config.getProperty('grails.some.key', Boolean, true) scattered throughout the codebase. No constants, no metadata, no discovery mechanism.
4. External plugins - Spring Security, Asset Pipeline, etc - each defines their own config in their own repos. A single app startup can only discover keys for plugins it actually loads.

"start an app and dump config in bootstrap"

• No complete enumeration API - There's no grailsApplication.getAllKnownConfigKeys(). The Settings interfaces give you maybe 30% of the keys. The rest are string literals buried in code.
• Plugin configs are external repos - Spring Security defaults live in grails-spring-security, not grails-core. Asset Pipeline lives in a different GitHub org (wondrify). The app will need ALL plugins loaded.
• Runtime vs. declared - At runtime you can dump what's set easily but would need a lot of code to iterate through everything and dump it
• No spring-configuration-metadata.json - Spring Boot's standard solution for this (annotation processor generating metadata) has never been set up for Grails. That's the gap.

What could be done, likely for Grails 8

1. Add spring-boot-configuration-processor to grails modules that use @ConfigurationProperties - this auto-generates spring-configuration-metadata.json at compile time
2. Migrate more config to @ConfigurationProperties instead of raw string lookups - a big refactor
3. Write a Gradle task that reflects over the Settings interfaces + collects @ConfigurationProperties metadata + generates the adoc
   But that's a big refactoring effort

[jdaugherty]

@jamesfredley I don't believe this is true. All of this gets added as a property source on the environment. we can merge any property sources so they're flattened and then dump them. We could even enable the actuators in spring boot to do this if we wanted. I'll take a pass at adding a command to do this as a proof of concept and we can compare.

[jdaugherty]

@jamesfredley checkout https://github.com/apache/grails-core/tree/configuration-command and see if this works. Right now it generates the asciidoc from the command, but we could just as easily generate json, command line readable, etc.

Assuming this looks correct (tests seem to pass), then I think we can go with this solution instead, yes?

[jamesfredley]

I would love for it to be automated. Here is a comparison of the static doc and automated process.

config-command-output.html
static-doc-output.html

[jamesfredley]

config-command-actual-output.html - the full output turned into similar html with some values redacted

[jdaugherty]

I see 4 issues based on these diffs:

1. the code I pushed to pull the properties needs to use the environment instead of application.config
2. documenting external configuration values that aren't in grails-core
3. gorm has different settings depending on the library imported
4. defaults in code that aren't really in configuration

I've pushed a fix for the first. For plugins like asset-pipeline, we should not be adding this to grails-core docs. They can change at any time. For cases where the defaults vary (i.e. mongodb vs hibernate have different values), this is the strongest indicator we should not be publishing a static document. For the remaining issue, technically, it's "not" configured but it's using a default.

If we take the plugin.yml fix, we can check in plugin configuration and remove the defaults from the plugin code. Then they'll show and be maintained. We can even use your initial effort to figure out what to check in, where.

I am okay with compromising here though. Use the configuration command to get the configured values, and then make it aware of the defaults (hard code them to start). Then we can gradually move the defaults in the command to actual config and iterate. But to solve the dynamic differences, we'll have to permute your document.

We also need to figure out if longer term we want to allow the defaults in code instead of plugin configuration. If we do, we'll need a standard way to do this so we can parse the classpath to find them. This is probably out of scope of the first pass. But we should consider using codenarc to enforce whatever we decide here - if we force configuration files, it should enforce that default is specified in the plugin config instead of inline in the code.

[jdaugherty]

some other examples where we have different defaults: grails-layout vs grails-sitemesh. This is why I think it's a must we handle this programmatically.

[jamesfredley]

If you can make it automated, without losing the depth of information, specifically the Description and Default, I am all for it. Keeping it similar to https://docs.spring.io/spring-boot/appendix/application-properties/index.html. But I would hate to lose all the clarity. It took OpenCode ~15 minutes to generate this and it would be faster going forward, but we can't automate using AI since it is non-deterministic.

[jdaugherty]

I'd suggest we move this to draft status then. I'm a -1 because of the burden of keeping this up to date when defaults are added/changed, documenting external plugins that aren't even in core (changes external to core will mismatch historical documentation), & the generated doc assumes the same features for every project (if different libraries are included, these defaults can change, be missing, or even wrong). The chance of being wrong here is what I view as the largest detriment.

A compromise proposal:

1. Change this PR so that the current default values are extracted from core & only include libraries that will exist in every Grails app. i.e. no hibernate, no database migration, no asset pipeline, nothing optional. Store those defaults in a way they can be retrieved programmatically.
2. Use the branch I created to determine what's overridden at build time in a test app
3. Take the output from 1 & 2 to generate a config doc that we publish with a disclaimer that the configuration values are the base settings that may be changed based on additional project settings.
4. Update the documentation to point people to the command so they know how to get the specific settings for their project

Longer term we can move those defaults into a location that we can programmatically retrieve them (I gave one proposal earlier).