Rewrite upgrade instructions #1788

ekohl · 2021-03-04T10:29:45Z

This limits the manual to RPM/deb packages since that's what most users use. Those who use git or tarballs are expected to handle it themselves.

In the next commit it copies the OS selector from the quickstart. This makes the upgrade instructions shorter since you don't need to skip over irrelevant OSes. For users this is less confusing.

It also removes the foreman-maintain reference. This can be done by moving the cleanup step to a point where the services should be stopped anyway. Avoiding a start-stop cycle makes the overall process shorter. The noop command removes the redundant --dont-save-answers. --noop already implies that.

With all of this in place it's easy to add PostgreSQL upgrade instructions only on EL8. In the previous structure it would have been too confusing.

ekohl · 2021-03-04T10:30:44Z

@ehelms in theforeman/foreman-installer#646 you had much more complex instructions but I found these to work for me. Could review?

_includes/manuals/2.4/3.6_upgrade.md

ekohl · 2021-03-09T13:15:32Z

I think I addressed the comments. They're in separate commits for easier review.

ekohl · 2021-03-10T18:02:33Z

I'll need to update this to remove the PG upgrade instructions since we're not going to push that into 2.4.

ekohl · 2021-03-10T18:03:19Z

And probably also incorporate #1194 which has been open for way too long.

ehelms · 2021-03-10T21:00:33Z

_includes/manuals/2.4/3.6_upgrade.md

-*Please note* that there can be significant differences between stable and
-development branches.  You MUST take care to select a branch and make sure you
-get the correct one.
+Foreman runs best on PostgreSQL 12 but the default version on EL8 is 10. The installer will try to use version 12 but can't upgrade existing databases. An upgrade can be performed by [switching module streams](https://docs.fedoraproject.org/en-US/modularity/using-modules-switching-streams/).


I think you decided this no longer holds true (the part about the installer trying to use PG 12). And this upgrade to PG 12 for Foreman 2.4 is an optional step (that we should encourage users to under take).

ehelms

Small nit around the PG upgrade wording, everything else looks good

This limits the manual to RPM/deb packages since that's what most users use. Those who use git or tarballs are expected to handle it themselves.

Previously the menu was: 3. Installing Foreman ... 3.6 Upgrade Upgrading to Foreman 2.4 After this change it's 3. Installing Foreman ... 3.6 Upgrade to 2.4

This copies the OS selector from the quickstart. This makes the upgrade instructions shorter since you don't need to skip over irrelevant OSes. For users this is less confusing. It also removes the foreman-maintain reference. This can be done by moving the cleanup step to a point where the services should be stopped anyway. Avoiding a start-stop cycle makes the overall process shorter. The noop command removes the redundant --dont-save-answers. --noop already implies that.

Includes a workaround for BZ 1935301 in upgrades. postgresql-upgrade is unable to deal with data_directory in postgresql.conf. This is added by puppetlabs/postgresql so pretty much guaranteed to be present.

ekohl · 2021-03-11T15:46:50Z

I've updated this slightly. All changes are in the last commit (PG upgrade instructions on EL8). It now only recommends to upgrade. Please review and merge when approved.

ehelms

@tbrisker final review and merge is left to you

tbrisker · 2021-03-16T17:20:17Z

_includes/manuals/2.4/3.6_upgrade.md

+<div class="upgrade_os upgrade_os_debian10 upgrade_os_ubuntu1804">
+Upgrading from the last release to {{page.version}} has been tested. Updating
+the packages will upgrade the application and automatically migrate the
+database.


do deb packages still run migrations in postinstall?

Yes, https://github.com/theforeman/foreman-packaging/blob/9fe8df5457c502b9b48bc38cebedebfada41486f/debian/buster/foreman/foreman-postgresql.postinst#L35-L36 (and other postinst files)

tbrisker · 2021-03-16T17:21:35Z

_includes/manuals/2.4/3.6_upgrade.md

    foreman-rake db:migrate
    foreman-rake db:seed


Don't we run migrations from the installer and seeds on startup? this should be optional probably

I didn't want to go full in on installer only. This procedure is safe and tested for both cases.

tbrisker · 2021-03-16T17:22:32Z

_includes/manuals/2.4/3.6_upgrade.md

+
+    su - postgres -c 'vacuumdb --full --dbname=foreman'
+
+##### Optional Step 3 (C) - Run foreman-installer


considering we are aiming to have the installer as the main recommended way, shouldn't this come first and not marked as optional (with a comment it isn't relevant if you aren't using the installer)

I didn't want to got that far. Still plenty of improvement possible but this is now clearer than it used to be (IMHO).

tbrisker · 2021-03-16T17:23:32Z

_includes/manuals/2.4/3.6_upgrade.md

