Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Configuration Docs page has non-functional example yaml #1804

Open
jhiemstrawisc opened this issue Dec 6, 2024 · 4 comments
Open

Configuration Docs page has non-functional example yaml #1804

jhiemstrawisc opened this issue Dec 6, 2024 · 4 comments
Assignees
Labels
documentation Improvements or additions to documentation Facilitation A request from the RCF's
Milestone

Comments

@jhiemstrawisc
Copy link
Member

Our config parameters docs page starts out boldly with an example YAML config file, and we've observed users trying to copy-paste the example as a template for configuring their service.

Unfortunately, the example yaml is gobbledygook that doesn't doesn't compile, let alone work as a functional template...

At minimum, we should provide a config template that compiles. The best case would be to provide a minimal config example for each component -- it may be possible to provide one big config template that acts as a minimal working example for all components, but that might be more confusing than helpful. @aowen-uwmad, what do you think is ideal here? I'm inclined to think we create one minimal config per component.

@jhiemstrawisc jhiemstrawisc added the documentation Improvements or additions to documentation label Dec 6, 2024
@jhiemstrawisc jhiemstrawisc added this to the v7.13.0 milestone Dec 6, 2024
@aowen-uwmad aowen-uwmad added the Facilitation A request from the RCF's label Dec 10, 2024
@jhiemstrawisc
Copy link
Member Author

In discussion with @aowen-uwmad, and we think a minimal config per component is good, but we'd also like to link out to osg-htc.org where we can host an example for each service of "how we do things in production"

@CannonLock CannonLock assigned aowen-uwmad and unassigned bbockelm Dec 10, 2024
@CannonLock
Copy link
Contributor

CannonLock commented Dec 17, 2024

What is the goal of a minimal config?

Theoretically the best config is the default values, so our minimal config would be the default values. Depending on how dynamic the default values are this might cause pain if we change the default values without updating this minimal config.

@jhiemstrawisc
Copy link
Member Author

There are some defaults that can't be filled in for generic cases, e.g. if you're setting up an origin, you still need to define the origin's exports, capabilities, federation discovery url, etc. I think most of our services can be set up as bare bones in ~15-20 lines of config. My goal is that someone could copy-paste, fill in a few blanks, and then run the service without any crashes/errors.

@CannonLock
Copy link
Contributor

Ah makes sense, so this won't compile but it will be closer to compiling.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation Facilitation A request from the RCF's
Projects
None yet
Development

No branches or pull requests

4 participants