Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/vufind-org/vufind/llms.txt

Use this file to discover all available pages before exploring further.

VuFind releases follow a regular cadence of minor and major versions. Upgrading involves replacing the application code, migrating configuration files, applying database schema changes, and re-running any Solr index rebuilds that the new version requires. Following the steps in order prevents data loss and reduces downtime.

​
Before you start

Always test an upgrade on a staging environment before applying it to production. A failed upgrade that touches the database or Solr index may be difficult to roll back.

​
Check compatibility

Review the release notes for every version between your current version and the target version. Pay particular attention to:
  • Removed or renamed configuration keys
  • Changes to the Solr schema that require reindexing
  • PHP version requirements
  • New required PHP extensions or Composer dependencies

​
Identify your current version

grep "'version'" $VUFIND_HOME/module/VuFind/src/VuFind/Config/Version.php

​
Step 1 — Back up your installation

Back up all three layers before touching any files.
1

Back up the database

# MySQL / MariaDB
mysqldump -u vufind -p vufind > /backup/vufind-db-$(date +%Y%m%d).sql

# PostgreSQL
pg_dump -U vufind vufind > /backup/vufind-db-$(date +%Y%m%d).sql
2

Back up your local configuration directory

cp -r "$VUFIND_LOCAL_DIR" "/backup/vufind-local-$(date +%Y%m%d)"
3

Back up the Solr data directory

Solr data can be large. A file-system snapshot or Solr replication backup is preferable to a file copy, but a simple copy works for smaller collections:
# Stop Solr first to ensure a consistent backup
$VUFIND_HOME/solr.sh stop
cp -r "$VUFIND_HOME/solr/vufind" "/backup/vufind-solr-$(date +%Y%m%d)"
$VUFIND_HOME/solr.sh start

​
Step 2 — Install the new VuFind code

cd $VUFIND_HOME
git fetch origin
git checkout v10.0.0   # replace with the target tag
composer install --no-dev
Do not replace the running installation until the upgrade commands have been run and tested. If you extracted a new release archive, keep the old directory intact until you are confident the upgrade is complete.

​
Step 3 — Upgrade configuration files

The upgrade/config command compares your local configuration files against the new defaults, migrates settings that have moved or been renamed, and reports keys that could not be migrated automatically. 
php $NEW_VUFIND_HOME/public/index.php upgrade/config \
    --from 9.0 \
    --olddir "$VUFIND_LOCAL_DIR" \
    --newdir "$VUFIND_LOCAL_DIR"
Replace 9.0 with your current VuFind version number.
1

Run the config upgrade command

php $VUFIND_HOME/public/index.php upgrade/config \
    --from <old-version> \
    --olddir "$VUFIND_LOCAL_DIR" \
    --newdir "$VUFIND_LOCAL_DIR"
2

Review the output

The command prints a summary of changes applied and a list of conflicts — settings it could not migrate automatically. Each conflict must be resolved manually.
3

Resolve conflicts manually

Open the flagged configuration files and apply the changes described in the release notes. Common conflict sources include:
  • Settings removed in the new version (safe to delete)
  • Settings whose accepted values have changed (update the value)
  • New required settings with no obvious default (read the release notes)
4

Verify theme overrides

If you have a custom theme, check that template files that override core templates are still compatible. New releases sometimes change template variables or .phtml template structure.

​
Step 4 — Apply database migrations

The upgrade/database command applies all pending schema migrations in order. It is safe to run against a database that is already partially migrated — it skips migrations that have already been applied. 
php $VUFIND_HOME/public/index.php upgrade/database
For automated deployments where interactive prompts are not possible: 
php $VUFIND_HOME/public/index.php upgrade/database --no-interaction
Run upgrade/database against a backup copy of the database first when upgrading across multiple major versions. Some migrations modify or drop columns and cannot be reversed.

​
What the migration command does

  • Reads all migration classes from module/VuFind/src/VuFind/Db/Migration/
  • Compares the list against migrations already recorded in the vufind_migration table
  • Applies any outstanding migrations in version order
  • Records each successful migration so re-running the command is idempotent

​
Step 5 — Rebuild the Solr index (if required)

Check the release notes to determine whether the new version changes the Solr schema. If it does, a full reindex is required.
1

Replace Solr configuration files

The new Solr schema, synonyms files, and solrconfig.xml are shipped with VuFind. Copy them into place:
# If you have local Solr overrides, merge them back after copying
cp -r $VUFIND_HOME/solr/vufind/biblio/conf \
      $VUFIND_HOME/solr/vufind/biblio/conf.bak
2

Stop Solr and clear index data

$VUFIND_HOME/solr.sh stop
rm -rf $VUFIND_HOME/solr/vufind/biblio/index
rm -rf $VUFIND_HOME/solr/vufind/biblio/tlog
3

Start Solr with the new configuration

$VUFIND_HOME/solr.sh start
4

Re-import all records

$VUFIND_HOME/import-marc.sh /path/to/full-dump.mrc
5

Rebuild the alphabetic browse index

$VUFIND_HOME/index-alphabetic-browse.sh

​
Step 6 — Test after upgrade

Run a basic smoke test before returning the site to users.
1

Verify the application loads

Open the VuFind home page in a browser and confirm no PHP errors or missing templates are displayed.
2

Run a test search

Search for a known record and confirm the result appears with the expected fields.
3

Test authentication

Log in with a test account and confirm that saved searches and favourites are intact.
4

Check the alphabetic browse

Navigate to the A-to-Z browse for titles and authors to confirm the SQLite databases were built correctly.
5

Review the application log

tail -n 100 $VUFIND_LOCAL_DIR/logs/vufind.log
Look for ERROR or CRITICAL entries that indicate runtime problems.

​
Common upgrade issues

This is most commonly caused by a Composer dependency version mismatch. Run composer install --no-dev in $VUFIND_HOME to ensure all dependencies match the new lockfile. Also check that the PHP version meets the new minimum requirement.
The --from value must exactly match a version string that VuFind’s upgrade logic recognises. Use the version string from Version.php in the old installation (e.g. 9.0, 9.1, 10.0).
A migration may have been partially applied during a previous failed upgrade attempt. Check the vufind_migration table for any migrations that are recorded as complete but left the schema in an inconsistent state. You may need to manually correct the schema and insert or delete rows from vufind_migration before retrying.
SELECT * FROM vufind_migration ORDER BY migration_id;
If the Solr schema changed and you did not reindex, searches may return zero results or throw errors. Check the Solr Admin UI (http://localhost:8983/solr) for schema mismatch warnings, then follow the full reindex procedure in Step 5.
Run index-alphabetic-browse.sh and check for errors in its output. Common causes are: Solr not running, the alphabetical_browse/ directory being unwritable, or the Java classpath not finding the required .jar files.
$VUFIND_HOME/index-alphabetic-browse.sh 2>&1 | tee /tmp/browse-build.log
New VuFind releases sometimes change template variable names or .phtml block structure. Compare your overriding templates against the updated base templates using diff to identify incompatibilities:
diff $VUFIND_HOME/themes/bootstrap5/templates/search/results.phtml \
     $VUFIND_LOCAL_DIR/themes/mytheme/templates/search/results.phtml

Build docs developers (and LLMs) love

Get started for freeTalk to us