How To Upgrade Ubuntu on RunCloud

Servers use operating systems, and like any piece of software, operating systems get outdated. If you have connected your servers to RunCloud, then you should keep an eye on Ubuntu release cycle as the older versions are gradually phased out and periodically reach end of life, and we advise our users to take action on their servers on RunCloud.

Moreover, you should note that Ubunutu 24 will only support PHP 8.1 and later versions, if you wish to use an older PHP versions then you should read our documentation about legacy PHP applications.

Server Migration Guide (Recommended)

Instead of upgrading your existing server, RunCloud strongly recommends following the steps below, which is a safer approach:

1. Create a new server with the desired Ubuntu version: Log in to your RunCloud dashboard and provision a new server using one of our existing guides.

2. Back up your existing applications using RunCloud’s backup functionality: After creating a new server, it is always advisable to create a full backup that includes all files, databases, and configurations.
3. Use RunCloud’s cloning feature to move your applications to the new server: In the RunCloud panel, go to the ‘Web Applications‘ section and select the application you want to move.
   On this page, click on the ‘Clone‘ option and select your new server as the destination. Review and confirm the other cloning settings, such as SSL configurations and database credentials. Finally, click on “Clone” to start the migration process.

4. Update your DNS records to redirect traffic to the new server: If you are using RunCloud to manage your DNS records, you can quickly update the application’s DNS records to point to the new server.
   
   If you are not using RunCloud to manage your DNS records, you will need to log in to your domain registrar to update them to point to the IP address of your new server.
   
   We also recommend you lower your TTL (Time To Live) values temporarily to speed up propagation.
   
   To ensure a smooth process, you may also wish to refer to our guides on how to speed up DNS propagation and how to flush the DNS cache.
5. Repeat: After cloning one application, you will need to repeat steps 2, 3, and 4 for all your applications individually to move them to the new server.
6. Monitor the new server: After migration, you should verify that all files, databases, and configurations have been transferred correctly. Here are a few things that you should pay attention to:
   • Monitor server resources (CPU, RAM, disk usage) to ensure they’re within normal ranges.
   • Check your logs (Nginx, PHP, application-specific) for any unusual entries.
   • Test all functionalities of your applications, including forms, logins, and data processing.
   • Verify that your SSL certificates are working correctly.
   • If you’re using custom Nginx configurations, make sure you transfer these to the new server.
   • Update any hard-coded IP addresses in your application code or configuration files.
   • If you’re using a firewall or a CDN, remember to configure it on the new server.
   • Update any external services or APIs that might be pointing to your old server’s IP address.
7. Remove the old server: Once the old server stops receiving traffic, you can safely delete it by following these steps:
   • First, ensure that no DNS queries are resolving to the old server’s IP address, and double-check that all important data has been transferred and backed up.
   • If you didn’t use RunCloud’s server provisioning API, then you will need to go to your cloud provider’s panel to initiate the server deletion process.
   • If you used RunCloud to deploy your server, then you can directly remove the old server from your RunCloud panel. 
   • We recommend keeping any offsite backups of the old server for a reasonable period (e.g., 30 days) before deleting them.

By following the steps described above, you minimize the risk of downtime and potential complications that can arise from in-place operating system upgrades. 

Ubuntu Upgrade Guide (Use with Caution)

Upgrading the server operating system, while technically possible, is NOT RECOMMENDED and can cause severe issues with your RunCloud server and applications. The best way to do this is by provisioning a new server and cloning your web application there using our documentation. This will ensure a smooth transition, and avoid any potential issues with minimal downtime.

Note: This guide has only been tested for Upgrading from Ubuntu 22 to Ubuntu 24, if you are running an older version of Ubuntu, we recommend you to migrate your web applications as described above.

If you still wish to proceed with an in-place upgrade, you can follow the steps below:

1. Prepare for the upgrade: Ensure you have a full backup of your server, and then update all the installed packages on your server using the following command:

sudo apt update && sudo apt upgrade -y

2. Install the upgrade tool: After upgrading the packages, you need to make sure that you have the necessary tools installed by running the following command:

sudo apt install ubuntu-release-upgrader-core -y

3. Open alternative SSH port: If you are upgrading your server via SSH, you might lose access to your server if something goes wrong. To prevent this, run the following command to allow incoming connections on port 1022, which will be used during the upgrade process for SSH access in case the primary SSH port becomes unavailable:

sudo iptables -I INPUT -p tcp --dport 1022 -j ACCEPT

4. Start the upgrade process: After opening the ports, you can upgrade to the latest version by running the following command with superuser permissions:

sudo do-release-upgrade -d

5. Follow the on-screen prompts: The upgrade process will ask for confirmations at various stages. For example, it may ask to update configuration files or restart services. Review each change carefully, and press ‘Enter’ to confirm the changes.

6. Update RunCloud Agent: After upgrading your server, you might need to update the RunCloud agent on your server manually, simply run the following command on your server to update it to the latest version:

apt install runcloud-agent -y

7. Reboot the server: After the upgrade completes, you’ll be prompted to reboot the server. Keep in mind that during the reboot, all your websites and applications will be unavailable.
8. Remove Old Supervisor Config: On Ubuntu 24, the supervisor job config files are created at /etc/supervisor/conf.d whereas in older versions of Ubuntu, these files were created at /etc/supervisor.d. To handle this you need to remove the old supervisor files by executing the following commands:

rm /etc/systemd/system/supervisord.service
rm /usr/local/bin/supervisord
rm /usr/local/bin/supervisorctl
systemctl daemon-reload

9. Modify Supervisor Config: After removing the old files, you need to replace both instances of /var/run/supervisor.sock to /tmp/supervisor.sock in the /etc/supervisor/supervisord.conf file. If you are not sure how to do this, you can check our blog post which explains how to find and replace test in nano. After saving the modified file, you need to restart the service by running the following command:

systemctl restart supervisor

10. Post-upgrade checks: Once the server has finished rebooting, make sure that you can still access your server via SSH, and test each of your web applications for functionality by running the following commands:

systemctl status supervisor
systemctl status nginx-rc
systemctl status php81rc-fpm
systemctl status php82rc-fpm
systemctl status apache2-rc
systemctl status runcloud-agent

Troubleshooting

When the upgrading Ubuntu version, it has been observed that the upgrade process renames the firewalld configuration file located at /etc/firewalld/firewalld.conf. This renaming can cause connection issues with the RunCloud dashboard and other services.

While it’s not certain that this will occur during every upgrade, we strongly recommend you to cross-check the existence and contents of the /etc/firewalld/firewalld.conf file. If the file has been renamed or modified, you may need to restore the correct configuration to ensure continued proper functioning of RunCloud services.

In our internal testing, we have also observed some problems on PHP 8.3 applications on Ubuntu 24, this is a known bug and our engineers are currently working on it.

If you encounter any connectivity issues post-upgrade, checking this file should be one of your first troubleshooting steps. If you encounter any other problems during or after the upgrade, you can reach out to us in the RunCloud community.