MuckiFacilityPlugin

Muckiware Facility Plugin for Shopware 6 Web shops for to maintenance and backup of the database.

• The plugin provides a backup functionality for the database.
• Creates a backup of folders and files by an individual configuration into repository database. The plugin use the restic backup tool for to create the backups. https://restic.readthedocs.io/
• The backups will be encrypted by a password.
• Cleanups tables like cart, if the database table grow up in too large.

Requirements

• Shopware 6.6.x or 6.7.x
• PHP 8.2.x or greater
• restic 0.15.x or greater

Installation

composer require muckiware/facility-plugin
bin/console plugin:install -a MuckiFacilityPlugin

Repository password secret

Repository passwords created through the administration are stored encrypted. The key is derived from the environment variable MUWA_FACILITY_SECRET, which you have to add to your .env:

echo "MUWA_FACILITY_SECRET=$(openssl rand -hex 32)" >> .env

Keep this value with your disaster recovery notes. Without it, no encrypted repository password can be read back — not even from a restored database. Restoring a shop onto a fresh host with a newly generated secret means the repository passwords are lost, and with them access to the backups.

If you would rather keep no secret in the database at all, see Password sources.

General Configuration

Plugin configuration under:
Settings -> Extensions -> My extensions -> MuckiFacilityPlugin -> Configure

Option	Desc
Global settings - Active	Turn plugin on/off global
Global backup settings -> Active database backup	Turn backup database on/off global, for cli command bin/console muckiware:db:dump <Type of backup>
Global backup settings -> Compress database backup file	Turn on/off compressen for db dump, for cli command bin/console muckiware:db:dump <Type of backup>
Global backup settings -> Use own restic path	Turn on/off own restic
Global backup settings -> Own path to binary of restic	Enter the absolut path to binary file of restic. Example input: /var/www/html/bin/restic_0.17.3_linux_386

Respoitory Configuration

First you will need a repository configuration for the backup. The repository configuration is the base for the backup process. The repository configuration contains the backup source and the backup target. The backup source is the path to the folder or file which should be backuped. The backup target is the path to the repository where the backup data should be restored.

Settings -> Extensions -> Backup Repositories -> Add Repository
for to create a new repository configuration.

General Configuration Setup

Option	Desc
Active	Turn repository on/off
Technical Name	Free choose as a technical name, is just for better to organize the backup configurations
Database dump type	Choose the typ of database dump backup. As separate dump files for each table, only one dump file for the complete database, or none database dump.
Repository Path	Absolute path to the backup repository folder. Note that this path cannot be changed after creation!
Hostname	Client hostname for the backup snapshots, default hostname is muwa-facility-client
Repository Password	The backup repository will be encryped by a password. Remembering this password is very important! If you lose it, you won’t be able to get access to the data stored in the repository outside of the shop functionality. Note that this password cannot be changed after creation!
Restore Path	Enter here the absolute path for the target of the restored data.

Backup Paths

Use the Add backup path-button for to define the files and folders which should be backup. You can choose a complete folder, or a single file.

You can define for each path item a compress option. If the compress option is active, the backup data will be compressed by gzip. For folders which containing mainly compressed image files, additional compression during backup would make less sense.

Delete of snapshots

You can remove old snapshots of a repository with the command.

bin/console muckiware:backup:snapshots --delete <backupRepositoryId>

This setup defines the daily, weekly, month or yearly values for this remove process. More details about the keep-parameters you can find in the restic documentation https://restic.readthedocs.io/en/latest/060_forget.html#removing-snapshots-according-to-a-policy

Initial Backup

Finally, click on the Create new Repository-button, for to create a new backup repository. This action creates then a configuration item in the shop database. And it creates the backup repository folder which is defined in the Repository Path field.

like this:

Create Backup

cli

You can create a backup by the command line interface with the following command:

bin/console muckiware:backup:create <backupRepositoryId>

Administration panel

You can also create a backup in the administration panel.

• Go into the list of backup configurations under Settings -> Extensions -> Backup Repositories
• Select the backup repository
• Click on the Start backup-button
  
  

This action does not start the backup process immediately, it will be started as a background process. After a short while, you can see under the checks-tab the status of the backup checks, as well as the snapshots of each database and path item in the Snapshots-tab

At the end of every backup run, the repository statistics (total size, total file count, snapshots count, file system size) are collected and stored. You can see the latest values, plus a history of the last 10 collections, in the Repository Status-tab.

Command Line Interface

