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.

Sign up for GitHub

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

Rewrite upgrade instructions #1788

Merged
merged 5 commits into from
Mar 18, 2021
Merged

Rewrite upgrade instructions #1788

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
706d32d
Drop tar and git checkout upgrade instructions
ekohl Mar 4, 2021
845ffb2
Remove duplicate upgrade header
ekohl Mar 4, 2021
8572535
Rewrite upgrade steps using an OS selector
ekohl Mar 4, 2021
66dbb01
Stop dynflow in when performing upgrades
ekohl Mar 9, 2021
6998b96
Add PostgreSQL upgrade instructions on EL8
ekohl Mar 4, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
272 changes: 165 additions & 107 deletions _includes/manuals/2.4/3.6_upgrade.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,3 @@

### Upgrading to Foreman {{page.version}}

#### Scope

**These instructions apply to environments not using Katello**
Expand All @@ -20,6 +17,30 @@ when planning to upgrade, as these change between releases. If your OS is no
longer supported by Foreman, migrate or upgrade the OS (if supported) using a
release of Foreman supported by both OS versions before upgrading Foreman.

<script type="text/javascript">
function update_upgrade_os(select) {
var os = select.value;
$(".upgrade_os").hide();
if (os) {
$(".upgrade_os_"+os).show();
} else {
$(".upgrade_os_none").show();
}
}
$(document).ready(function() {
$('#upgrade_os').trigger('change');
});
</script>

To provide specific installation instructions, please select your operating system:
<select id="upgrade_os" onChange="update_upgrade_os(this);">
<option value="none">-- select operating system --</option>
<option value="el7">CentOS 7 / Red Hat Enterprise Linux 7</option>
<option value="el8">CentOS 8 / Red Hat Enterprise Linux 8</option>
<option value="debian10">Debian 10 (Buster)</option>
<option value="ubuntu1804">Ubuntu 18.04 (Bionic)</option>
</select>

#### Step 1 - Backup

It is recommended that you backup your database and modifications to Foreman
Expand All @@ -31,113 +52,138 @@ For more information about how to backup your instance head over to

#### Step 2 - Perform the upgrade

Before proceeding, it is necessary to shutdown the Foreman instance (e.g.
`systemctl stop httpd foreman.service foreman.socket` or
`systemctl stop apache foreman.service foreman.socket` usually).

Now it's time to perform the actual upgrade. This process if different
depending on how you downloaded Foreman. You only need to perform *one* of
the following options.

##### Step 2 (A) - RHEL package (RPM) and installer setups

Before proceeding, it is necessary to shutdown the Foreman instance.

<div class="upgrade_os upgrade_os_none">
<i>No operating system selected.</i>
</div>
<div class="upgrade_os upgrade_os_el7 upgrade_os_el8">
{% highlight bash %}
systemctl stop httpd foreman.service foreman.socket dynflow\*
{% endhighlight %}
</div>
<div class="upgrade_os upgrade_os_debian10 upgrade_os_ubuntu1804">
{% highlight bash %}
systemctl stop apache foreman.service foreman.socket dynflow\*
{% endhighlight %}
</div>

Now it's time to perform the actual upgrade.

<div class="upgrade_os upgrade_os_none">
<i>No operating system selected.</i>
</div>

<div class="upgrade_os upgrade_os_el7">
To upgrade an existing Foreman installation, first update with the
appropriate foreman-release package for your operating system:
appropriate foreman-release package:

yum upgrade https://yum.theforeman.org/releases/{{page.version}}/el7/x86_64/foreman-release.rpm
{% highlight bash %}
yum upgrade https://yum.theforeman.org/releases/{{page.version}}/el7/x86_64/foreman-release.rpm
{% endhighlight %}

Clean up the yum metadata cache:

yum clean metadata

First install or upgrade the SCL release packages to add the RHSCL repository:
Also make sure centos-release-scl-rh is up to date:

yum install centos-release-scl-rh
{% highlight bash %}
yum upgrade centos-release-scl-rh
{% endhighlight %}

or:

yum upgrade centos-release-scl-rh

Clean up the yum metadata cache once more, to ensure the new repositories are used:
Clean up the yum metadata cache:

yum clean metadata
{% highlight bash %}
yum clean metadata
{% endhighlight %}

Next upgrade all Foreman packages:

yum upgrade tfm\* ruby\* foreman\*
{% highlight bash %}
yum upgrade tfm\* ruby\* foreman\*
{% endhighlight %}

Optionally, consider removing unused SCL packages:

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):

rpmconf -a --frontend=vimdiff

You can skip to Step 3.
{% highlight bash %}
yum erase rh-ruby22\* rh-ruby24\* rh-ror42\* tfm-ror52\*
{% endhighlight %}
</div>

##### Step 2 (B) - Debian or Ubuntu package (deb) and installer setups
<div class="upgrade_os upgrade_os_el8">
To upgrade an existing Foreman installation, first update with the
appropriate foreman-release package:

Upgrading from the last release to {{page.version}} has been tested on both
Debian and Ubuntu. Updating the packages will upgrade the application and
automatically migrate the database.
{% highlight bash %}
dnf upgrade https://yum.theforeman.org/releases/{{page.version}}/el8/x86_64/foreman-release.rpm
{% endhighlight %}

First edit `/etc/apt/sources.list.d/foreman.list` and change the release
number from the previous release or "stable" to `{{ page.version }}`:
Clean up the yum metadata cache:

deb http://deb.theforeman.org/ buster {{ page.version }}
deb http://deb.theforeman.org/ plugins {{ page.version }}
{% highlight bash %}
dnf clean metadata
{% endhighlight %}

Next upgrade all Foreman packages:

apt-get update
apt-get --only-upgrade install ruby\* foreman\*

You can skip to Step 3.

##### Step 2 (C) - Downloaded release (tar.bz2)

- Uncompress the new program archive in a *new directory*.
- Copy your database settings-file `config/database.yml` into the new `config` directory.

VERY IMPORTANT: do NOT overwrite `config/settings.yml` with the old one.

##### Step 2 (D) - git checkouts only
{% highlight bash %}
dnf upgrade ruby\* foreman\*
{% endhighlight %}

*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. It is recommended to upgrade by [switching module streams](https://docs.fedoraproject.org/en-US/modularity/using-modules-switching-streams/).

1. Go to the Foreman root directory and run the following command:
First check which version of PostgreSQL is currently installed:

For staying on the stable branch:
{% highlight bash %}
rpm -qv postgresql-server
{% endhighlight %}

- git checkout {{page.version}}-stable
- git pull
If you're already on 12 or don't have the PostgreSQL server installed, you can continue with step 3. Otherwise upgrade:

There may have been changes to the ruby gem or node module versions, to update
run the following commands:
{% highlight bash %}
systemctl stop postgresql.service
# https://bugzilla.redhat.com/1935301
sed -i '/^data_directory =/d' /var/lib/pgsql/data/postgresql.conf
dnf module reset postgresql
dnf module install postgresql:12
dnf install postgresql-upgrade
postgresql-setup --upgrade
ekohl marked this conversation as resolved.
Show resolved Hide resolved
systemctl start postgresql.service
{% endhighlight %}
</div>

bundle update
npm update
<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.
Copy link
Member

Choose a reason for hiding this comment

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

do deb packages still run migrations in postinstall?

Copy link
Member Author

Choose a reason for hiding this comment

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

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


The following step is the one that could change the contents of your database.
Go to your new Foreman directory (or the git dir), then migrate and update the
contents of your database:

foreman-rake db:migrate
foreman-rake db:seed
First edit `/etc/apt/sources.list.d/foreman.list` and change the release
number from the previous release to `{{ page.version }}`:

<div class="upgrade_os upgrade_os_debian10">
{% highlight bash %}
deb http://deb.theforeman.org/ buster {{ page.version }}
deb http://deb.theforeman.org/ plugins {{ page.version }}
{% endhighlight %}
</div>
<div class="upgrade_os upgrade_os_ubuntu1804">
{% highlight bash %}
deb http://deb.theforeman.org/ bionic {{ page.version }}
deb http://deb.theforeman.org/ plugins {{ page.version }}
{% endhighlight %}
</div>

You should compile i18n strings and precompile assets now:
Next upgrade all Foreman packages:

foreman-rake locale:pack
foreman-rake assets:precompile RAILS_ENV=production
foreman-rake webpack:compile RAILS_ENV=production
{% highlight bash %}
apt-get update
apt-get --only-upgrade install ruby\* foreman\*
{% endhighlight %}
</div>

#### Step 3 - Post-upgrade steps

##### Step 3 (A) - Database migration and cleanup

The database should be migrated already, but you can make sure by executing the
migration script again, it should produce no errors or output:
Make sure by executing database is migrated. It should produce no errors or
output:

foreman-rake db:migrate
foreman-rake db:seed
Comment on lines 188 to 189
Copy link
Member

Choose a reason for hiding this comment

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

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

Copy link
Member Author

Choose a reason for hiding this comment

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

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

Expand All @@ -147,7 +193,13 @@ You should clear the cache and the existing sessions:
foreman-rake tmp:cache:clear
foreman-rake db:sessions:clear

##### Optional Step 3 (B) - Run foreman-installer
##### Optional Step 3 (B) - Reclaim database space

After database migrations, some space can sometimes be reclaimed. It's a good idea to perform a *full* database vacuum for PostgreSQL rather than relying on the autovacuum feature to claim maximum space possible.

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

##### Optional Step 3 (C) - Run foreman-installer
Copy link
Member

Choose a reason for hiding this comment

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

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)

