Updating Admidio with the Core Updater

Since version 6.0, Admidio provides a core updater that installs a new Admidio release for you: it downloads the release, checks it, backs up your database, replaces the program files and updates the database. You do not have to unpack files or upload them by FTP, and if something goes wrong it can put the previous version back.

Admidio 4.x and 5.x do not contain the updater. You add it once manually as a small package and then update directly to the latest 6.x release. You do not have to install the versions in between.

• Installing the Core Updater for Admidio 4.x and 5.0
• Running the Core Updater from 6.0 and later (with screenshots)

You cannot go backwards: the updater refuses to install a version that is older than the one you have.

1. Make your own backup of the folder adm_my_files and of the database. (optional, the core updater will also make a backup)
2. Open Preferences → System → Update & backup and click Update Admidio. (Admidio 4.x and 5.x do not have this button yet: see chapter 5.)
3. Check the requirements, confirm the download, choose “Back up the database”, click Install update.
4. Wait until the page says “Admidio has been updated to version …”.

The rest of this page explains each step and what to do if one of them fails.

Do these steps for 4.x and for 5.x alike.

1. Back up the folder adm_my_files and the database. Make sure your server runs PHP 8.2 or newer (ask your hosting provider; the latest 4.3 release was tested with PHP 8.3).
2. Download the updater package admidio-core-updater-X.Y.Z.zip of the latest release from the download page. It is small and only contains the folder install/core-update.
   1. The core-update directory needs to go to the install/core-update/ directory on the server of your Admidio installation:
   2. Unpack the zip-file on your computer. You get a folder install with a folder core-update inside.
   3. Upload the folder install into the main folder of your Admidio installation (the folder that contains adm_my_files and index.php). Keep the structure: the result must be <your Admidio folder>/install/core-update/index.php. If a folder install exists already (5.x), merge it. Only files inside install/core-update are added; nothing is overwritten.
3. Make the files readable for the web server (the same permissions as your other Admidio files).
4. Open the updater in your browser:
   https://www.example.org/admidio/install/core-update/index.php
   (replace the address with the address of your Admidio).
5. If you are not logged in as administrator, the page asks you to log in to Admidio as an administrator and has a Log in button for the login page of your version. After the login, open the updater address again.
6. Follow the steps of the updater.

Once Admidio 6.0 or later is installed, the updater is part of the installation and can be executed from the button in the preferences.

• Plugins you installed yourself in the old folder adm_plugins are moved to the new folder plugins. If the server does not allow it, the result page shows a warning that tells you what to move by hand.
  • Plugins written for 4.x are mostly not compatible with 6.x: ask the author for a new version.
• New settings are added with their default values.
• If your 5.x version is older than 5.0.15, visitors see the maintenance page only once the first files have been replaced.
• Admidio 4.x keeps its program files in the folder adm_program. The updater removes the old code as part of the update and keeps a backup copy in adm_my_files/backups/. The old addresses such as …/adm_program/overview.php no longer exist afterwards. Update links and bookmarks. Menu entries and the start page setting of Admidio are converted by the database update.
• Your own themes in adm_themes cannot be used by the new version. The updater leaves them untouched and names them on the result page. Delete them when you no longer need them. The new standard theme is themes/simple.

This page explains

• how to update an installation that already has the Core Updater (Admidio 6.0 and later),
• how to upgrade old releases, Admidio 4.x and 5.x, to the latest 6.x release,
• what the updater does with your files, what to do if it stops, and how to use it on the command line.

The update only starts when an administrator starts it. Nothing is updated in the background.

Updating is also possible if your server has little time per request: the updater works in portions of a few seconds. Only the database update is one long step (see chapter 8).

1. Back up adm_my_files and the database. The updater makes a backup of the database as well, but a backup of your own is cheap insurance.
2. Choose a quiet time. During the file replacement visitors see a maintenance page. (Admidio 4.x and 5.0 before 5.0.15 do not know maintenance mode yet: there the pages stay reachable until the old files are removed at the end of the file replacement. Update when nobody works in Admidio.)
3. Finish pending updates. If you updated the files earlier but never finished the database update (install/update.php), do that first. The updater tells you if this is the case.
4. Check your plugins and themes. The plugins that come with Admidio are updated with it. Plugins and themes that you installed yourself must be available for the new version: ask their authors. Modified core files are replaced (see chapter 6): note your changes down or keep a copy.
5. Open the updater in a normal browser window, not in a private tab that closes by itself, and keep it open until it is finished.

Admidio looks for a new release at most twice a day, but only while an administrator is using Admidio. If there is one, administrators see a notice above the content of every page:

Admidio 6.1.0 is available. Update Admidio

