Friendica/upgrading

About

This page is about upgrading Friendica instances.

Steps

The folder where you put Friendica – which should be the same as your public web folder (typically public_html), will be referred to as <fka-root>.

To determine what version you are currently running, look at the <fka-root>/VERSION file. Upgrading must be done in stages: 3.54, 2018-09, and finally 2019-09.

The configuration file is <fka-root>/.htconfig.php, although it is distributed without the dot prefix (just htconfig.php).

upgrade to 3.5.4

1. Unzip the Friendica distribution
2. Rename the configuration file to .htconfig.php.
3. Edit the configuration file to have the proper access parameters for your Friendica database.
4. Open a terminal in <fka-root> and run:
   • php util/db_update.php
   • This will probably give warnings, but seems to complete even under PHP 7.2.

$ php util/db_update.php 
PHP Warning:  count(): Parameter must be an array or an object that implements Countable in /home/icms/domains/hey.iseeamess.com/site/git/friendica-3.5.4/include/pgettext.php on line 45
PHP Warning:  Invalid argument supplied for foreach() in /home/icms/domains/hey.iseeamess.com/site/git/friendica-3.5.4/include/pgettext.php on line 111
Old DB VERSION: 1159
New DB VERSION: 1234
Updating database...
Error 1050 occurred during database update:
Table 'temp-addon' already exists
PHP Warning:  Use of undefined constant dbesc - assumed 'dbesc' (this will throw an Error in a future version of PHP) in /home/icms/domains/hey.iseeamess.com/site/git/friendica-3.5.4/include/dbstructure.php on line 47
Done

upgrade to 2018-09

I've struck out steps which turned out to be dead-ends.

1. Unzip the v2018-09 Friendica distribution
2. Make it accessiable to the web
3. Rename .htaccess-dist to .htaccess
4. Browse your Friendica domain in order to access the web installer.
5. Fix any errors and enter the database information into the web installer.
   • You will get a "Database already in use" message if this works. (Nope: this does not write the config file.)
6. Copy config/local-sample.ini.php to config/local.ini.php
7. Modify config/local.ini.php to have the connection parameters for your Friendical database.
   • If your database's password contains any "$" characters, be sure to prefix them with backslashes: "pa$$word" -> "pa\$\$word"
8. From the <fka-root> folder, run:
   • chmod +x bin/console
   • bin/console dbstructure update

At this point I encountered many hairy database errors, which I was able to resolve.

Reloading the current page in the web installer returned a different message:

Documentation Whine

Database upgrade instructions are still difficult to find as of v2019-09:

• Update instructions on the 2019-09 release page say "please first update your Friendica instance to [v2018-09]".
• Update instructions on the 2018-09 release page say "First update to the 3.5.4 release", but do not link to instructions.
• The 3.5.4 release page does not seem to have any update instructions.

Documentation for upgrading Friendica's code and database schema was minimal or at least difficult to find as of 3.5.2-dev. The following were applicable:

1. Friendica automatically detects database issues and, when they are encountered, attempts to run a database upgrade.
2. Before starting, it automatically puts the site into maintenance mode.
3. If the upgrade completes successfully, it presumably takes the site back out of maintenance mode.
4. If the upgrade does not complete successfully, there are no notifications to this effect; you have to check the logfile for errors.
5. The current schema – much like Hubzilla's – has many table rows which try to set a default value for a DATETIME column, which (as of MySQL v5.7.17) may be disallowed by the server configuration.

This means that the automated upgrade may fail, and the SQL to create or modify tables will have to be tweaked and executed manually. (Details may change from version to version, but my notes are here.)

Old Notes

Notes I took during the last upgrade seem to indicate that there was a way to explicitly request a db upgrade in the "admin area", but I haven't been able to find the admin area yet in the current version (which isn't currently working; hopefully when I get it working, it will appear and I can update this section).

Previous notes said:

The update process does not always go smoothly. If you see a message like this in the admin db_updates area:

Executing update_1141 failed. Check system logs.

...then what you need to do is view the update.php file, manually execute the given SQL (adjusting permissions or whatever is necessary until it has executed), and then click the "DB updates" link again to get the list of failed updates (in this case, it should show 1141) and then click on the link which says "Mark success (if update was manually applied)".