foreman-documentation Document external PostgreSQL earlier in the installation UX

What changes are you introducing?

Document external PostgreSQL databases as a prerequisite/preparation for Satellite installation, rather than as a migration option afterwards.

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Based on https://issues.redhat.com/browse/SAT-30802

Checklists

[x] I am okay with my commits getting squashed when you merge this PR.
[x] I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

[ ] Foreman 3.14/Katello 4.16
[ ] Foreman 3.13/Katello 4.15 (EL9 only)
[ ] Foreman 3.12/Katello 4.14 (Satellite 6.16)
[ ] Foreman 3.11/Katello 4.13 (orcharhino 6.11 on EL8 only; orcharhino 7.0 on EL8+EL9; orcharhino 7.1 with Leapp)
[ ] Foreman 3.10/Katello 4.12
[ ] Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
[ ] Foreman 3.8/Katello 4.10
[ ] Foreman 3.7/Katello 4.9 (Satellite 6.14)
We do not accept PRs for Foreman older than 3.7.

Apr 14 '25 11:04 jherrman

The PR preview for 0d8bfa856913e3e2302f7879b6cce72f4c5646e2 is available at theforeman-foreman-documentation-preview-pr-3783.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

Apr 14 '25 11:04 github-actions[bot]

I'll disregard the note in the PR description that says to disregard this PR because you've switched it from draft state to ready-for-review :)

I'm not convinced that the Preparing for installation assembly is the best place for the whole ext DB assembly. Looking at 1.7. Using external databases with Foreman, it now includes a lot of information from the planning phase (what options Foreman offers, considerations for these options, advantages/disadvantages).

On a similar note, are detailed steps on PostgreSQL installation really a prerequisite for installing a Foreman server? Not sure about better placement though. And now I'm also wondering whether it's something we should commit to documenting on our side. Do we have actual PostgreSQL docs to link to instead? That is something that might help make it fit into the Preparing chapter better.

The reason I'm asking these question is that I'm wondering whether users opening an installation guide, with the goal of installing a server, wouldn't feel a tiny bit frustrated from having to read a lot of text before getting to the actual installing server part. Personally, I like to see installation prerequisites as a sort of an action-packed 'pre-flight checklist' thing rather than long paragraphs :) What do you think? Do you observe some these points when you at the guide as a whole? Do you see some opportunities for making the ext DB assembly shorter and more action-focused or for moving some parts elsewhere perhaps?

Apr 17 '25 06:04 aneta-petrova

The reason I'm asking these question is that I'm wondering whether users opening an installation guide, with the goal of installing a server, wouldn't feel a tiny bit frustrated from having to read a lot of text before getting to the actual installing server part. Personally, I like to see installation prerequisites as a sort of an action-packed 'pre-flight checklist' thing rather than long paragraphs :)

I agree. Thanks @aneta-petrova for providing a more high-level input on this. (I hope this does not obsolete my style review :smile:)

But I feel like that we always have this question: keep guides short so that people actually ready them and achive their goal quickly vs. documenting every possible use case/scenario/configuration option to ensure that people can adapt Foreman/Katello to their specific requirements. :shrug:

Apr 17 '25 06:04 maximiliankolb

I agree. Thanks @aneta-petrova for providing a more high-level input on this. (I hope this does not obsolete my style review 😃

:D I'm sure it doesn't!

But I feel like that we always have this question: keep guides short so that people actually ready them and achive their goal quickly vs. documenting every possible use case/scenario/configuration option to ensure that people can adapt Foreman/Katello to their specific requirements. :shrug:

Call me naive (and people do, all the time) but I think you can have both focused guides and descriptions of options. What helps is keeping the content very action-focused (like bullet points with actions rather than long paragraphs), moving things that are just 'FYI' or considerations elsewhere (Planning? Appendix?), and making it easy to decide what you as a user can skip ("Optional:" or "If you want to use XYZ").

Apr 17 '25 07:04 aneta-petrova

Hi @maximiliankolb @aneta-petrova , thank you for weighing in on this. You're right that even after moving one of the modules into the Configuring Satellite Server procedure, this section is pretty big and unwieldy for a prereq item.

What I would do to alleviate the situation is the following

Create a single entirely new module (perhaps named "Preparing Satellite for using external databases") to use instead of the current assembly.
The new module would be marked as Optional, similar to 3.4. ("Optional: Using fapolicyd on Satellite Server")
The module would briefly outline the possibility of setting up external DB instead of the default internal DB. For most other information, it would use links to Chapter 4 in the Administering Satellite doc.

This way, it should be a less daunting prereq, but potentially sends the user to a different document when it doesn't have to. Still, in terms of the doc UX, it might arguably be the lesser evil here.

What do you think?

Apr 17 '25 09:04 jherrman

Sounds like a good plan, Jirka! Feel free to try it and see what it looks like.

I'll say one thing, though: I suggest you try to find a good solution rather than attempt to mimic the surrounding existing content. While that would normally be a good thing (for consistency), the long-term goal here is to improve the existing content (prerequisites and installation). So don't feel limited by what you see and try to find something that you like :)

Apr 17 '25 09:04 aneta-petrova

moving things that are just 'FYI' or considerations elsewhere (Planning? Appendix?)

I also though "appendix" but wondered why we don't do that more often. I assumed there was a good, unknown to me, reason for that.

Sounds like a good plan, Jirka! Feel free to try it and see what it looks like.

:+1:

Apr 17 '25 11:04 maximiliankolb

@jherrman I think the rebase on master failed. Do you need help with that?

Jul 03 '25 16:07 ekohl

@jherrman I think the rebase on master failed. Do you need help with that?

I think the branch should be mergeable with master (for the moment, at least), so hopefully no need, thank you :-)

Jul 04 '25 15:07 jherrman

@ekohl , thank you very much for reviewing the Debian-related changes before I even managed to ask for it :-)

With the recent updates, would you consider the changes sufficient, and the PR ready for merging in the current state?

Thanks again, J.

Jul 04 '25 16:07 jherrman

Please rebase to HEAD of "master".

Jul 07 '25 06:07 maximiliankolb

Hi @maximiliankolb , rebasing throws up a long series of sizeable conflicts (probably because I synced with master via merge, rather than rebase, at multiple points), so it's probably going to be easier to replicate the changes on a new branch and in a new PR.

For that purpose, I created https://github.com/theforeman/foreman-documentation/pull/3985 , and if that one works, this PR could probably be closed.

Apologies for the kerfuffle.

Jul 07 '25 13:07 jherrman

Closing this PR, see https://github.com/theforeman/foreman-documentation/pull/3985 for replacement/continuation.

Jul 07 '25 16:07 jherrman

Closing this PR, please see https://github.com/theforeman/foreman-documentation/pull/3985 for the replacement/continuation.

Jul 08 '25 10:07 jherrman