Restore ERPNext Docker Install from S3 Backup Tutorial

Follow these steps to restore an ERPNext instance using a backup stored in S3 (or Google Drive, Dropbox, etc.) into a Frappe Docker setup.

1. Clone Frappe Docker Repository

git clone https://github.com/frappe/frappe_docker.git
cd frappe_docker

2. Start the Docker Stack

docker compose up -f pwd.yml -d

This will bring up the database, backend, frontend, and all required services in detached mode.

3. Download the Backup Archive

Fetch your backup folder (named with timestamp) from your object store. Example directory listing:

ls 20250625_152739/
# 20250625_152739-frontend-database.sql.gz
# 20250625_152739-frontend-files.tar
# 20250625_152739-frontend-private-files.tar
# 20250625_152739-frontend-site_config_backup.json

4. Copy Backup Files into the Backend Container

Replace <timestamp> with your folder name.

docker cp 20250625_152739/20250625_152739-frontend-database.sql.gz frappe_docker-backend-1:/tmp/db.sql.gz
docker cp 20250625_152739/20250625_152739-frontend-files.tar frappe_docker-backend-1:/tmp/frontend-files.tar
docker cp 20250625_152739/20250625_152739-frontend-private-files.tar frappe_docker-backend-1:/tmp/frontend-private-files.tar
docker cp 20250625_152739/20250625_152739-frontend-site_config_backup.json frappe_docker-backend-1:/home/frappe/frappe-bench/sites/frontend/site_config.json

Success messages will confirm each copy.

Note: Open the frontend-site_config_backup.json to identify your database name and credentials:

{
  "db_name": "_2089und8szw92uqu",
  "db_password": "n98zudsanfu09u3n92",
  "db_type": "mariadb",
  "encryption_key": "w09j43-apwo4jr28h392usADk-jpfw8ohw4uejwihaw=",
  "host_name": "http://systemip:8080"
}

5. Import the Database Dump

Enter the backend container as root:

docker exec -it -u root frappe_docker-backend-1 bash

Navigate and decompress the SQL dump:

cd /home/frappe/frappe-bench/
gunzip /tmp/db.sql.gz

Import into MariaDB (replace admin and the DB name as per your config):

mysql -h db -u root -padmin _2089und8szw92uqu < /tmp/db.sql

6. Extract Site Files

Unpack the public and private files into your site folder:

cd /home/frappe/frappe-bench/sites/frontend

# Public files
tar -xvf /tmp/frontend-files.tar -C ./

# Private files
tar -xvf /tmp/frontend-private-files.tar -C ./

7. Update Database User Credentials

Within the MariaDB shell, set the site DB user’s password:

mysql -h db -u root -padmin

ALTER USER '_2089und8szw92uqu'@'%' IDENTIFIED BY 'n98zudsanfu09u3n92';
FLUSH PRIVILEGES;
EXIT;

8. Build, Migrate, and Restart the Site

cd /home/frappe/frappe-bench/

# Clear cache and run migrations
bench --site frontend clear-cache
bench --site frontend migrate

# Build front-end assets
bench build

# Restart bench (warnings about supervisorctl can be ignored in Docker)
bench restart

9. Restart the Docker Stack

Exit the container and back on the host:

docker compose -f pwd.yml down
docker compose -f pwd.yml up -d

Your ERPNext site should now be restored and available at the configured host_name. If you encounter any issues, check logs with docker logs frappe_docker-backend-1 or bench --site frontend console.