+##### Optional Step 3 (D) - Update config files
+<div class="upgrade_os upgrade_os_none">
+  <i>*No operating system selected.*</i>
+</div>
+<div class="upgrade_os upgrade_os_el7">
+In order to catch all configuration changes and manage them properly you should install and run
+rpmconf from the EPEL repository along with vim-enhanced (for vimdiff).
+
+{% highlight bash %}
+rpmconf -a --frontend=vimdiff
+{% endhighlight %}
+</div>
+<div class="upgrade_os upgrade_os_el8 upgrade_os_debian10 upgrade_os_ubuntu1804">
+This step is irrelevant for the chosen operating system.
+</div>


Perhaps only show this whole section only for upgrade_os_el7?

I didn't want to write that complex code. If you use HTML tags, you can't use markdown. So ##### needs to be some HTML tag.

tbrisker

Thanks for the effort @ekohl ! I agree there is more that can be done but this is already a great improvement.

ekohl force-pushed the rewrite-upgrading-guide branch 2 times, most recently from c6118ac to a5523a8 Compare March 4, 2021 12:21

ehelms reviewed Mar 4, 2021

View reviewed changes

_includes/manuals/2.4/3.6_upgrade.md Outdated Show resolved Hide resolved

ehelms reviewed Mar 4, 2021

View reviewed changes

_includes/manuals/2.4/3.6_upgrade.md Outdated Show resolved Hide resolved

ehelms reviewed Mar 4, 2021

View reviewed changes

_includes/manuals/2.4/3.6_upgrade.md Show resolved Hide resolved

ekohl mentioned this pull request Mar 4, 2021

Fixes #31834 - Use PostgreSQL 12 on EL8 theforeman/foreman-installer#650

Merged

ekohl marked this pull request as draft March 10, 2021 18:02

ehelms reviewed Mar 10, 2021

View reviewed changes

ehelms approved these changes Mar 10, 2021

View reviewed changes

ekohl added 5 commits March 11, 2021 16:37

Drop tar and git checkout upgrade instructions

706d32d

This limits the manual to RPM/deb packages since that's what most users use. Those who use git or tarballs are expected to handle it themselves.

Remove duplicate upgrade header

845ffb2

Previously the menu was: 3. Installing Foreman ... 3.6 Upgrade Upgrading to Foreman 2.4 After this change it's 3. Installing Foreman ... 3.6 Upgrade to 2.4

Stop dynflow in when performing upgrades

66dbb01

Add PostgreSQL upgrade instructions on EL8

6998b96

Includes a workaround for BZ 1935301 in upgrades. postgresql-upgrade is unable to deal with data_directory in postgresql.conf. This is added by puppetlabs/postgresql so pretty much guaranteed to be present.

ekohl force-pushed the rewrite-upgrading-guide branch from f2fac59 to 6998b96 Compare March 11, 2021 15:45

ekohl marked this pull request as ready for review March 11, 2021 15:45

ekohl requested review from tbrisker and ehelms March 11, 2021 15:46

ehelms approved these changes Mar 15, 2021

View reviewed changes

tbrisker reviewed Mar 16, 2021

View reviewed changes

tbrisker approved these changes Mar 18, 2021

View reviewed changes

tbrisker merged commit b2b43db into theforeman:gh-pages Mar 18, 2021

ekohl deleted the rewrite-upgrading-guide branch March 18, 2021 17:33

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rewrite upgrade instructions #1788

Rewrite upgrade instructions #1788

ekohl commented Mar 4, 2021

ekohl commented Mar 4, 2021

ekohl commented Mar 9, 2021

ekohl commented Mar 10, 2021

ekohl commented Mar 10, 2021

ehelms Mar 10, 2021

ehelms left a comment

ekohl commented Mar 11, 2021

ehelms left a comment

tbrisker Mar 16, 2021

ekohl Mar 18, 2021

tbrisker Mar 16, 2021

ekohl Mar 18, 2021

tbrisker Mar 16, 2021

ekohl Mar 18, 2021

tbrisker Mar 16, 2021

ekohl Mar 18, 2021

tbrisker left a comment


		su - postgres -c 'vacuumdb --full --dbname=foreman'

		##### Optional Step 3 (C) - Run foreman-installer

Rewrite upgrade instructions #1788

Rewrite upgrade instructions #1788

Conversation

ekohl commented Mar 4, 2021

ekohl commented Mar 4, 2021

ekohl commented Mar 9, 2021

ekohl commented Mar 10, 2021

ekohl commented Mar 10, 2021

Choose a reason for hiding this comment

ehelms left a comment

Choose a reason for hiding this comment

ekohl commented Mar 11, 2021

ehelms left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tbrisker left a comment

Choose a reason for hiding this comment