Skip to content

docs: Document application configuration - #1174

Merged
johanandren merged 2 commits into
mainfrom
wip-config-docs-patriknw
Nov 20, 2025
Merged

johanandren merged 2 commits into
mainfrom
wip-config-docs-patriknw

Conversation

@patriknw

Copy link
Copy Markdown
Contributor

Fixes https://github.com/lightbend/akka-runtime/issues/4512

Seems like we didn't have documentation of configuration at all, aside from specific features such as model provider config.

@github-actions github-actions Bot added documentation documentation related java-sdk labels Nov 20, 2025

To access the configuration in application code you can use a constructor parameter `com.typesafe.config.Config` in all components and the `ServiceSetup` class. An example of this is shown in xref:setup-and-dependency-injection.adoc#_disabling_components[].

WARNING: Don't use `ConfigFactory.load()` since that will not load the `application.conf` as you intended. Use dependency injection of `Config` instead.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

here is the warning that was requested in the issue

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know this was the concrete thing the user hit but I don't like notes about what APIs you shouldn't use, isn't it better with just the right way than to try to cover everything you could do that won't work?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree but seems like it was a strong opinion about that we should highlight this problem. We don't behave as "normal" so I can understand that we should document the wrong way. New users probably don't know about ConfigFactory at all, but AI assistants will use it. I tried in a sample that was setup with right claude instructions and akka-context, and it recommends ConfigFactory.load().

I'm using Akka and need to read the application.conf in my service, how should I do that?

It's also a pretty bad mistake since it will probably work locally, but then fail when deployed.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, let's leave it in then

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this mean that AI coding assistants honor this from now on and behave different, e.g. not recommending ConfigFactory.load()?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That depends on how well they read the documentation.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if there is any way to throw an error/warning if they try....

@johanandren johanandren left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM with one opinion


To access the configuration in application code you can use a constructor parameter `com.typesafe.config.Config` in all components and the `ServiceSetup` class. An example of this is shown in xref:setup-and-dependency-injection.adoc#_disabling_components[].

WARNING: Don't use `ConfigFactory.load()` since that will not load the `application.conf` as you intended. Use dependency injection of `Config` instead.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know this was the concrete thing the user hit but I don't like notes about what APIs you shouldn't use, isn't it better with just the right way than to try to cover everything you could do that won't work?

@johanandren
johanandren merged commit 3fc5970 into main Nov 20, 2025
1 check passed
@johanandren
johanandren deleted the wip-config-docs-patriknw branch November 20, 2025 10:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation documentation related java-sdk

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants