How do I update the operating system of edoc platform (on-premises) from Ubuntu 20.04 LTS to Ubuntu 24.04 LTS?

Summary

In this article, you will learn how to update edoc platform On-Premises from Ubuntu 20.04 LTS to Ubuntu 24.04 LTS. You will also find help on potential problems that may occur during the update process.

First make some preparations to then update to Ubuntu 22.04 LTS and then to Ubuntu 24.04 LTS.

Important requirements

• You have sufficient knowledge of Linux to execute the commands described and adapt them if necessary.

• You are currently using Ubuntu Server 20.04 LTS. Ubuntu Desktop versions are not supported.

• You have created a current backup of the system.

• There is a downtime of approx. 1–1.5 hours during the update process. Plan the update time together with your team.

• Your edoc platform server is connected to the Internet to download updates.

• You may need to temporarily deactivate your firewall in order to perform updates.

• You are an administrative user with sudo permissions.

• You have read access to the system in edoc system control.

• The version of the Kubernetes environment (MicroK8s) has already been updated to 1.19. For more information see this KB article in the section "How to prepare the update".

Solution

How to prepare the update

Check the following aspects before updating. If there are deviations in the result, change the configuration according to the specifications.

Please proceed as follows to prepare the update:

1. Use the following command to ensure that Ubuntu has been set to LTS releases:

   grep Prompt /etc/update-manager/release-upgrades 
   

   The output must be Prompt=lts. If you receive a different output, set the prompt to lts using a text editor.

2. Use the following command to check whether the packages are kept. This means that these packages are not updated automatically, even if newer versions are available.

   sudo apt-mark showhold
   

   It is correct that there should be no output, so no packets are held.

3. Check the version of Ubuntu with the following command:

   lsb_release -r
   

   The output must be Release: 20.04.

4. Check the status of the Ubuntu firewall ufw with the following command:

   sudo ufw status
   

   The status of the firewall must be Disabled so that you can perform the update. Otherwise, temporarily deactivate the firewall for the update.

5. Check which additional package sources are retrieved by apt. In addition to the standard Ubuntu package sources, edoc has added the package source ppa:ondrej/php. Other package sources may also have been added, such as the Microsoft package source for Microsoft Azure systems. The package sources can be found under /etc/apt/sources.list.d.

6. Check the version of MicroK8s with the following command:

   snap list microk8s
   

   The version must be version v1.19. If the version of MicroK8s is older than 1.19, you must update the program. The function can be found in edoc system control for the system under Configurations > System update > Further options > Update Microk8s. (Get in touch with your edoc contact so that MicroK8s can be updated)

How to update the system

After the preparations, you can update the system. First stop Microk8s, update all packages again and add all cgroup entries.

Start the update

When MicroK8s is stopped, the services are no longer available.

1. Stop MicroK8s with the following command:

   sudo microk8s stop
   

2. Update the package lists and install the latest packages with the following command:

   sudo apt update && sudo apt dist-upgrade -y && sudo apt autoremove -y
   

3. Add all cgroup entries to the kernel with the following command:

   sudo grep -rl "GRUB_CMDLINE_LINUX_DEFAULT=" /etc/default/grub* | xargs sudo sed -i '/GRUB_CMDLINE_LINUX_DEFAULT=/ { /systemd\.unified_cgroup_hierarchy=0/! s/"$/ systemd.unified_cgroup_hierarchy=0"/ }'
   [ -d "/etc/default/grub.d/" ] && [ "$(ls -A /etc/default/grub.d/)" ] && sudo sed -i '/^GRUB_CMDLINE_LINUX_DEFAULT=/s/^/# /' /etc/default/grub.d/*
   sudo update-grub
   sudo reboot
   

Update the system to Ubuntu 22.04 LTS

In this step, you update Ubuntu 20.04 LTS to version 22.04 LTS. After executing the command, you will be asked configuration questions depending on the packages installed on the operating system.

You start the installation with the command:

sudo do-release-upgrade

The following questions may arise, which you should confirm accordingly:

• Confirm the opening of an additional SSH port under port 1022 with y (Continue).

• Information is displayed that the port must also be released in the firewall. Make sure this is the case and confirm the information by pressing Enter.

• Information is displayed that third-party package sources have been deactivated. Confirm the information with the Enter key.

• A confirmation is requested to adjust the installed packages. Confirm the customization with y. The size of the download is displayed.

• Confirm the restart of the services when upgrading the libraries, e.g. (libc), with yes.

• Confirm the deletion of obsolete packages (Remove obsolete packages?) with y.

• Confirm audit.rules with n.

• Confirm the changes in grub with ok.

• Confirm the retention of the configuration of packages with N.

• Confirm the restart with y.

Update the system to Ubuntu 24.04 LTS

Please update the package lists and install the latest packages with the following command:

sudo apt update && sudo apt dist-upgrade -y && sudo apt autoremove -y

In this step, you will update Ubuntu 22.04 LTS to version 24.04 LTS. Similar to the previous step, after executing the command–depending on the packages installed on the operating system–you will be asked questions about the configuration.

You start the update with the command:

sudo do-release-upgrade

The following questions may arise, which you should confirm accordingly:

• Confirm the question to continue (Continue) with y.

• Confirm the opening of an additional SSH port under port 1022 with y (Continue).

• Information is displayed that the port must also be released in the firewall. Make sure this is the case and confirm the information by pressing Enter.

• Information is displayed that third-party package sources have been deactivated. Confirm with the Enter key.

• A confirmation is requested to adjust the installed packages. Confirm this with y. The size of the download is displayed.

• Confirm the restart of the services when upgrading the libraries, e.g. (libc) with yes.

• Confirm the deletion of obsolete packages (Remove obsolete packages?) with y.

• Confirm audit.rules with n.

• Confirm the changes in grub with ok.

• Confirm the restart with y.

Tasks after the update

You have now updated the system to Ubuntu 24.04 LTS. Next, carry out a few steps to ensure that everything is working again:

1. Use the following command to check whether Ubuntu 24.04 LTS has now been installed:

   lsb_release -r
   

   The output must be Ubuntu 24.*.

2. Use the following command to check whether cgroup entries are present in the kernel:

   if stat -fc %T /sys/fs/cgroup/|grep -q tmpfs; then echo -e "cgroup ok";fi
   

   The output must be cgroup ok.

3. Use the following command to deactivate the LocalStorageCapacityIsolation feature in the kubelet:

   grep -q '\--feature-gates="LocalStorageCapacityIsolation=false"' /var/snap/microk8s/current/args/kubelet || echo '--feature-gates="LocalStorageCapacityIsolation=false"' | sudo tee -a /var/snap/microk8s/current/args/kubelet
   

4. Activate the third-party package sources used again. The package sources were commented out within the file during the update or backups of the files were created as *.distUpgrade. You can reactivate the two frequently used package sources ppa:ondrej/php and microsoft-prod using the following script:

if [ ! -f "/etc/apt/sources.list.d/ondrej-ubuntu-php-noble.sources" ]; then sudo rm /etc/apt/sources.list.d/ondrej-ubuntu-php-* 2>/dev/null;sudo add-apt-repository ppa:ondrej/php -y;fi
if [ -f "/etc/apt/sources.list.d/microsoft-prod.sources" ]; then sudo curl -sSL -O https://packages.microsoft.com/config/ubuntu/$(lsb_release -sr)/packages-microsoft-prod.deb && sudo dpkg -i packages-microsoft-prod.deb && sudo rm packages-microsoft-prod.deb;fi

4. Update the system packages with the following command:

   sudo apt update && sudo apt dist-upgrade -y && sudo apt autoremove -y
   

5. Optional: If you encounter problems, check your repos under /etc/apt/sources.list.d/. The repos must reference Ubuntu 24 (Noble). If apt update does not run (and only then), you can run the following command to change all repositories to Ubuntu 24 (Noble):

   ls /etc/apt/sources.list.d/*.list | sudo xargs -I{} sed -i -e 's/^[[:space:]]*//' -e '/disabled on upgrade/s/^#//' -e 's/20\.04/24.04/g' -e 's/focal/noble/g' -e 's/mantic/noble/g' {}
   

6. Start MicroK8s with the following command:

   sudo microk8s start
   

7. Use the following command to query the status of the pods. Be sure to wait until all pods show the status running. Normally it takes about 5-10 minutes.

   kubectl get pods -A
   

8. Check the system in edoc system control with regard to the status of MicroK8s and when the last contact was made. The last contact must have been made after the update.

You have done it and successfully updated edoc platform to Ubuntu 24.04 LTS.

Potential warning messages and tips

It can always happen that messages are displayed or the update is interrupted during the update process.

"apt update" warning for security keys (keys)

If you receive a warning about the keys when using apt, try reinstalling the affected repository. If reinstallation is not possible, use the following workaround:

sudo cp /etc/apt/trusted.gpg /etc/apt/trusted.gpg.d

For more information search the Internet for the keywords "apt" and "trusted.gpg"

Connection closed during update

If you accidentally close the connection during the update, the update process will continue in most cases and you can re-enter the current session with the following command:

sudo screen -D -r