You can close the notice; it comes back when there is a newer version. In Preferences → System → Update & backup you can switch the check off (“Notify about new Admidio versions”).

You can also check by hand: Preferences → System → Information or Update & backup, click Check for update. If an update is available, a button Update Admidio appears next to the result.

Click Update Admidio. The updater opens on a page of its own. On the left you see the steps of the update:

1. Check requirements
2. Download update
3. Unpack and compare files
4. Review changes
5. Back up database
6. Replace files
7. Update database
8. Finish

The updater checks the new version and your server. Every line is either green (ok) or tells you what is missing. Typical messages:

Errors (red) stop the update; warnings (yellow) do not. If all is well, click Download and prepare. Nothing has been changed on your site so far, and Cancel update removes everything the updater has created.

The updater downloads the release in parts and shows a progress bar. It then checks that the package is the one Admidio announced: the announcement is digitally signed, the package must have the announced checksum, and every file in it is checked again. Only HTTPS is used. If a check fails, the update ends and nothing is installed.

If the download is interrupted (browser closed, connection lost), open the updater again and click Start or continue update. It continues where it stopped.

The page “Ready to update to version X” tells you what will happen:

• how many files are new, replaced, removed and already up to date,
• how many files were changed or do not belong to the installed version. They are kept in a ZIP archive (chapter 6), nothing is lost,
• under Details of the changes the lists of the removed and kept files.

Then you choose the backup of your database:

• Back up the database before the update (recommended): the updater backs up the database itself.
• I have my own current backup of the database: choose this only if you really have one. It is the only choice if your server cannot back up the database itself (for PostgreSQL the program pg_dump is needed).

Click Install update when you are ready. From here on the site is in maintenance mode.

The updater runs through the remaining steps without further questions:

1. Maintenance mode goes on, and the database is backed up.
2. Every file that is replaced or removed is copied away first, then the new files are installed and checked again.
3. The database is updated. This can take several minutes for a large installation. Keep the page open.
4. Maintenance mode goes off.

If your server cuts off a long request, the page keeps asking the server until the database update is really finished.

The page says “Admidio has been updated to version …”. It lists

• where the backup of the database is,
• where the archive of changed and replaced files is,
• notes from the database update, for example about plugins that could not be moved.

The log of the update is saved in adm_my_files/logs/core-update_<date>_<from>_to_<to>.log.

Click Open Admidio. Try the start page, the login and one or two modules. Usually you stay logged in; if not, log in again.

The backups stay on your server until you delete them. You can download and delete them in Preferences → System → Update & backup (see chapter 7).

The archive of replaced files is a ZIP file adm_my_files/backups/files_<date>_<time>_<from version>_to_<to version>_<code>.zip. It contains every file that was changed, unknown or removed, with its full path, and a list meta.json. It is never deleted automatically, and you can download or delete it in the preferences. A ZIP file cannot be run, so a suspicious file in it does no harm.

Before a single file is replaced, the updater copies it to a safe place, and it writes a journal of every step. That is what makes it possible to put the previous version back.

The backups are in the folder adm_my_files/backups. You manage them in Preferences → System → Update & backup:

• Back up the database now makes the same kind of backup as the updater does, whenever you want one.
• The list Backups shows all backups and archives of replaced files with type, date and size, and lets you download or delete each of them. Nothing is deleted automatically: remember to clean up now and then, the files contain all your data.

A ZIP file database_<date>_<time>_<version>_<code>.zip. It contains one file per table (001_adm_….sql.gz and so on) with the structure and the data. For PostgreSQL it contains one file made with pg_dump.

A backup contains your members' data. You can encrypt every backup with a password (AES-256):

• In Preferences → System → Update & backup, field Password for the database backups of updates. The password is stored in the database and never shown again; leave the field empty to keep it, tick Remove the stored password to delete it.
• Or, safer, in adm_my_files/config.php:

$gCoreUpdateDumpPassword = 'a long secret password';

A password in config.php takes precedence over the one in the preferences. Keep it safe: without the password a backup cannot be restored. If your server cannot encrypt ZIP files, the updater warns you and makes the backup without encryption.

To open an encrypted ZIP file you need a program that supports AES encryption, for example 7-Zip or WinZip. The built-in ZIP functions of Windows and macOS cannot do it.

The updater restores its own backups for you if an update fails (chapter 8). To restore a backup by hand, unpack the ZIP, then import the files into the database in the order of their names, for example with phpMyAdmin or

gunzip -c 001_adm_announcements.sql.gz | mysql -u USER -p DATABASE

Each file replaces its table (it starts with DROP TABLE). A backup of a PostgreSQL database holds a single file that you restore with

gunzip -c DATABASE.sql.gz | psql -U USER DATABASE