Command	Desc
bin/console muckiware:backup:check <backupRepositoryId>	Checks a backup repository
bin/console muckiware:backup:create <backupRepositoryId>	Creates a new backup by backup repository configuration
bin/console muckiware:backup:forget <backupRepositoryId>	Removes snapshots of a backup repository by forget parameters
bin/console muckiware:backup:snapshots <backupRepositoryId>	Gets a list of snapshots in a backup repository id
bin/console muckiware:repository:stats <backupRepositoryId>	Collects and persists the repository status (total size, file count, snapshots count, file system size)
bin/console muckiware:backup:restore <backupRepositoryId> <snapshotId>	Restore data by backup repository id and snapshot id
bin/console muckiware:db:dump <Type of backup>	Creates just a database dump by global plugin setups
bin/console muckiware:backup:encrypt-passwords [--dry-run]	Encrypts repository passwords that are still stored as plain text
bin/console muckiware:backup:password-source <backupRepositoryId> <source> <value>	Sets the password source of a repository (encrypted, env or file)

Password sources

Every repository records where its password comes from. The column repository_password is read according to that source:

Source	Content of the column	Secret in the database
encrypted	ciphertext, prefix v1:	yes, encrypted
env	name of an environment variable	no
file	path of a file	no
plain	the password itself (legacy)	yes, readable

Repositories created in the administration use encrypted. To keep no secret in the database at all, point a repository at an environment variable or a file:

bin/console muckiware:backup:password-source <backupRepositoryId> env MY_REPO_PASSWORD
bin/console muckiware:backup:password-source <backupRepositoryId> file /run/secrets/repo-password

Both are verified when set, so an unreadable file or an empty variable fails right away instead of at the next backup. A password file should not be readable by anyone but the shop user (chmod 600), and it must live outside the document root.

plain only exists for repositories created before passwords were encrypted. Move them over with:

bin/console muckiware:backup:encrypt-passwords --dry-run
bin/console muckiware:backup:encrypt-passwords

Cronjob

You can create a cronjob for to create a backup automatically. This should be the usual configuration for creating backups. The cronjob should be executed by the user which is running the shopware instance. The following command is an example for the cronjob configuration:

* 3 * * * php /var/www/html/bin/console muckiware:backup:create <backupRepositoryId>
30 5 * * * php /var/www/html/bin/console muckiware:backup:forget <backupRepositoryId>
0 6 * * * php /var/www/html/bin/console muckiware:repository:stats <backupRepositoryId>

The first row creates a backup every day at 3:00 am. The second row removes old snapshots every day at 5:30 am. Removing snapshots does not refresh the persisted repository status by itself, so the third row collects a fresh status right after, at 6:00 am.

Database dumps

Backups via command line interface are possible with the following commands:

bin/console muckiware:db:dump <backupType>

Option backup type	Desc
completeDatabaseSingleFile (default)	Backup the complete database as single file. The backup is stored in the directory var/backup/db/ with the filename YYYY-MM-DD_HH-MM-SS_db_backup.sql.gz
completeDatabaseSeparateFiles	Backup the complete database as single file for each database table. The backup is stored in the directory var/backup/YYYY-MM-DD with the filename YYYY-MM-DD_HH-MM-SS_tablename.sql.gz

This command execute a backup of the database. The backup is stored in the directory var/backup/db/ with the filename db_backup_YYYY-MM-DD_HH-MM-SS.sql.gz

Restore

As long as the shopware instance is running, you can restore the backup data via cli like this:

bin/console muckiware:backup:restore 019403b49bed7109a1e238139fb759c5 8888ec40

Or you can choose the snapshot id from the list of snapshots in the administration panel.

• Settings -> Extensions -> Backup Repositories
• Select the backup repository
• Click on the Snapshots-tab
• And select in die list of snapshots the snapshot id for to restore the data. This action will start the restore process of the backup data as a background process.

But if the shop instance is not running anymore, you can use the native restic commands for to restore the backup data.

restic -r /srv/restic-repo restore 79766175 --target /tmp/restore-workdir 

Checkout the description of the restic command for more information. https://restic.readthedocs.io/en/stable/050_restore.html#

Database cleanup

This command offers a more effective option to clean up database tables as the origin Shopware function and free up more memory.

Cart Cleanup

bin/console muckiware:table:cleanup cart

Example

• Database table overview of cart before cleanup
  
  
• Execute the cleanup command
  
• After the cleanup, the table cart has become correspondingly much smaller size as before.
  The maximum number of days that should remain in the cart table can be set in the plugin configuration.

## Log_Entry Cleanup ```shell bin/console muckiware:table:cleanup log_entry ```

Testing

phpstan

Install

Install phpstan, if required

cd custom/plugin/MuckiFacilityPlugin
composer install

Execute

cd custom/plugins/MuckiFacilityPlugin 
composer run-script phpstan

Unit test

Execute first time

./vendor/bin/phpunit --configuration="custom/plugins/MuckiFacilityPlugin" --testsuite "migration"

Execute regular run

./vendor/bin/phpunit --configuration="custom/plugins/MuckiFacilityPlugin"