AtoM 2.9 Updates

- Ubuntu 24.04
- PHP 8.3
- Elasticsearch 6.8

Author: melaniekung

admin-manual/customization/config-files.rst

@@ -831,8 +831,8 @@ has its own configuration file that defines some important global PHP settings
 like timeouts, and environment variables that may also modify the way that
 AtoM works as documented in accesstomemory.org.
 
-The file of the pool is located at ``/etc/php/7.4/fpm/pool.d/atom.conf``. Edit
-with ``nano``. Once saved, run: ``sudo systemctl restart php7.4-fpm``, and the
+The file of the pool is located at ``/etc/php/8.3/fpm/pool.d/atom.conf``. Edit
+with ``nano``. Once saved, run: ``sudo systemctl restart php8.3-fpm``, and the
 changes will apply.
 
 .. SEEALSO::

admin-manual/customization/theming.rst

@@ -92,7 +92,8 @@ Additional steps for tarball installations:
 *******************************************
 
 If not already installed, first `download the node.js binary distributuion
-<https://nodejs.org/en/download>`_ and export the PATH variable.
+<https://nodejs.org/en/download>`_ and export the PATH variable. AtoM requires
+the latest LTS version of node, v22 or above is required for AtoM 2.9+.
 
 The tarball is missing three required files for this:
 

admin-manual/installation/execution-limits.rst

@@ -13,7 +13,7 @@ useful guide we recommend reading: `Common pitfalls
 Some of these values are set during installation, in the PHP configuration
 pool you set up here:
 
-* :ref:`20.04 PHP-FPM Configuration <installation-ubuntu-serve-php-fpm>`
+* :ref:`24.04 PHP-FPM Configuration <installation-ubuntu-serve-php-fpm>`
 
 .. _execution-php-ini:
 
@@ -168,7 +168,7 @@ caches and restart Memcached (if you're using it as cache engine).
 
 .. code-block:: bash
 
-   sudo systemctl restart php7.4-fpm
+   sudo systemctl restart php8.3-fpm
    php symfony cc
 
 **Optionally, to restart Memcached**:

admin-manual/installation/macosx.rst

@@ -4,8 +4,8 @@
 Mac OS X
 ========
 
-OS X 10.7 (Lion) and newer ships with Apache and PHP pre-installed.
-Recent versions of OS X include PHP 5.4. On the other hand, MySQL can be
+OS X 15.2 (Sequoia) and newer ships with PHP pre-installed.
+Recent versions of OS X include PHP 8.x. On the other hand, MySQL can be
 installed using the `official package <http://dev.mysql.com/downloads/mysql/>`_.
 
 However, we encourage you to use `homebrew <http://brew.sh/>`_, an open source
@@ -16,19 +16,19 @@ and its maintenance much easier. Installing homebrew is easy:
 
    ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go/install)"
 
-Note that Xcode is required, which you can download from the App Store.
+
 More instructions can be found at:
 https://github.com/mxcl/homebrew/wiki/Installation
 
-Once homebrew and Xcode are installed, you are ready to install all the
+Once homebrew is installed, you are ready to install all the
 packages needed:
 
 .. code-block :: bash
 
-   brew install php54 --with-mysql --with-fpm
+   brew install php --with-mysql --with-fpm
    brew install nginx
    brew install elasticsearch
-   brew install mysql55
+   brew install mysql
 
 Some extra :ref:`dependencies <installation-requirements>` can be also be
 installed via homebrew:

admin-manual/installation/requirements.rst

@@ -62,12 +62,13 @@ of each component.
 * A webserver like `Apache <https://httpd.apache.org/>`__ or
   `Nginx <http://nginx.com/>`__; Artefactual prefers the latter in
   development
-* `Elasticsearch <https://www.elastic.co/products/elasticsearch>`__ 5.x (we use
-  ES 5.6 in development). Elasticsearch 6.0 or newer is not supported as they
-  have deprecated a number of APIs still used in AtoM
+* `Elasticsearch <https://www.elastic.co/products/elasticsearch>`__ 6.x (we use
+  ES 6.8 in development). ES 7 is not supported as ES 7.11+ uses Server
+  Side Public License (SSPL) and Elastic License 2.0 (ELv2), which are not
+  approved by the Open Source Initiative.
 * `Java <https://www.java.com/en/>`__ 8 (required for Elasticsearch)
 * `MySQL <https://www.mysql.com/>`__ 8.0
