Backups and Recovery

This content was generated with the assistance of AI and should be verified against the official Joomla documentation before being relied on in production.

This sub-section’s Joomla bibliography lists the reference material consulted while preparing these pages.

A backup is only worth the last time somebody restored it. Joomla keeps a site in two places, the files under the web root and the database, and a third small item, configuration.php, ties them together. This page, checked on 2026-10-30, covers Joomla 6.2.x on PHP 8.3 or later. It shows what to save, how to save it with the command line, with plain database and file tools and with Akeeba Backup, how to rehearse a restore for the Tallpine Hiking Club site (package pkg_tallpine, component com_tallpine, child template cassiopeia_tallpine), and how to recover when an extension locks you out of the administrator by editing the database directly.

For the container tooling used in the examples see Docker volumes and bind mounts and Kubernetes Jobs and CronJobs; for the CLI itself see Command Line Interface.

What to back up

The User Guide describes a Joomla site as two parts: the files in the Joomla root directory, which change little between updates, and the database, which changes whenever content is added or edited. A usable backup holds both, taken close enough in time to match.

Part Contents Notes

Database

Articles, categories, users, menus, extension rows (#__extensions), configuration of modules and plugins, the Smart Search index, action logs.

Changes constantly. Back it up most often. Tables share a prefix defined by $dbprefix in configuration.php.

Files

Core files, installed extensions, templates (including cassiopeia_tallpine), template overrides, language overrides, and the images folder that the Media Manager fills (for example the gpx-file uploads of the trail reports).

Core files can be reinstalled, but uploads and custom code cannot. Under the public-folder layout of Joomla 6 the web root is a subfolder, so back up the parent as well (see Installation and the public folder).

configuration.php

Database host, name, user, password and prefix, the $secret value, mail, session and cache settings.

A file, so it is part of the file backup, but it deserves its own care: it contains credentials, and a restore on a new server needs its database settings edited.

Two further items are easy to miss. First, anything the site generates on demand, such as the cache and tmp folders, the administrator cache and compiled assets, can be rebuilt and need not be kept. Second, data held outside the site, such as a Redis session store or object cache (see Redis), a reverse-proxy cache, or files on a separate object-storage bucket, must be covered by that service’s own backup, or be accepted as disposable. A site that is only half restored (database from Tuesday, uploads from Friday) shows broken image links and missing attachments, which is why the two parts should be taken together.

Hosting snapshots help but should not be the only recovery method: they live with the same provider as the site, and their consistency between database and files is not guaranteed.

Backing up the database from the command line

Joomla ships console commands that export and import database tables, run through the entry point cli/joomla.php at the site root:

# Show the options the installed version supports
php cli/joomla.php database:export --help

# Export every table into a folder, one file per table
php cli/joomla.php database:export --folder /var/backups/tallpine/db-2026-10-30

# Export a single table
php cli/joomla.php database:export --table tp_banners --folder /var/backups/tallpine/db-2026-10-30

# Import every exported table from a folder
php cli/joomla.php database:import --folder /var/backups/tallpine/db-2026-10-30

# Import a single exported table (path to the exported file, without extension)
php cli/joomla.php database:import --table /var/backups/tallpine/db-2026-10-30/tp_banners

Source: Joomla User Guide: Using the CLI

How these commands behave matters when they are used for backups:

  • The export writes one file per table, and the import reads those files back. If a file is missing, the import reports that the expected XML file does not exist.

  • The User Guide documents --table and --folder. Other options may exist in a given release; run --help on the installed version rather than relying on a tutorial.

  • The User Guide warns against using the database import on the complete set of tables of a multilingual site, because it could stop Smart Search working completely. For a multilingual site such as the Tallpine club (English and German, see Multilingual Sites), prefer a native database dump for full restores and use the CLI import for individual tables.

  • The command runs as the operating-system user who invoked it, with the database credentials from configuration.php, so run it as the web-server user or the site owner and keep the destination folder outside the web root. A backup folder reachable by URL leaks the whole site.

  • The commands operate on the tables of the current prefix; they are a convenience for small and medium sites and for moving individual tables, not a replacement for the database server’s own tools on a large site.

Native dumps

A dump from the database server is a single consistent file and is the better default for a full backup:

# MariaDB or MySQL; credentials come from a protected option file, not the command line
mariadb-dump --defaults-extra-file=/etc/tallpine/backup.cnf \
  --single-transaction --routines --default-character-set=utf8mb4 \
  tallpine > /var/backups/tallpine/tallpine-$(date +%F).sql
gzip /var/backups/tallpine/tallpine-$(date +%F).sql

Source: Joomla User Guide: Backup

--single-transaction gives a consistent snapshot of InnoDB tables without locking the site, and utf8mb4 avoids corrupting emoji and non-Latin text, which Joomla stores in that character set. Keep the password in the option file (mode 600) or in an environment variable, never in the command line, where it shows in the process list. The User Guide also mentions phpMyAdmin’s export and recommends testing an export by importing it into a new database, which is the heart of the restore drill below.

Backing up the files

Plain file tools are enough because Joomla has no hidden state outside the tree and the database:

tar --exclude='./cache/*' --exclude='./tmp/*' --exclude='./administrator/cache/*' \
  -czf /var/backups/tallpine/files-$(date +%F).tar.gz -C /var/www/tallpine .

# Incremental copy of the uploads only, on a schedule
rsync -a --delete /var/www/tallpine/images/ backup-host:/srv/backups/tallpine/images/

Source: Joomla User Guide: Backup

Preserve ownership and permissions, because a restore as the wrong user is a common cause of "cannot write to the tmp folder" errors. In containers the files live in volumes: with the official joomla image of the local setup (see Local Development with Docker) the site and the database are separate volumes, and each is saved with its own mechanism.

services:
  backup:
    image: mariadb:11
    profiles: ["backup"]
    depends_on: [db]
    volumes:
      - joomla_data:/var/www/html:ro
      - ./backups:/backups
    environment:
      MARIADB_PASSWORD_FILE: /run/secrets/db_password
    secrets: [db_password]
    entrypoint: ["/bin/sh", "-c"]
    command:
      - >
        mariadb-dump -h db -u tallpine --password="$$(cat /run/secrets/db_password)"
        --single-transaction tallpine > /backups/tallpine-$$(date +%F).sql &&
        tar -czf /backups/files-$$(date +%F).tar.gz -C /var/www/html .
volumes:
  joomla_data: {}
secrets:
  db_password:
    file: ./secrets/db_password.txt

Source: Docker Hub: joomla (Docker Official Image)

Run it on demand with docker compose --profile backup run --rm backup. In Kubernetes the same two commands become a CronJob writing to a persistent volume or object storage (see Persistent volumes); a volume snapshot of the database without a dump is crash-consistent at best.

Backup extensions: Akeeba Backup

Akeeba Backup is a third-party extension (not part of the Joomla project, and not affiliated with it) and the best-known backup tool of the ecosystem. The User Guide names it as a free extension that creates a single archive of the files and the database, stored as a .jpa file, restored with Akeeba Kickstart and the Akeeba installer. According to the vendor, the free Core edition offers one-click backups, self-contained archives, ACL permissions, local quota management and manual transfer with Kickstart. The Pro edition adds automatic backups (through the CLI, Joomla Scheduled Tasks or the legacy front-end), cloud storage targets such as Amazon S3, Dropbox and Google Drive, remote quota management, restore from within the component, encrypted archives and incremental files-only backups. Archives are ZIP (including split ZIP) or JPA; encrypted JPS is Pro only.

Source: Akeeba Backup for Joomla

Considerations when adopting it:

  • Check the vendor’s compatibility information for the Joomla and PHP version before every major upgrade; a backup tool that does not run on the new version is the worst surprise after an upgrade.

  • An archive contains configuration.php and a full database copy, so store it off the web root, restrict download access, and prefer encryption for archives that leave the server. Backup files can be large and fill hosting quotas.

  • Scheduling can be done by the extension itself or by Joomla’s Scheduled Tasks (see Scheduled Tasks) or by a system cron entry; whichever is used, monitor that files actually appear and prune old ones.

  • Older books such as Joomla! 4 Masterclass (2023) present Akeeba as part of the standard workflow. It is a useful option, but the core documentation treats it as one tool among several (host tools, mysqldump, phpMyAdmin), and the Joomla 6 platform leaves you free to use any of them.

The User Guide also notes that many hosts, notably those using cPanel, offer full and partial backups of files and databases with restore options. Treat those as a second copy, not the only one.

The 3-2-1 routine for the Tallpine site

A practical policy for the club site combines the tools above:

Database   nightly   mariadb-dump (single-transaction), 14 daily + 8 weekly retained
Files      nightly   rsync of images/, weekly tar of the whole tree
Config     on change configuration.php copied to the password manager vault / secret store
Copies     3 copies, 2 different media, 1 off-site (object storage with versioning)
Test       monthly   full restore drill on a staging site

Source: Joomla User Guide: Backup

Back up before every risky operation as well: a core update, an extension update, a minor-to-major upgrade (see Updating Joomla and Automated Core Updates and Upgrading Joomla 5 to 6). Sites with Automated Core Updates enabled should take scheduled backups regardless, since an update can run without anyone present.

Restoring and rehearsing a restore

The User Guide’s restore sequence is: clear the faulty site first, restore the database (phpMyAdmin for small databases, the mysql client for larger ones), then restore the files by extracting the archive and check configuration.php for the correct database details. A drill for the club site on a staging host:

# 1. Create an empty database and user for the staging site
mariadb -e "CREATE DATABASE tallpine_stage CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci"

# 2. Load the dump
gunzip -c /var/backups/tallpine/tallpine-2026-10-30.sql.gz | mariadb tallpine_stage

# 3. Extract the files
mkdir -p /var/www/stage && tar -xzf /var/backups/tallpine/files-2026-10-30.tar.gz -C /var/www/stage

# 4. Point configuration.php at the staging database and make caches/paths valid
sed -i "s|public \$db = .*|public \$db = 'tallpine_stage';|" /var/www/stage/configuration.php
sed -i "s|public \$tmp_path = .*|public \$tmp_path = '/var/www/stage/tmp';|" /var/www/stage/configuration.php
sed -i "s|public \$log_path = .*|public \$log_path = '/var/www/stage/administrator/logs';|" /var/www/stage/configuration.php

# 5. Verify
php /var/www/stage/cli/joomla.php list

Source: Joomla User Guide: Backup

Things a drill usually reveals:

  • configuration.php may be read-only (mode 444 after installation, as the User Guide notes); change it to 644 to edit it, then restore the stricter mode. See configuration.php and .htaccess.

  • The absolute paths $tmp_path and $log_path still point at the old server, which makes uploads and logging fail.

  • The $live_site, mail and proxy settings may need to change, and a staging copy should not send real email or trigger real scheduled tasks; use a mail catcher such as the one in the Docker setup.

  • The .htaccess (or web-server rewrite rules) may be missing from an archive made without hidden files.

  • Time the whole procedure and write the figure down. That duration is the real recovery time of the site.

  • Sign in as a Super User, open System, System Information and check that folders are writable and the database version is supported (see System Information, Maintenance and Troubleshooting).

After restoring on a different host, also rebuild the Smart Search index and clear the cache (see Smart Search and Caching and Performance).

Recovering with the database: a disabled plugin

Sometimes the problem is not lost data but a locked door. A plugin that throws an error on every request, or an upgrade step that was done in the wrong order, can make the administrator unreachable, so the plugin can no longer be toggled in the Plugins screen. Because every extension is a row in the #__extensions table (the prefix #__ stands for the $dbprefix value of configuration.php), it can be switched off or on with SQL:

-- Find the row
SELECT extension_id, name, element, folder, enabled
FROM #__extensions
WHERE type = 'plugin' AND element = 'tallpine_conditions' AND folder = 'content';

-- Disable the failing Tallpine plugin
UPDATE #__extensions SET enabled = 0
WHERE type = 'plugin' AND element = 'tallpine_conditions' AND folder = 'content';

-- Re-enable a plugin that was disabled and must be on
UPDATE #__extensions SET enabled = 1 WHERE extension_id = 1234;

Source: Joomla Manual: How plugins work

Replace the placeholder prefix #__ with the real prefix (for example tp_) when running the statement in phpMyAdmin or in the mariadb client; it is only expanded inside Joomla’s database layer. Take a dump first, run the update against a single extension_id, then clear the cache, because plugin lists are cached.

The same technique is the documented rescue in the upgrade from 5.4 to 6. The upgrade requires you to update to the latest 5.4.x, disable the old Behaviour - Backward Compatibility plugin and enable Behaviour - Backward Compatibility 6 (they cannot both be on), and then switch the update channel to Joomla Next. The pre-update check is not a reliable source of truth, so a site can end up with neither plugin active and legacy code failing. Setting enabled back to 1 on the row of the plugin that is needed restores the site. Third-party plugins must never be placed in the behaviour group for this reason.

Source: Joomla Developer Manual: Migration notes

Other rescues of the same kind:

  • A lost Super User password can be reset with the CLI user commands (php cli/joomla.php list user shows what the installed version offers) or by writing a new hashed password to the #__users table; never store the plain text.

  • A lockout caused by multi-factor authentication can be cleared by deleting the user’s rows from the MFA table (#__user_mfa) after confirming the identity of the person, as the owner of the site; see Security Hardening, MFA and Passkeys.

  • An extension that fails after a failed update may need its #__extensions row and #__schemas version checked; see Installer Scripts and SQL Updates.

Database edits bypass Joomla’s validation and action logs, so record each one, and prefer the Administrator screens whenever they are available.

Security and common pitfalls

  • Credentials: configuration.php holds the database password and $secret. In examples and runbooks use environment variables or placeholders such as CHANGE_ME; do not paste a real file into a ticket or a repository. After restoring from an old backup into a new place, rotate the database password and consider changing $secret, which invalidates sessions.

  • Backups in the web root: an .sql or .jpa file left in an accessible folder is a full copy of the site and its users. Store archives outside the document root or deny access in the web-server configuration.

  • Restoring over a newer site: old backups bring old, possibly vulnerable, core and extensions. Update the restored site immediately and check the Joomla Security Centre for advisories.

  • Version mismatch: a database restored from 5.4 into code of 6.2 (or the reverse) breaks until the schema is updated; restore database and files from the same moment.

  • Untested backups: a zero-byte or truncated dump, or an archive missing hidden files, is discovered only during a restore.

  • Personal data: backups contain personal data covered by privacy regulations; retention must match the policy described in Privacy and Action Logs.

  • Documentation age: the legacy wiki at docs.joomla.org has many backup pages written for Joomla 1.5 to 3.x, some marked obsolete. Prefer the current User Guide, and treat shell snippets from older tutorials as starting points.

References