Overview

This is a personal note on updating Omeka S. Please also refer to the following official documentation.

https://omeka.org/s/docs/user-manual/install/#updating

Preparation: Backup

Before performing update operations, be sure to create backups of the database and all files in case of unforeseen circumstances.

1. Database Backup Create a database dump file using the mysqldump command or similar.

# mysqldump -u [DB username] -p [DB name] > [output filename]
mysqldump -u db_user -p omeka_s_db > omeka_s_backup.sql

2. File Backup Back up (duplicate) the entire Omeka S installation directory.

cd /home/nakamura/www
# When copying the entire directory (adding a date is convenient)
cp -r omeka-s omeka-s_backup_20240801

# Or, when compressing and saving with tar
# tar -czvf omeka-s_backup_20240801.tar.gz omeka-s

Maintenance Mode

Before updating, switch to maintenance mode.

Install the following EasyAdmin module.

https://omeka.org/s/modules/EasyAdmin/

Then, access the settings page from the “Settings” button.

/admin/setting

For the “Maintenance” item, check “Public front-end” for example and save.

As a result, the maintenance page will be displayed.

Updating the Core and Default Theme

Navigate to the directory where Omeka S is installed and execute the following.

cd /home/nakamura/www/omeka-s

Below is an example of updating to v4.1.1.

version=4.1.1
wget https://github.com/omeka/omeka-s/releases/download/v$version/omeka-s-$version.zip
unzip omeka-s-$version.zip
rm -rf *.zip
rm -rf application
rm -rf vendor
mv omeka-s/application .
mv omeka-s/*.php .
mv omeka-s/composer.* .
mv omeka-s/LICENSE .
mv omeka-s/README.md .
mv omeka-s/vendor .
rm -rf ./themes/default
mv omeka-s/themes/default ./themes/
rm -rf omeka-s

When you access /admin, you will be redirected to /migrate and the following screen will be displayed. Press the “Update Database” button.

If you navigate to the admin screen and see “Migrated”, the update was successful.

Updating Modules

Update modules as well.

Modules that can be updated will be displayed as shown. Additionally, when updating from Omeka S v3 to v4, there may be cases where modules cannot be run without updating due to version incompatibilities.

First, navigate to the modules directory.

cd /home/nakamura/www/omeka-s/modules

Then, create a file with the following content. Change the target modules as appropriate.

#!/bin/bash

# Store module name and URL pairs in an array
declare -a modules=(
    "Common https://github.com/Daniel-KM/Omeka-S-module-Common/releases/download/3.4.61/Common-3.4.61.zip"
    "BulkExport https://github.com/Daniel-KM/Omeka-S-module-BulkExport/releases/download/3.4.34/BulkExport-3.4.34.zip"
    "CleanUrl https://github.com/Daniel-KM/Omeka-S-module-CleanUrl/releases/download/3.17.7/CleanUrl-3.17.7.zip"
    "Log https://github.com/Daniel-KM/Omeka-S-module-Log/releases/download/3.4.24/Log-3.4.24.zip"
    "BulkImport https://github.com/Daniel-KM/Omeka-S-module-BulkImport/releases/download/3.4.56/BulkImport-3.4.56.zip"
    "FacetedBrowse https://github.com/omeka-s-modules/FacetedBrowse/releases/download/v1.5.1/FacetedBrowse-1.5.1.zip"
    "IiifServer https://github.com/Daniel-KM/Omeka-S-module-IiifServer/releases/download/3.6.21/IiifServer-3.6.21.zip"
    "ImageServer https://github.com/Daniel-KM/Omeka-S-module-ImageServer/releases/download/3.6.18/ImageServer-3.6.18.zip"
    "IiifViewers https://github.com/nakamura196/Omeka-S-module-IiifViewers/releases/download/1.2.5/IiifViewers-1.2.5.zip"
    "Reference https://github.com/Daniel-KM/Omeka-S-module-Reference/releases/download/3.4.49/Reference-3.4.49.zip"
    "EasyAdmin https://github.com/Daniel-KM/Omeka-S-module-EasyAdmin/releases/download/3.4.20/EasyAdmin-3.4.20.zip"
)

# Loop through each element of the array
for module in "${modules[@]}"; do
    # Split module name and URL
    read -r MODULE_NAME MODULE_URL <<< "$module"

    echo "Processing $MODULE_NAME from $MODULE_URL"

    # Delete existing module directory
    rm -rf "$MODULE_NAME"

    # Download the module zip file
    wget "$MODULE_URL"

    # Get the zip file name
    ZIP_FILE=$(basename "$MODULE_URL")

    # Unzip the file and then delete the zip
    unzip "$ZIP_FILE"
    rm "$ZIP_FILE"
done

Then, execute the following.

bash upgrade.sh

As a result, an “Upgrade” button will be displayed for updated modules, so press the button. Note that recent modules often require the “Common” module to be installed beforehand, so it is recommended to install it first.

Summary

Finally, disable maintenance mode to complete the update process.

Since errors may occur during the update process, it may be helpful to change the settings in the .htaccess file as follows. Also, don’t forget to switch back to production mode after completing the update.

# SetEnv APPLICATION_ENV "production"
SetEnv APPLICATION_ENV "development"
...

I hope this serves as a useful reference for operating Omeka S.

Update History

  • 2026/02/06: Added backup procedure
  • 2024/08/01: Article published