-* `PHP <http://php.net/>`__ 7.4
+* `PHP <http://php.net/>`__ 8.x (8.1, 8.2, 8.3 are all supported)
 * `Gearman job server <http://gearman.org>`__
 
 Optionally, Memcached can be used as cache engine:

admin-manual/installation/ubuntu.rst

@@ -1,8 +1,8 @@
 .. _installation-ubuntu:
 
-======================================
-Linux - Ubuntu 20.04 LTS (Focal Fossa)
-======================================
+==========================================
+Linux - Ubuntu 24.04 LTS (Noble Numbat)
+==========================================
 
 Most of the configuration steps described in this document apply to any modern
 Linux environment, however some of them will apply only to Ubuntu and likely to
@@ -11,7 +11,7 @@ development and testing using Ubuntu LTS releases, and cannot guarantee that
 other versions, distributions, or operating systems will work as expected with
 the following instructions.
 
-This document is based in `Ubuntu 20.04 LTS (Focal Fossa)`_. Once you have
+This document is based in `Ubuntu 24.04 LTS (Noble Numbat)`_. Once you have
 installed it, you should be able to follow the instructions described below.
 In particular, we are going to use Ubuntu packages that can be found under the
 `repositories`_ *main* and *universe*.
@@ -108,24 +108,20 @@ and install the public signing key used in their repository:
 
 .. code-block:: bash
 
-   wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
-
-.. IMPORTANT::
-
-   Don't miss the dash ( ``-`` ) at the end of the above command!
+   wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearmor -o /usr/share/keyrings/elasticsearch-keyring.gpg
 
 Now add their repository:
 
 .. code-block:: bash
 
-   echo "deb https://artifacts.elastic.co/packages/5.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-5.x.list
+   echo "deb [signed-by=/usr/share/keyrings/elasticsearch-keyring.gpg] https://artifacts.elastic.co/packages/oss-6.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-6.x.list
 
 Ready to be installed. Run:
 
 .. code-block:: bash
 
    sudo apt update
-   sudo apt install elasticsearch
+   sudo apt install -y elasticsearch-oss
 
 Start the service and configure it to start when the system is booted.
 
@@ -139,13 +135,14 @@ Start the service and configure it to start when the system is booted.
 PHP
 ---
 
-Ubuntu 20.04 bundles PHP 7.4, which is much faster than older releases. The
-following command will install it along with the rest of PHP extensions
+Ubuntu 24.04 bundles PHP 8.3, which is much faster than older releases.
+The following command will install it along with the rest of PHP extensions
 :ref:`required <installation-requirements>` by AtoM:
 
 .. code-block:: bash
 
-   sudo apt install php-common php7.4-common php7.4-cli php7.4-curl php7.4-json php7.4-ldap php7.4-mysql php7.4-opcache php7.4-readline php7.4-xml php7.4-mbstring php7.4-xsl php7.4-zip php-apcu php-apcu-bc
+   # For Ubuntu 24.04, running PHP 8.3
+   sudo apt install php-common php8.3-common php8.3-cli php8.3-curl php-json php8.3-ldap php8.3-mysql php8.3-opcache php8.3-readline php8.3-xml php8.3-mbstring php8.3-xsl php8.3-zip php-apcu
 
 If you are using Memcached as cache engine, you will also need to install
 `php-memcache`:
@@ -309,8 +306,13 @@ After downloading the code, you will need to compile the themes files:
 Compile Bootstrap 5 Theme Files:
 --------------------------------
 
+.. note::
+   When working with Bootstrap 5 themes, AtoM requires the latest LTS version of node.
+   Node v22 or above is required for AtoM 2.9+.
+
 .. code-block:: bash
 
+   sudo apt install npm
    sudo npm install
    sudo npm run build
 