Copy link
Member Author

Choose a reason for hiding this comment

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

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


If you used foreman-installer to set up your existing Foreman instance we
recommend running it again after upgrading. Note that the installer can
Expand All @@ -156,41 +208,47 @@ the installer in noop mode so you can see what would be changed.

To see what would happen

foreman-installer --noop --dont-save-answers --verbose
foreman-installer --noop --verbose

You may see ERRORS such as `/Stage[main]/Foreman_proxy::Register/Foreman_smartproxy[foreman-hostname.domain]:` `Could not evaluate: Connection refused - connect(2)` due to httpd / apache2 service being stopped. These can be safely ignored.

To apply these changes, run the installer again without options

foreman-installer

#### Step 4 - Restart

Restart the application server (e.g. mongrel, thin, passenger).

On RPM installations, run:

systemctl start httpd foreman.service foreman.socket

And on Debian/Ubuntu installations, run:

systemctl start apache foreman.service foreman.socket

#### Optional Step 5 - Reclaim database space

After database migrations, some space can sometimes be reclaimed. It's a good idea to perform a *full* database vacuum for PostgreSQL rather than relying on the autovacuum feature to claim maximum space possible. For PostgreSQL do the following:

foreman-maintain service stop --exclude postgresql
su - postgres -c 'vacuumdb --full --dbname=foreman'
foreman-maintain service start

On platforms where foreman-maintain is not available, stop all Foreman-related services except PostgreSQL.

#### Optional Step 6 - Cleanup of RPMs and repositories

On EL7, consider removing unused SCL packages:

yum erase rh-ruby22\* rh-ruby24\* rh-ror42\* tfm-ror52\*
##### 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>
Comment on lines +219 to +233
Copy link
Member

Choose a reason for hiding this comment

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

Perhaps only show this whole section only for upgrade_os_el7?

Copy link
Member Author

Choose a reason for hiding this comment

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

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.


##### Step 4 - Restart

Start the application server. This is redundant if you previously ran `foreman-installer` in step 3B.

<div class="upgrade_os upgrade_os_none">
<i>*No operating system selected.*</i>
</div>
<div class="upgrade_os upgrade_os_el7 upgrade_os_el8">
{% highlight bash %}
systemctl start httpd foreman.service foreman.socket
{% endhighlight %}
</div>
<div class="upgrade_os upgrade_os_debian10 upgrade_os_ubuntu1804">
{% highlight bash %}
systemctl start apache foreman.service foreman.socket
{% endhighlight %}
</div>

#### Common issues

Expand Down
Loading