First: do not panic. Before the update changes anything, the updater keeps the previous files and a backup of the database. The page always shows the possible next steps under What should I do?

Open the updater address again (…/install/core-update/index.php in your Admidio folder). While Admidio is in maintenance mode you cannot use the normal login, so the updater has a login of its own:

• The browser that started the update can continue without a login.
• Any other browser or computer: log in with the login name, password and, if you use two-factor authentication, the security code of an administrator. After five wrong logins the login is blocked for 15 minutes.

The page then shows where the update stands and continues from there, or shows the buttons for the situation (see below).

Typical cause: file permissions. The page says “The file … could not be installed. Check the file permissions on the server.” and offers:

• Continue the update, once you have fixed the cause. It continues with the file at which it stopped.
• Restore version X: all previous files are put back. The database has not been changed yet, so Admidio works as before.

The files are new and the database is half updated. Admidio stays in maintenance mode, and the page names the error and offers

• Retry the database update, once the cause is fixed (for example with help from the Admidio forum). It continues with the step that failed.
• Restore version X (recommended): the database is restored from the backup that was made before the update, then the files. Admidio works exactly as before, and you can try the update again later.
• Restore version X and look for a corrected release: the same, but a new update starts at once. If a fixed release has been published in the meantime, it is offered.

If you chose “I have my own current backup” and the updater has no backup, you must first restore the database from your backup yourself and tick I have restored the database from my own backup. Only then are the files restored.

When the database update “has not reported back”, it may still be running. Wait a few minutes and reload the page before you retry it.

If the updater itself does not open and your site shows the maintenance page for hours, you can switch maintenance mode off by deleting the file adm_my_files/maintenance.json. Only do this when you are sure no update is running, and check afterwards whether Admidio works: an interrupted update leaves a mixture of old and new files.

The log of every update is in adm_my_files/logs/core-update_<date>_<from>_to_<to>.log and the page shows Error details for a bug report. Please add both to your report in the Admidio forum, together with your PHP version and your hosting provider.

If you have shell access (SSH), you can run the same update without a browser. The commands do exactly what the pages do and ask the same two questions: before the download and before the installation.

Go to the main folder of your Admidio installation and run (as the user that owns the Admidio files; if you use another user, the new files belong to that user and later updates in the browser may fail):

cd /path/to/admidio
php install/core-update/cli.php apply

This works in every installation that contains the updater, including 4.x and 5.x after chapter 5.2. The PHP of the command line may be a different version than the one of your web server: check it with php -v.

Useful options:

Other commands:

php install/core-update/cli.php status          # is an update unfinished, and in which state?
php install/core-update/cli.php rollback        # undo the unfinished update (asks first; --yes to confirm)

rollback cancels an update that has not changed anything, puts the previous files back until the database update has started, and after a failed database update restores the previous version with the backup of the updater. If the updater has no backup, restore your own database backup first and add –database-restored.

The exit code tells scripts what happened: 0 = done, 1 = error, 2 = wrong options, 5 = refused (for example a failed requirement check), 6 = the update could not be completed.

In Admidio 6.x with the Admidio command line enabled you can also use php admidio update:apply –as=LOGIN and php admidio update:rollback –as=LOGIN, which start the same updater. php admidio update:check only tells you whether a new version exists, and php admidio maintenance:run –job=update-check in a cron job keeps the notice of chapter 4.1 up to date.

Does Admidio update itself automatically?
No. It only looks for a new version and tells the administrators. An administrator has to start every update.

Can I go back to the old version afterwards?
Until the database update has started, the updater can put back the previous files (button or rollback). After a failed database update it can restore the database and the files. After a successful update there is no “undo”: restore the backup of your own, or the database backup of the updater together with the old files.

How long does an update take?
On a good server less than a minute; on shared hosting usually a few minutes. The database update of a very old installation (4.x) takes longer.

Is the download safe?
The announcement of a new release is digitally signed by the Admidio team and contains the checksum of the package. The updater downloads over HTTPS only, checks the signature and the checksum, and checks every file again after the installation. A release that fails any check is not installed.

Why does the updater say “Automatic updates are not available for this installation”?
The release that is announced has no package for the updater yet, or your version is older than 4.0. Download the release from the Admidio website and update by hand, as described in its documentation.

Do I need the updater package for every update?
No, only once for an installation older than 6.0. From 6.0 on the updater is part of Admidio and updates itself with every release.

Can I still update by hand?
Yes. Uploading the files of a release and opening install/update.php works as before. The updater is a convenience, not a requirement.

Can I update to a beta or a development version?
The updater offers only stable releases. Other versions are for testers who switch on debug mode in config.php; do not use them on a live site.

Where do I find the old archives and backups?
In Preferences → System → Update & backup, in the list of backups, and in the folder adm_my_files/backups.