@@ -528,16 +530,16 @@ file :file:`/usr/lib/systemd/system/atom-worker.service`:
    User=www-data
    Group=www-data
    WorkingDirectory=/usr/share/nginx/atom
-   ExecStart=/usr/bin/php7.4 -d memory_limit=-1 -d error_reporting="E_ALL" symfony jobs:worker
+   ExecStart=/usr/bin/php8.3 -d memory_limit=-1 -d error_reporting="E_ALL" symfony jobs:worker
    KillSignal=SIGTERM
    Restart=on-failure
    RestartSec=30
 
 .. IMPORTANT::
 
-   If you are not using PHP 7.4, be sure to update the `ExecStart` filepath
-   in the `[Service]` section of  the sample configuration block above!
-   Currently it assumes PHP 7.4 is being used, and will not  work for
+   If you are not using PHP 8.3, be sure to update the `ExecStart` filepath
+   in the `[Service]` section of the sample configuration block above!
+   Currently it assumes PHP 8.3 is being used, and will not work for
    installations using a different PHP version without modification.
 
 Now reload systemd, enable and start the AtoM worker:
@@ -561,10 +563,10 @@ scales better than other solutions like FastCGI.
 
 .. code-block:: bash
 
-   sudo apt install php7.4-fpm
+   sudo apt install php-fpm
 
 Let's add a new PHP pool for AtoM by adding the following contents in a new
-file called :file:`/etc/php/7.4/fpm/pool.d/atom.conf`:
+file called :file:`/etc/php/8.3/fpm/pool.d/atom.conf`:
 
 .. code-block:: ini
 
@@ -575,7 +577,7 @@ file called :file:`/etc/php/7.4/fpm/pool.d/atom.conf`:
    group = www-data
 
    ; Use UNIX sockets if Nginx and PHP-FPM are running in the same machine
-   listen = /run/php7.4-fpm.atom.sock
+   listen = /run/php-fpm.atom.sock
    listen.owner = www-data
    listen.group = www-data
    listen.mode = 0600
@@ -630,23 +632,23 @@ The process manager has to be enabled and started:
 
 .. code-block:: bash
 
-   sudo systemctl enable php7.4-fpm
-   sudo systemctl start php7.4-fpm
+   sudo systemctl enable php8.3-fpm
+   sudo systemctl start php8.3-fpm
 
 If the service fails to start, make sure that the configuration file has been
 has been pasted properly. You can also check the syntax by running:
 
 .. code-block:: bash
 
-   sudo php-fpm7.4 --test
+   sudo php-fpm8.3 --test
 
 If you are not planning to use the default PHP pool (``www``), feel free to
 remove it:
 
 .. code-block:: bash
 
-   sudo rm /etc/php/7.4/fpm/pool.d/www.conf
-   sudo systemctl restart php7.4-fpm
+   sudo rm /etc/php/8.3/fpm/pool.d/www.conf
+   sudo systemctl restart php8.3-fpm
 
 .. _installation-ubuntu-serve-nginx:
 
