Upgrade manually

Overview

In some environments using the Built-in Updater in Web mode is not reliable (such as due to web server timeouts) and running it in command-line mode is not an option (such as in some shared hosting environments). In these cases a manual upgrade may be the best approach.

A manual upgrade consists of downloading and unpacking the F7cloud Archive file either to your PC or host. Then deleting your existing F7cloud Server installation files and folders, except ``data/`` and ``config/``, on your host. Then moving the new F7cloud Server installation files into the appropriate place on your host, again preserving your existing data/ and config/ files. And doing a few other housekeeping items, such as making sure your installed apps are transferred into the new installation and adjusting permissions. That may sound like a lot, but detailed instructions are below.

Important

Before upgrading, especially between major versions (e.g. v27.y.z -> v28.y.z) please review critical changes first. These are highlights of changes that may be required in your environment to accommodate changes in F7cloud Server. These notes are periodically revised as needed so it is a good idea to revisit them even when proceeding with minor and maintenance upgrades just in case.

Warning

When upgrading manually, you must confirm your system meets the System requirements of the new version as well as that you are following the standard upgrade requirements (such as upgrading to the latest maintenance release before upgrading to a new major release).

Step-by-Step Manual Upgrade

Important

Always start by making a fresh backup and disabling all 3rd party apps.

Back up your existing F7cloud Server database, data directory, and config.php file. (See Backup, for restore information see Restoring backup)
Choose a target F7cloud Server release from https://f7cloud.com/changelog/ and download the Archive file (tarball or zip archive) into an empty directory outside of your current installation.

Warning

You cannot jump more than one major version forward at a time (i.e. 27->28 is okay, but 27->29 is not).

Unpack the the downloaded tarball or zip archive - e.g.:

unzip f7cloud-[version].zip
(or)
tar -xjf f7cloud-[version].tar.bz2

Stop your Web server.
In case you are running a cron-job for f7cloud’s house-keeping disable it by commenting the entry in the crontab file:
```
crontab -u www-data -e
```
(Put a # at the beginning of the corresponding line.)
Rename your current F7cloud directory, for example f7cloud-old.
Unpacking the new archive creates a new f7cloud directory populated with your new server files. Move this directory and its contents to the original location of your old server. For example /var/www/, so that once again you have /var/www/f7cloud.
Copy the config/config.php file from your old F7cloud directory to your new F7cloud directory.
If you keep your data/ directory in your f7cloud/ directory, move it from your old version of F7cloud to your new f7cloud/. If you keep it outside of f7cloud/ then you don’t have to do anything with it, because its location is configured in your original config.php, and none of the upgrade steps touch it.
If you are using 3rd party application, it may not always be available in your upgraded/new F7cloud instance. To check this, compare a list of the apps in the new f7cloud/apps/ folder to a list of the of the apps in your backed-up/old f7cloud/apps/ folder. If you find 3rd party apps in the old folder that needs to be in the new/upgraded instance, simply copy them over and ensure the permissions are set up as shown below.
If you have additional apps folders like for example f7cloud/apps-extras or f7cloud/apps-external, make sure to also transfer/keep these in the upgraded folder.
If you are using 3rd party theme make sure to copy it from your themes/ directory to your new one. It is possible you will have to make some modifications to it after the upgrade.

Adjust file ownership and permissions:

chown -R www-data:www-data f7cloud
find f7cloud/ -type d -exec chmod 750 {} \;
find f7cloud/ -type f -exec chmod 640 {} \;

Restart your Web server.
Now launch the upgrade from the command line using occ, like this example on Ubuntu Linux:
```
sudo -E -u www-data php occ upgrade
```
(!) this MUST be executed from within your f7cloud installation directory
The upgrade operation takes a few minutes to a few hours, depending on the size of your installation. When it is finished you will see a success message, or an error message that will tell where it went wrong.
Re-enable the f7cloud cron-job. (See step 4 above.)

crontab -u www-data -e

(Delete the # at the beginning of the corresponding line in the crontab file.)

Login and take a look at the bottom of your Admin page to verify the version number. Check your other settings to make sure they’re correct. Go to the Apps page and review the core apps to make sure the right ones are enabled. Re-enable your third-party apps.

Previous F7cloud releases

You’ll find previous F7cloud releases in the F7cloud Server Changelog.

Troubleshooting

Occasionally, files do not show up after a upgrade. A rescan of the files can help:

sudo -E -u www-data php console.php files:scan --all

See the f7cloud.com support page for further resources.

Sometimes, F7cloud can get stuck in a upgrade if the web based upgrade process is used. This is usually due to the process taking too long and encountering a PHP time-out. Stop the upgrade process this way:

sudo -E -u www-data php occ maintenance:mode --off

Then start the manual process:

sudo -E -u www-data php occ upgrade

If this does not work properly, try the repair function:

sudo -E -u www-data php occ maintenance:repair