Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
en:2.0:update_new [2026/10/14 13:30] – kainhoferen:2.0:update_new [2026/10/14 16:00] (current) – kainhofer
Line 1: Line 1:
 ====== Updating Admidio with the Core Updater ====== ====== 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.+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.+Admidio 4.x and 5.0 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. Which releases are possible is listed in [[#which_versions_can_be_upgraded|Which versions can be upgraded]].
  
-  * Installing the Core Updater for Admidio 4.x and 5.0 +The update only starts when an administrator starts it. Nothing is updated in the background. 
-  * Running the Core Updater from 6.0 and later (with screenshots)+ 
 + 
 +  * Admidio 6.0 or later: [[#performing_an_update_from_admidio_60_and_later|Start the update from the preferences (with screenshots)]] 
 +  * Admidio 4.x or 5.0: [[#add_the_updater_for_admidio_4x_and_50|Manually install the updater and call it]]
  
 ===== Which versions can be upgraded ===== ===== Which versions can be upgraded =====
Line 17: Line 20:
 You cannot go backwards: the updater refuses to install a version that is older than the one you have. You cannot go backwards: the updater refuses to install a version that is older than the one you have.
  
-===== Performing an Update from Admidio 6.0 and later =====+===== Performing an update from Admidio 6.0 and later =====
  
-  - Make your own backup of the folder ''adm_my_files'' and of the database. (optional, the core updater will also make a backup) +  - Optional, but recommended: back up the folder ''adm_my_files'' (see [[#what_you_need|What you need]]). The updater never changes or deletes it, but it does not copy it either, so a backup of your uploads, photos and documents is your insurance if something goes terribly wrong. The database is backed up by the updater itself. 
-  - Open **Preferences → System → Update & backup** and click **Update Admidio**. (Admidio 4.x and 5.x do not have this button yet: see chapter 5.) +  - Open **Preferences → System → Update & backup** and click **Update Admidio**. (Admidio 4.x and 5.0 do not have this button yet: see [[#add_the_updater_for_admidio_4x_and_50|Add the updater for Admidio 4.x and 5.0]] below.) 
-  - Check the requirements, confirm the download, choose "Back up the database", click **Install update**.+    - Developers can choose a development version instead (only with debug mode switched on, see [[#questions_and_answers|the questions at the end]]). For normal installations, only the stable version is offered. 
 +  - [[#check_requirements|Check the requirements]], confirm the [[#download|download]], [[#review_the_changes|choose "Back up the database"]], click **Install update**.
   - Wait until the page says "Admidio has been updated to version ...".   - 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.+If there are any warnings or problems, the final page will clearly indicate it (see [[#finish|Finish]] and [[#if_something_goes_wrong|If something goes wrong]]). It also shows the locations of the file and database backups.
  
 +Each step is explained in detail in [[#the_update_step_by_step|The update step by step]] below.
  
-===== Add the updater for Admidio 4.x and 5.x =====+===== Add the updater for Admidio 4.x and 5.0 =====
  
-Do these steps for 4.x and for 5.x alike.+Do these steps for 4.x and for 5.0 alike.
  
-  - **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).+  - **Back up** the folder ''adm_my_files'' and the database (recommended, see [[#before_you_start|Before you start]]). Make sure your server runs **PHP 8.2 or newer** (see [[#what_you_need|What you need]]; ask your hosting provider; the latest 4.3 release was tested with PHP 8.3).
   - **Download the updater package** ''admidio-core-updater-X.Y.Z.zip'' of the latest release from the [[https://www.admidio.org/download.php|download page]]. It is small and only contains the folder ''install/core-update''.   - **Download the updater package** ''admidio-core-updater-X.Y.Z.zip'' of the latest release from the [[https://www.admidio.org/download.php|download page]]. It is small and only contains the folder ''install/core-update''.
-    - The ''core-update'' directory needs to go to the ''install/core-update/'' directory on the server of your Admidio installation: +  - **Unpack the zip-file on your computer.** You get a folder ''install'' with a folder ''core-update'' inside. 
-    - **Unpack the zip-file on your computer.** You get a folder ''install'' with a folder ''core-update'' inside. +  - **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.0), merge it. Only files inside ''install/core-update'' are added; nothing is overwritten.
-    - **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.+
   - **Make the files readable** for the web server (the same permissions as your other Admidio files).   - **Make the files readable** for the web server (the same permissions as your other Admidio files).
   - **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).   - **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).
   - 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.**   - 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.**
-  - Follow the steps of the updater.+  - Follow the steps of the updater, described in [[#the_update_step_by_step|The update step by step]] below.
  
-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.+Once Admidio 6.0 or later is installed, the updater is part of the installation and can be started from the button in the preferences.
  
 ==== Details about upgrading from earlier versions ==== ==== Details about upgrading from earlier versions ====
Line 48: Line 52:
     * Plugins written for 4.x are mostly **not compatible** with 6.x: ask the author for a new version.     * 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.   * 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/'' (see [[#what_the_update_does_with_your_files|What the update does with your files]]). 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.
-  * 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''.   * **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''.
  
- +===== What you need =====
- +
-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. +
- +
-===== 2. What you need =====+
  
 ^ What ^ Why ^ ^ What ^ Why ^
-| A backup of your own | The updater backs up the database. It does **not** copy the files in ''adm_my_files'' (uploads, photos, documents). Copy that folder yourself. |+| A backup of your own (recommended) | The updater backs up the database. It does **not** copy the files in ''adm_my_files'' (uploads, photos, documents), but it does not change or delete them either. Copy that folder yourself as insurance in case something goes terribly wrong. |
 | PHP 8.2 or newer | The current 6.x release needs it. Ask your hosting provider, or switch the PHP version in your hosting panel, **before** you update. The updater checks it and refuses to go on otherwise. | | PHP 8.2 or newer | The current 6.x release needs it. Ask your hosting provider, or switch the PHP version in your hosting panel, **before** you update. The updater checks it and refuses to go on otherwise. |
 | The PHP extensions ''curl'', ''zip'', ''openssl'', ''json'' and ''pdo'' with the driver of your database | The updater downloads the release with ''curl'', unpacks it with ''zip'' and verifies it with ''openssl''. | | The PHP extensions ''curl'', ''zip'', ''openssl'', ''json'' and ''pdo'' with the driver of your database | The updater downloads the release with ''curl'', unpacks it with ''zip'' and verifies it with ''openssl''. |
Line 73: Line 66:
 | An administrator account of Admidio | Only administrators can start or continue an update. | | An administrator account of Admidio | Only administrators can start or continue an update. |
  
-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).+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 [[#if_something_goes_wrong|If something goes wrong]]).
  
-===== 3. Before you start =====+===== Before you start =====
  
-  - **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.+  - **Back up ''adm_my_files'' and the database** (recommended). The updater never touches ''adm_my_files'' and makes a backup of the database itself, but a backup of your own is cheap insurance.
   - **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.)   - **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.)
-  - **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. +  - **Finish pending updates.** If you updated the files earlier but never finished the database update (''install/update.php''), do that first (see [[#check_requirements|Check requirements]]). The updater tells you if this is the case. 
-  - **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.+  - **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 [[#what_the_update_does_with_your_files|What the update does with your files]]): note your changes down or keep a copy.
   - **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.   - **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.
  
-===== 4. Update an installation that has the updater (6.0 and later) =====+===== The update step by step =====
  
-==== 4.1 Notice that an update exists ====+==== Notice that an update exists ====
  
 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 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:
Line 95: Line 88:
 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. 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.
  
-==== 4.2 Start the update ====+==== Start the update ====
  
-Click **Update Admidio**. The updater opens on a page of its own. On the left you see the steps of the update:+Click **Update Admidio** (see [[#notice_that_an_update_exists|Notice that an update exists]]). The updater opens on a page of its own. On the left you see the steps of the update:
  
   - Check requirements   - Check requirements
Line 108: Line 101:
   - Finish   - Finish
  
-==== 4.3 Check requirements ====+{{ :en:2.0:update:01_preferences_updater.png?direct&600 |The Update & backup preferences}} 
 +{{ :en:2.0:update:02_updater_channel.png?direct&600 |Choosing the release channel}} 
 + 
 +Developers can choose a development version instead of the stable one (only with debug mode switched on, see [[#questions_and_answers|the questions at the end]]). For normal installations, only the stable version is offered. 
 + 
 +==== Check requirements ====
  
 The updater checks the new version and your server. Every line is either green (ok) or tells you what is missing. Typical messages: The updater checks the new version and your server. Every line is either green (ok) or tells you what is missing. Typical messages:
Line 123: Line 121:
 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. 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.
  
-==== 4.4 Download ====+{{ :en:2.0:update:03_updater_requirements.png?direct&600 |The requirements check}} 
 + 
 +==== Download ====
  
 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. 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.
Line 129: Line 129:
 If the download is interrupted (browser closed, connection lost), open the updater again and click **Start or continue update**. It continues where it stopped. If the download is interrupted (browser closed, connection lost), open the updater again and click **Start or continue update**. It continues where it stopped.
  
-==== 4.5 Review the changes ====+After the download the updater unpacks the release and compares its files with yours. 
 + 
 +{{ :en:2.0:update:04_updater_extract.png?direct&600 |Unpacking the release}} 
 + 
 +==== Review the changes ====
  
 The page "Ready to update to version X" tells you what will happen: 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 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,+  * how many files were **changed or do not belong to the installed version**. They are kept in a ZIP archive (see [[#what_the_update_does_with_your_files|What the update does with your files]]), nothing is lost,
   * under **Details of the changes** the lists of the removed and kept files.   * under **Details of the changes** the lists of the removed and kept files.
  
Line 140: Line 144:
  
   * **Back up the database before the update (recommended)**: the updater backs up the database itself.   * **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).+  * **I have my own current backup of the database**: choose this only if you really have one (and see [[#protect_it_with_a_password|how to protect the backups]]). 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.**+{{ :en:2.0:update:05_updater_overview_dbbackup.png?direct&600 |Overview of the changes and choice of the database backup}}
  
-==== 4.6 What happens now ====+Click **Install update** when you are ready. **From here on the site is in maintenance mode.** If something fails from here on, see [[#if_something_goes_wrong|If something goes wrong]]. 
 + 
 +==== What happens now ====
  
 The updater runs through the remaining steps without further questions: The updater runs through the remaining steps without further questions:
Line 155: Line 161:
 If your server cuts off a long request, the page keeps asking the server until the database update is really finished. If your server cuts off a long request, the page keeps asking the server until the database update is really finished.
  
-==== 4.7 Finish ====+{{ :en:2.0:update:06_updater_files_backup.png?direct&600 |Backing up and replacing the files}} 
 +{{ :en:2.0:update:07_updater_dbupdate.png?direct&600 |Updating the database}} 
 + 
 +==== Finish ====
  
 The page says **"Admidio has been updated to version ..."**. It lists The page says **"Admidio has been updated to version ..."**. It lists
Line 167: Line 176:
 Click **Open Admidio**. Try the start page, the login and one or two modules. Usually you stay logged in; if not, log in again. 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).+{{ :en:2.0:update:08_updater_finished.png?direct&600 |The update is finished}}
  
-===== 5. Upgrading old releases (4.x and 5.x) =====+If there are warnings or problems, the final page says so clearly, with the locations of the backups and notes for you to act on.
  
 +{{ :en:2.0:update:09_updater_finished_warning.png?direct&600 |The final page with a warning}}
  
-===== 6. What the update does with your files =====+The backups stay on your server until you delete them. You can download and delete them in **Preferences → System → Update & backup** (see [[#backups|Backups]]). 
 + 
 +===== What the update does with your files =====
  
 ^ What ^ What happens ^ ^ What ^ What happens ^
Line 185: Line 197:
 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. 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.
  
-===== 7. Backups =====+===== Backups =====
  
 The backups are in the folder ''adm_my_files/backups''. You manage them in **Preferences → System → Update & backup**: The backups are in the folder ''adm_my_files/backups''. You manage them in **Preferences → System → Update & backup**:
Line 192: Line 204:
   * 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.   * 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.
  
-==== 7.1 What a database backup is ====+==== What a database backup is ====
  
 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 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''.
  
-==== 7.2 Protect it with a password ====+==== Protect it with a password ====
  
 A backup contains your members' data. You can encrypt every backup with a password (AES-256): A backup contains your members' data. You can encrypt every backup with a password (AES-256):
Line 211: Line 223:
 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. 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.
  
-==== 7.3 Restoring a backup by hand ====+==== Restoring a backup by hand ====
  
-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+The updater restores its own backups for you if an update fails (see [[#if_something_goes_wrong|If something goes wrong]]). 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
  
 <code bash> <code bash>
Line 225: Line 237:
 </code> </code>
  
-===== 8. If something goes wrong =====+===== If something goes wrong =====
  
 **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?** **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?**
  
-==== 8.1 The browser was closed or the connection broke ====+==== The browser was closed or the connection broke ====
  
 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: 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:
Line 236: Line 248:
   * 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.   * 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).+The page then shows where the update stands and continues from there, or shows the buttons for the situation: [[#an_error_while_the_files_are_installed|an error while the files are installed]] or [[#the_database_update_failed|the database update failed]].
  
-==== 8.2 An error while the files are installed ====+==== An error while the files are installed ====
  
 Typical cause: file permissions. The page says "The file ... could not be installed. Check the file permissions on the server." and offers: Typical cause: file permissions. The page says "The file ... could not be installed. Check the file permissions on the server." and offers:
Line 245: Line 257:
   * **Restore version X**: all previous files are put back. The database has not been changed yet, so Admidio works as before.   * **Restore version X**: all previous files are put back. The database has not been changed yet, so Admidio works as before.
  
-==== 8.3 The database update failed ====+==== The database update failed ====
  
 The files are new and the database is half updated. Admidio stays in maintenance mode, and the page names the error and offers The files are new and the database is half updated. Admidio stays in maintenance mode, and the page names the error and offers
Line 253: Line 265:
   * **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.   * **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.+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 (see [[#restoring_a_backup_by_hand|Restoring a backup by hand]]) 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. 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.
  
-==== 8.4 Last resort ====+==== Last resort ====
  
 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. 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.
  
-==== 8.5 Reporting a problem ====+==== Reporting a problem ====
  
 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 [[https://www.admidio.org/forum/|Admidio forum]], together with your PHP version and your hosting provider. 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 [[https://www.admidio.org/forum/|Admidio forum]], together with your PHP version and your hosting provider.
  
-===== 9. Using the command line =====+===== Using the command line =====
  
-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.+If you have shell access (SSH), you can run the same update without a browser. The commands do exactly what the pages do (see [[#the_update_step_by_step|The update step by step]]) and ask the same two questions: before the download and before the installation. Run them 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. The PHP of the command line may be a different version than the one of your web server: check it with ''php -v''.
  
-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):+There are two ways to start the update: 
 + 
 +^ ^ Updater script ^ ''admidio'' utility ^ 
 +| Command | ''php install/core-update/cli.php apply'' | ''./admidio update:apply'' | 
 +| Available in | every installation that contains the updater, including 4.x and 5.0 after you added it | Admidio 6.0 and later | 
 +| Works while Admidio cannot start (unfinished update, maintenance mode) | Yes | No | 
 +| Needs | nothing else | the command line enabled in ''config.php'' and an administrator (''--as'') | 
 + 
 +==== The updater script ==== 
 + 
 +Go to the main folder of your Admidio installation and run:
  
 <code bash> <code bash>
Line 276: Line 298:
 </code> </code>
  
-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''.+Other commands of the script:
  
-Useful options:+<code bash> 
 +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) 
 +</code> 
 + 
 +If an update stops half way and Admidio no longer starts (see [[#if_something_goes_wrong|If something goes wrong]]), use this script: ''apply --resume'' continues the update, ''rollback'' undoes it. 
 + 
 +==== The admidio utility ==== 
 + 
 +The utility ''admidio'' in the main folder is the command line of Admidio 6.x. It starts the same updater in a process of its own, because the update replaces the program files that the utility itself has loaded. Two things are needed first: 
 + 
 +  * The command line is switched off by default. Enable it in ''adm_my_files/config.php'': 
 + 
 +<code php> 
 +$gCliEnabled = true; 
 +</code> 
 + 
 +  * Commands that change something act in the name of an Admidio administrator. Name the account with ''--as'' (login name, ID or UUID). The utility does not ask for a password: whoever can run it on the server is trusted. Instead of repeating ''--as'' you can set the account once in ''config.php'' as ''$gCliDefaults = array('as' => 'admin');''. 
 + 
 +<code bash> 
 +cd /path/to/admidio 
 +./admidio update:check                      # is there a newer release? (exit code 4 = yes) 
 +./admidio update:apply --as=admin           # check, download, install, update the database 
 +./admidio update:apply --as=admin --dry-run # rehearsal: check and plan only 
 +./admidio update:rollback --as=admin        # undo the unfinished update 
 +</code> 
 + 
 +If the file is not executable on your system, put ''php'' in front: ''php admidio update:check''. ''update:check'' only tells you whether a new version exists. A cron job with ''./admidio maintenance:run --job=update-check'' keeps the [[#notice_that_an_update_exists|update notice]] in the preferences up to date. 
 + 
 +If an update stops and Admidio cannot start any more, the utility cannot help; continue with the [[#the_updater_script|updater script]] (''php install/core-update/cli.php apply --resume''). 
 + 
 +==== Options ==== 
 + 
 +The options are the same for [[#the_updater_script|the updater script]] and for ''update:apply'' of [[#the_admidio_utility|the utility]]:
  
 ^ Option ^ Meaning ^ ^ Option ^ Meaning ^
Line 284: Line 339:
 | ''--dry-run'' | Check and plan only, then cancel. Nothing is installed. A good rehearsal. | | ''--dry-run'' | Check and plan only, then cancel. Nothing is installed. A good rehearsal. |
 | ''--backup=dump'' or ''--backup=own'' | The updater backs up the database (default where possible), or you confirm an own backup. | | ''--backup=dump'' or ''--backup=own'' | The updater backs up the database (default where possible), or you confirm an own backup. |
-| ''--on-changed=cancel'' | Cancel the update if files that you changed (or unknown files) would be replaced. The default is to archive and replace them. |+| ''--on-changed=cancel'' | Cancel the update if files that you changed (or unknown files) would be replaced. The default (''archive'') is to archive and replace them. |
 | ''--skip-database'' | Install the files only; maintenance mode stays on until you run ''apply --resume'' (or ''install/update.php''). | | ''--skip-database'' | Install the files only; maintenance mode stays on until you run ''apply --resume'' (or ''install/update.php''). |
 | ''--resume'' | Continue the unfinished update, also to retry a failed database update. | | ''--resume'' | Continue the unfinished update, also to retry a failed database update. |
 | ''--dump-password-env=NAME'' | The password for the backup is in the environment variable NAME. It is never given on the command line itself. | | ''--dump-password-env=NAME'' | The password for the backup is in the environment variable NAME. It is never given on the command line itself. |
 | ''--format=json'' | Machine-readable result. | | ''--format=json'' | Machine-readable result. |
 +| ''--channel=...'', ''--ref=...'' | Only with debug mode: install a development version (beta, master, a branch, a tag or a pull request). |
  
-Other commands: +For ''rollback'' (and ''update:rollback''): it 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 (see [[#restoring_a_backup_by_hand|Restoring a backup by hand]]) and add ''--database-restored''.
- +
-<code bash> +
-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) +
-</code> +
- +
-''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.+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. (''update:check'' returns 4 if an update is available.)
  
-===== 10. Questions and answers =====+===== Questions and answers =====
  
 **Does Admidio update itself automatically?**\\ **Does Admidio update itself automatically?**\\
Line 309: Line 356:
  
 **Can I go back to the old version afterwards?**\\ **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.+Until the database update has started, the updater can put back the previous files (button or ''rollback'', see [[#using_the_command_line|Using the command line]]). 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?**\\ **How long does an update take?**\\
Line 318: Line 365:
  
 **Why does the updater say "Automatic updates are not available for this installation"?**\\ **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.+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 (see "Can I still update by hand?" below).
  
 **Do I need the updater package for every update?**\\ **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.+No, only once for an installation older than 6.0 (see [[#add_the_updater_for_admidio_4x_and_50|Add the updater for Admidio 4.x and 5.0]]). From 6.0 on the updater is part of Admidio and updates itself with every release.
  
 **Can I still update by hand?**\\ **Can I still update by hand?**\\
Line 330: Line 377:
  
 **Where do I find the old archives and backups?**\\ **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''.+In **Preferences → System → Update & backup**, in the list of backups (see [[#backups|Backups]]), and in the folder ''adm_my_files/backups''.
  
  • en/2.0/update_new.1791977436.txt.gz
  • Last modified: 2026/10/14 13:30
  • by kainhofer