@@ -704,7 +706,7 @@ contents in :file:`/etc/nginx/sites-available/atom`.
 .. code-block:: nginx
 
    upstream atom {
-      server unix:/run/php7.4-fpm.atom.sock;
+      server unix:/run/php-fpm.atom.sock;
    }
 
    server {
@@ -796,7 +798,7 @@ information on your first steps using AtoM.
 :ref:`Back to top <installation-ubuntu>`
 
 
-.. _`Ubuntu 20.04 LTS (Focal Fossa)`: http://releases.ubuntu.com/focal/
+.. _`Ubuntu 24.04 LTS (Noble Numbat)`: http://releases.ubuntu.com/noble/
 .. _`repositories`: https://help.ubuntu.com/community/Repositories/Ubuntu
 .. _`download section`: http://www.accesstomemory.org/download
 .. _`public repository`: https://github.com/artefactual/atom

admin-manual/installation/upgrading.rst

@@ -54,15 +54,14 @@ purpose of the release and how best to install it.
 Make sure the dependencies are updated
 ======================================
 
-Since the 2.5 version, AtoM uses Elasticsearch 5.x. If you're upgrading from an
+As of version 2.9, AtoM uses Elasticsearch 6.8. If you're upgrading from an
 earlier version, please make sure to upgrade your Elasticsearch installation.
 You don't need to backup your index data as it will be recreated from the
 database later in the upgrade.
 
-You will also need to upgrade to Java 8 if the system is using a previous
-version, as this is a requirement for Elasticsearch 5.x.
+Elasticsearch is built using Java, and requires at least Java 8 in order to run.
 
-Since the 2.6 version, AtoM requires MySQL 8.0. Bellow we'll explain the steps
+Since the 2.6 version, AtoM requires MySQL 8.0. Below we'll explain the steps
 needed to move and upgrade the AtoM database to properly work with that version.
 
 Install the latest version of AtoM
@@ -313,7 +312,7 @@ and the atom-workers managed by the job scheduler.
 
 .. code-block:: bash
 
-   sudo systemctl restart php7.4-fpm
+   sudo systemctl restart php8.3-fpm
 
 **Optionally, to restart Memcached**:
 
@@ -494,7 +493,7 @@ To restart PHP-FPM:
 
 .. code-block:: bash
 
-   sudo systemctl restart php7.4-fpm
+   sudo systemctl restart php8.3-fpm
 
 If you are using Memcached with AtoM, you may also want to restart it:
 

admin-manual/maintenance/cli-tools.rst

@@ -2441,7 +2441,7 @@ there is also a ``--demo`` option available:
    .. code-block:: bash
 
       php symfony cc
-      sudo systemctl restart php7.4-fpm
+      sudo systemctl restart php8.3-fpm
 
    Optionally, if you're using Memcached as cache engine:
 

admin-manual/maintenance/debug.rst

@@ -17,54 +17,6 @@ To diagnose AtoM application errors it is usually useful to run in Debug mode
 (though the types of messages displayed is subject to your PHP error reporting
 configuration setting), as well as displaying a debug toolbar.
 
-There are two methods for enabling Debug mode for AtoM.
-
-Using qubit_dev.php
--------------------
-
-Using the "qubit_dev.php"
-`front controller <http://en.wikipedia.org/wiki/Front_Controller_pattern>`_
-for AtoM is the simplest way see debugging information, as it only involves a
-simple change to the web address (URL) used to access the application. For
-instance:
-
-.. code:: bash
-
-   http://www.example.com/atom/informationobject/browse
-
-becomes
-
-.. code:: bash
-
-   http://www.example.com/atom/qubit_dev.php/informationobject/browse
-
-
-.. important::
-
-    Access to "qubit_dev.php" is limited to the server (localhost) IP address
-    by default. This means that to access the 'qubit_dev.php' page you must be
-    running a web-browser on the actual server that is hosting the AtoM
-    application. If this is not the case you will see an error message:
-
-    **You are not allowed to access this file. Check qubit_dev.php for more
-    information.**
-
-A :term:`developer` can edit the PHP configuration file (frequently located at
-``/etc/php/7.4/fpm/pool.d/atom.conf``) to add further IP addresses to the
-``ATOM_DEBUG_IP`` variable - this is called by ``qubit_dev.php`` and checked
-for allowed IP addresses. Doing so will allow you to access Debug mode from a
-different IP address than that of the server.
-
-.. image:: images/debug-ip.*
-   :align: center
-   :width: 85%
-   :alt: an image of the ATOM_DEBUG_IP variable in the php configuration file
-
-After making changes to the ``ATOM_DEBUG_IP`` variable in ``atom.conf``, you
-will need to restart PHP-FPM. See: 
-
-* :ref:`troubleshooting-restart-php-fpm`
-
 Editing the index.php file
 --------------------------
 
@@ -87,12 +39,12 @@ comfortable editing files, please contact your system administrator.
    $configuration = ProjectConfiguration::getApplicationConfiguration('qubit',
    'prod', false);
 
-3. Update the "false" flag to "true"
+3. Update the "prod" environment to "dev" and "false" flag to "true"
 
 .. code:: bash
 
    $configuration = ProjectConfiguration::getApplicationConfiguration('qubit',
-   'prod', true);
+   'dev', true);
 
 4. Save the index.php file