Skip to main content

Restore a Joomla backup using Docker

Easily restore your Joomla website backup locally using Docker, Docker Compose, and Akeeba Kickstart. A simple make import command is all it takes.

· 7 min read
View raw
Christophe
Markdown, WSL and Docker lover ~ Insatiable curious.
Cet article existe aussi en français — lire la version française.

Changelog

Latest
Review and update YAML files to Joomla 6

Restore a Joomla backup using Docker

⚡
TL;DR

This guide explains how to restore a Joomla site locally by combining Docker, an Akeeba Backup archive, and the Akeeba Kickstart utility. Users configure a custom environment with PHP and Apache, then execute a simple import command to deploy the necessary files and containers. The process is completed by accessing the Kickstart wizard in a browser to finalize the database connection and site restoration.

In previous articles (Part 1 and Part 2), we've seen how to create a Joomla site from scratch by using Docker: pull Joomla, PHP, Apache and MySQL from Docker Hub and do magic stuff so we have a fresh http://127.0.0.1:8080 local site.

In this article, we'll see how to restore on our machine, a backup created thanks to great Akeeba Backup component.

We'll reuse some files from Part 2 and make some changes to them.

At the end, we'll have a make import command that will start Akeeba Kickstart.

Result​

Fill in the database info shown in your console, and Akeeba Kickstart takes care of the rest — from a raw .jpa backup to a browsable site:

Akeeba Kickstart

Restoring the database

Site is restored

Why it works​

  • We reuse the same compose.yaml/.env/makefile trio from Part 2, so nothing new to learn there.
  • The only real change: since the backup already is a full Joomla site, the containers only need PHP and Apache, not a fresh Joomla image — the database itself gets rebuilt from the backup by Akeeba Kickstart, not by Joomla's installer.

Creating required files​

Skipping the files creation process

In the next chapters, you'll need to create several files using copy/paste. If you wish to go faster, just run the following commands to retrieve files from my Github repo so you don't need to create them.

>user@machine: ~/yourproject

By following the instructions below, you'll create a xxx folder where you can copy all the files you need to restore a Joomla site using Docker. You can then proceed immediately to the “Run the import process” chapter, as the files are already in place.

If you prefer to understand what you do and create files manually, please continue reading below.

Please create a new folder on your computer like f.i. mkdir /tmp/joomla_restore && cd $_.

>user@machine: ~/yourproject

In that folder, you'll need to create several files (please refer to Part 2) if you need more explanations about these files.

The orchestration file: compose.yaml​

Below, highlighted, small differences from the compose.yaml file we saw in Part 2.

Here is why: this time we don't need to download a fresh copy of Joomla since we already have a Joomla site (our backup). What we need is PHP and Apache. We don't need Joomla, so this time we'll use a custom Docker image, not an already existing one.

Except for the highlighted lines, everything else is the same as in Part 2.

name: ${PROJECT_NAME:-your-project-name}
services:
joomla:
# highlight-next-line
build:
# highlight-next-line
context: .
# highlight-next-line
args:
# highlight-next-line
- PHP_VERSION=${PHP_VERSION:-8.3-apache}
container_name: ${CONTAINER_PREFIX:-joomla}-app
restart: always
ports:
- ${WEB_PORT:-8080}:80
environment:
- JOOMLA_DB_HOST=joomladb
- JOOMLA_DB_NAME=${DB_NAME:-joomla}
- JOOMLA_DB_PASSWORD=${DB_PASSWORD:-examplepass}
- JOOMLA_DB_USER=${DB_USER:-joomla}
depends_on:
joomladb:
condition: service_healthy
user: ${UID:-1000}:${GID:-1000}
volumes:
- ./joomla_data:/var/www/html
networks:
- joomla_network
joomladb:
image: mysql:${MYSQL_VERSION:-latest}
container_name: ${CONTAINER_PREFIX:-joomla}-db
restart: always
ports:
- ${MYSQL_PORT-:3306}:3306
environment:
- MYSQL_DATABASE=${DB_NAME:-joomla}
- MYSQL_PASSWORD=${DB_PASSWORD:-examplepass}
- MYSQL_ROOT_PASSWORD=${DB_ROOT_PASSWORD:-rootpass}
- MYSQL_USER=${DB_USER:-joomla}
healthcheck:
test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
timeout: 20s
retries: 10
user: ${UID:-1000}:${GID:-1000}
volumes:
- ./db_data:/var/lib/mysql
networks:
- joomla_network
phpmyadmin:
image: phpmyadmin
container_name: ${CONTAINER_PREFIX:-joomla}-phpmyadmin
restart: always
depends_on:
joomladb:
condition: service_healthy
ports:
- 8081:80
environment:
- PMA_HOST=joomladb
- PMA_PASSWORD=${DB_ROOT_PASSWORD:-rootpass}
networks:
- joomla_network
networks:
joomla_network:

This Docker Compose file defines a three-container setup for running Joomla with a MySQL database and phpMyAdmin management interface. It uses environment variables with sensible defaults to make the deployment configurable—you can override things like the PHP version, database credentials, and port numbers without editing the file itself. All three services run on the same internal network and the Joomla container waits for the database to be healthy before starting.

The .env file​

As introduced above, we don't need Joomla anymore, just PHP and Apache. We'll then define a PHP_VERSION variable and initialize it to the desired version.

CONTAINER_PREFIX=joomla
DB_NAME=joomla
DB_PASSWORD=examplepass
DB_USER=joomla
MYSQL_PORT=3306
MYSQL_VERSION=8.4.2
// highlight-next-line
PHP_VERSION=8.3-apache
PROJECT_NAME=running-joomla-in-docker
WEB_PORT=8080

This script sets up configuration variables for a Docker-based Joomla installation. It defines the database credentials, MySQL version, PHP version, port mappings, and project name that will be used when spinning up containers. These variables are typically sourced by other scripts that actually build and run the Docker environment.

Caution

Since we need to restore an existing site, make sure to use the same PHP version as the one used by your site.

Our makefile​

We'll need a new action called import:

-include .env
config:
@UID=$$(id -u) GID=$$(id -g) docker compose config
down: stop
-@UID=$$(id -u) GID=$$(id -g) docker compose down
log:
-@UID=$$(id -u) GID=$$(id -g) docker compose logs
reset: down
-@rm -rf db_data joomla_data
start:
@clear
@printf "\033[1;33m%s\033[0m\n\n" "To start your site, please jump to http://127.0.0.1:${WEB_PORT}"
@printf "\033[1;33m%s\033[0m\n\n" "Go to http://127.0.0.1:${WEB_PORT}/administrator to open your backend."
@printf "\033[1;104m%s\033[0m\n\n" "Below a summary of your current installation:"
@printf "\033[1;34m%s\033[0m\n\n" "JOOMLA"
@printf "\033[1;34m%-30s\033[0m\033[1;104m%s\033[0m\n" " * Project name" "${PROJECT_NAME}"
@printf "\033[1;34m%-30s\033[0m\033[1;104m%s\033[0m\n" " * Version" "${JOOMLA_VERSION}"
@printf "\033[1;34m%-30s\033[0m\033[1;104m%s\033[0m\n\n" " * Port" "${WEB_PORT}"
@printf "\033[1;34m%s\033[0m\n\n" "DATABASE"
@printf "\033[1;34m%-30s\033[0m\033[1;104m%s\033[0m\n" " * Host" "joomla-db"
@printf "\033[1;34m%-30s\033[0m\033[1;104m%s\033[0m\n" " * User name" "${DB_USER}"
@printf "\033[1;34m%-30s\033[0m\033[1;104m%s\033[0m\n" " * Password" "${DB_PASSWORD}"
@printf "\033[1;34m%-30s\033[0m\033[1;104m%s\033[0m\n" " * Database name" "${DB_NAME}"
@printf "\033[1;34m%-30s\033[0m\033[1;104m%s\033[0m\n" " * Version" "${MYSQL_VERSION}"
@printf "\033[1;34m%-30s\033[0m\033[1;104m%s\033[0m\n\n" " * Port" "${MYSQL_PORT}"
stop:
-@UID=$$(id -u) GID=$$(id -g) docker compose stop
up:
-@mkdir -p db_data joomla_data
@UID=$$(id -u) GID=$$(id -g) docker compose up --detach --build
# highlight-next-line
import: reset
# highlight-next-line
-@mkdir -p db_data joomla_data
# highlight-next-line
# highlight-next-line
@clear
# highlight-next-line
@printf "\033[1;33m%s\033[0m\n" "Copying Akeeba Kickstart to the Docker Joomla container..."
# highlight-next-line
@cp en-GB.kickstart.ini ./joomla_data
# highlight-next-line
@cp kickstart.php ./joomla_data/kickstart.php
# highlight-next-line
# highlight-next-line
@printf "\033[1;33m%s\033[0m\n\n" "Copying your backup to the Docker Joomla container..."
# highlight-next-line
@cp backup.jpa ./joomla_data
# highlight-next-line
# highlight-next-line
@UID=$$(id -u) GID=$$(id -g) docker compose up --detach
# highlight-next-line
# highlight-next-line
@printf "\n\n\033[1;33m%s\033[0m\n\n" "Please now jump to http://127.0.0.1:${WEB_PORT}/kickstart.php to finalize your site restoration."
# highlight-next-line
# highlight-next-line
@printf "\033[1;104m%s\033[0m\n\n" "Below a summary of your current installation:"
# highlight-next-line
# highlight-next-line
@printf "\033[1;34m%s\033[0m\n\n" "JOOMLA"
# highlight-next-line
@printf "\033[1;34m%-30s\033[0m\033[1;104m%s\033[0m\n\n" " * Port" "${WEB_PORT}"
# highlight-next-line
# highlight-next-line
@printf "\033[1;34m%s\033[0m\n\n" "DATABASE"
# highlight-next-line
@printf "\033[1;34m%-30s\033[0m\033[1;104m%s\033[0m\n" " * Host" "joomla-db"
# highlight-next-line
@printf "\033[1;34m%-30s\033[0m\033[1;104m%s\033[0m\n" " * User name" "${DB_USER}"
# highlight-next-line
@printf "\033[1;34m%-30s\033[0m\033[1;104m%s\033[0m\n" " * Password" "${DB_PASSWORD}"
# highlight-next-line
@printf "\033[1;34m%-30s\033[0m\033[1;104m%s\033[0m\n" " * Database name" "${DB_NAME}"
# highlight-next-line
@printf "\033[1;34m%-30s\033[0m\033[1;104m%s\033[0m\n" " * Version" "${MYSQL_VERSION}"
# highlight-next-line
@printf "\033[1;34m%-30s\033[0m\033[1;104m%s\033[0m\n\n" " * Port" "${MYSQL_PORT}"

This Makefile defines commands to manage a Docker-based Joomla installation with a MySQL database. It provides shortcuts for common operations like starting/stopping containers, viewing logs, resetting data, and importing backups—while automatically passing the current user and group IDs to Docker to avoid permission issues. The file also loads environment variables from a .env file and displays formatted configuration information to the user.

Caution

If you don't know if you already have GNU make, just run which make in the console. If you see make not found then please run sudo apt-get update && sudo apt-get install make to proceed with the installation.

>user@machine: ~/yourproject
>user@machine: ~/yourproject

We also need a file called Dockerfile​

In the very first lines of the compose.yaml file we've this portion:

name: ${PROJECT_NAME:-your-project-name}
services:
joomla:
# highlight-next-line
build:
# highlight-next-line
context: .
# highlight-next-line
args:
# highlight-next-line
- PHP_VERSION=${PHP_VERSION:-8.3-apache}

This is a Docker Compose configuration that defines a service called 'joomla'. It builds a Docker image from the current directory (the context) and passes in a PHP version argument during the build process, with a sensible default of PHP 8.3 with Apache if no version is specified. The project name itself also defaults to 'your-project-name' if not provided.

We don't see here an image: statement but a build: one. This means that we need a special file called Dockerfile.

Please create a new file called Dockerfile in your folder with this content:

ARG PHP_VERSION=8.3-apache
FROM php:${PHP_VERSION:-latest}
RUN set -e -x ; \
docker-php-ext-install mysqli pdo pdo_mysql && docker-php-ext-enable pdo_mysql

This Dockerfile creates a PHP web server image starting from an official PHP image with Apache. It installs and enables MySQL-related extensions so PHP can connect to and work with MySQL databases.

That file is quite simple right now: it tells us we need a PHP Docker image, and we also need to install the mysqli drivers.

We need a backup for sure​

Please also put a backup of your existing site and save it in the same folder. For standardization needs, please call that file backup.jpa.

To make this step more explicit: jump to your existing Joomla website and, using Akeeba Backup, create a backup (file format: .jpa) and download the backup. Please rename the backup file like this: backup.jpa.

And finally, we need Akeeba Kickstart​

Finally, we also need to have two files coming from Akeeba Kickstart.

By following the link Akeeba Kickstart, we'll be able to download a .zip file (called kickstart-core-xxx.zip where xxx is a version number). Proceed to the download and open the archives: we'll get two files in it. Please copy these files in your folder.

The two files we need are called en-GB.kickstart.ini and kickstart.php.

Before starting​

We're ready. Just before you begin, please check that you have all the required files (please run ls -alh):

>user@machine: ~/yourproject

Skipping the files creation process

If you've skipped the file creation step earlier by downloading files from my repo, you'll have all the files listed above.

Caution

Remember, for Linux users, we need GNU make to be able to run commands like make import or make up. If you see make not found then please run sudo apt-get update && sudo apt-get install make to proceed with the installation.

Run the importation process​

Ok, you've copied a lot of files. Time to start restoring your site.

For Linux users, simply take advantage of GNU Make and run the make import instruction.

For Windows (Powershell or DOS), please run these commands:

>Powershell

For both users (Linux and Windows), you'll get something like this output in the console:

>user@machine: ~/yourproject

When finished, just start your browser and surf to http://127.0.0.1:8080/kickstart.php to start the restoration of your website using the Akeeba Kickstart wizard — the screens shown at the top of this article.

Once you need to fill in the database information, please refer to what was displayed in your console.

Continue the restoration as you always have; close the window once Akeeba Kickstart asks for it, then click on the Clean Up button; then on Visit your site's frontend and enjoy.

Information

If you've used the provided demo site, the admin account is joomla and its password is joomla@secured.

Conclusion​

As we've just seen, restoring a Joomla site locally has become really simple.

All you need to do is retrieve a few configuration files, and just the one named .env should be updated with the PHP and MySQL versions you're using on your production site.

You download the local backup of your site and, with a single command (make import), your site is restored.

>user@machine: ~/yourproject

No matter what version of Joomla or MySQL you're using.

Piece of cake, no?


Was this article helpful?
Did you try the steps in this article?
🦋 Join the conversation on BlueskyRequires a free Bluesky account to like, repost or comment. This block talks to Bluesky's public API directly from your browser (no cookies, no sign-in) — that means your IP address reaches Bluesky's servers just by this section loading.

Loading comments…