How to Extract, Unpack and Restore Akeeba .jpa Backup Files — No Technical Knowledge Required

Take an Akeeba Backup file. Put it in a folder. Paste one prompt into Claude Code. Click Yes a few times. Your entire Joomla site — every article, every user, every forum post, every template setting — is running on your machine in under a minute. No server configuration. No database imports. No PHP version headaches. Just a working clone of your live site.

This is not theoretical. We tested it. Backup from one Docker environment, restore to a completely fresh one. 126 database tables. 77 articles. 835 forum messages. 100+ user accounts. All of it, intact and functional, with a single prompt.

And it works with Akeeba Backup Core (free). You don’t need Pro.

Why This Matters

Every Joomla administrator has been there. Your hosting provider changes something. An update goes sideways. You need to test a major change but you’re terrified of breaking production. Or you simply want a local copy of your live site to work on.

The traditional restore process involves:

1. Downloading Akeeba Kickstart
2. Setting up a local web server (XAMPP, MAMP, or similar)
3. Creating a MySQL database manually
4. Configuring PHP extensions
5. Running through Kickstart’s multi-step wizard
6. Fixing configuration.php paths
7. Troubleshooting PHP version mismatches
8. Dealing with MariaDB vs MySQL collation errors

Most people give up somewhere around step 4.

The AI Alternative: One Prompt, One Click

Here is what the entire process looks like now:

1. Create a new folder on your computer
2. Put your .jpa backup file in it
3. Open the folder in VS Code
4. Open Claude Code (the AI assistant built into VS Code)
5. Paste the prompt below
6. Approve the commands Claude asks to run
7. Open http://localhost:8080

That’s it. Claude handles the Docker containers, the file extraction, the multi-part SQL dump reassembly, the collation fixes, the configuration patching, everything.

What You Need

If you don’t have Docker installed, Claude will detect that and tell you exactly how to install it for your operating system. One terminal command on Linux, a download link on Mac and Windows.

The Prompt

Copy this entire block and paste it into Claude Code. The only thing you might want to change is the port number (default 8080) if you already have something running on that port.

# Akeeba JPA Restore Prompt — TheAIDirector.Win
# https://theaidirector.win

I have an Akeeba Backup .jpa file in this folder. Restore it to a working
Joomla site running in Docker on localhost.

Before you start, check if Docker is installed by running: docker --version
If Docker is not installed, tell me how to install it for my OS.

Steps:
1. Find the .jpa file in this folder
2. Write a Python script that:
   - Extracts the JPA archive (handle JPF entities, JP01/JP02 headers,
     gzip decompression)
   - Reads databases.json from installation/sql/ for prefix and part count
   - Concatenates SQL parts in correct order: .sql FIRST, then .s01, .s02 etc
   - Replaces #__ with the actual prefix
   - Strips /**ABDB**/ markers
   - Fixes MariaDB collations (utf8mb3_uca*_ai_ci to utf8mb3_general_ci)
   - Creates a docker-compose.yml with MySQL 8 + Joomla (latest image)
   - Map the site to port 8080 (change this if 8080 is already in use)
   - Starts containers, waits for MySQL + DB user to be ready
   - Copies extracted files into the Joomla container
   - Imports the processed SQL with sql_mode=NO_ENGINE_SUBSTITUTION
   - Patches configuration.php (host, user, password, db, paths)
   - Removes the installation/ folder
   - Prints the site URL when done
3. Run the script
4. Tell me the admin password reset command when done

What Happens Behind the Scenes

When Claude receives this prompt, it does roughly what a senior DevOps engineer would do — but in about 45 seconds:

1. Extracts the JPA binary format — Akeeba uses its own archive format with JPF file entities, JP01 span headers, and JP02 extra headers. Claude parses all of these correctly.
2. Reassembles the multi-part SQL dump — Akeeba splits large databases across multiple files (site.sql, site.s01, site.s02, etc.). The critical detail: site.sql is the beginning, not the end. Get the order wrong and your import fails silently with missing tables.
3. Fixes cross-database compatibility — If your live site runs MariaDB but Docker uses MySQL 8, certain collation types don’t exist. Claude patches these automatically.
4. Handles zero-date fields — MySQL 8’s strict mode rejects 0000-00-00 00:00:00 dates that older Joomla extensions use. Claude sets the correct SQL mode.
5. Patches configuration.php — Database host, username, password, paths — all updated to match the Docker environment.

Tested and Verified

We didn’t just write this and hope it works. We tested a full cycle:

1. Took an Akeeba backup from a live Joomla 5/6 site (18,077 files, 117 MB uncompressed)
2. Restored it to a fresh Docker environment — 126 tables imported, HTTP 200
3. Tested admin login, article creation, article editing, article deletion
4. Verified all Kunena forum data (835 messages across 33 topics)
5. Verified all user accounts (100+ users with correct groups)
6. Ran Joomla CLI commands: user:list, extension:list, finder:index, scheduler:list, maintenance:database
7. Took a new Akeeba backup from the restored site
8. Restored that backup to yet another fresh Docker environment
9. Everything worked. Perfect clone of a clone.

After the Restore

Once your site is running, you can:

• Reset the admin password:
  docker exec joomla-restore-app php /var/www/html/cli/joomla.php user:reset-password --username=admin --password=’YourNewPassword123!’
• Take a new backup:
  docker exec joomla-restore-app php /var/www/html/cli/joomla.php akeeba:backup:take
• Run database maintenance:
  docker exec joomla-restore-app php /var/www/html/cli/joomla.php maintenance:database
• Rebuild the search index:
  docker exec joomla-restore-app php /var/www/html/cli/joomla.php finder:index

Claude knows all of these commands. Just ask.

Works on Every Platform

The restore script is pure Python — no platform-specific code. Docker abstracts away the server environment. It doesn’t matter what OS you run.

Akeeba Backup Free vs Pro

Good news: Akeeba Backup Core (free) creates .jpa files. The JPA format is the same in both editions. The only difference relevant to this workflow is that CLI backups (akeeba:backup:take) require Pro. But you can take the backup through the Joomla admin panel with the free version and download the .jpa file manually.

For the restore side, our script handles both free and Pro backups identically. The .jpa format, the SQL dump structure, the databases.json metadata — all the same regardless of which edition created the backup.

What About Akeeba Kickstart?

Akeeba Kickstart is Akeeba’s official restore tool, and it’s excellent. This approach doesn’t replace it — it’s an alternative for people who:

• Want a fully automated restore without clicking through a wizard
• Need a local Docker development environment rather than a server restore
• Want to test template changes, extensions, or updates safely
• Don’t want to install XAMPP, MAMP, or configure a local web server manually

Kickstart is designed for server-to-server restores. This is designed for “give me a working local copy of my site in under a minute.”

The Technical Details (For Those Who Care)

The JPA (Joomla Pack Archive) format is publicly documented by Akeeba and explicitly royalty-free for any use. Our extraction code is original — written from scratch based on the public specification, with additional handling for:

• JP02 extra headers (which some community extractors miss)
• Multi-part SQL dump reassembly with correct ordering
• Path traversal protection during extraction
• MariaDB-to-MySQL collation mapping
• MySQL strict mode compatibility

The entire restore script is ~200 lines of Python with zero external dependencies beyond the standard library. No pip install required.

Try It

Take a backup of your Joomla site right now. Put the .jpa file in a folder. Open VS Code. Paste the prompt. See what happens.

The worst case scenario is you learn something about Docker. The best case is you never worry about Joomla restores again.

Built with AI. Published at TheAIDirector.Win.