Merge pull request #40 from move-elevator/feat/mittwald-backup-exclude

feat: exclude regenerable cache directories from hosting backups

Author: konradmichalik

README.md

@@ -65,6 +65,7 @@ Read the [documentation](docs/TYPO3.md) for detailed installation instructions a
 - [Development](docs/DEV.md)
 - [Debug helper](docs/DEBUG.md)
 - [Requirements](docs/REQUIREMENTS.md)
+- [Backup exclusion](docs/BACKUP.md)
 
 
 ## 💛 Acknowledgements

autoload.php

@@ -28,6 +28,12 @@
 require_once(__DIR__ . '/deployer/sync/config/set.php');
 require_once(__DIR__ . '/deployer/sync/task/database_backup.php');
 
+/*
+ * backup
+ */
+require_once(__DIR__ . '/deployer/backup/config/set.php');
+require_once(__DIR__ . '/deployer/backup/task/backup_exclude_cache.php');
+
 /*
  * security
  */

deployer/backup/config/set.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Deployer;
+
+/**
+ * Release-local directories that are fully regenerated on every deploy (composer/npm install,
+ * cache warmup) and therefore don't need to be part of a hosting backup.
+ */
+set('backup_exclude_dirs', [
+    'vendor',
+    'var/cache',
+]);

deployer/backup/task/backup_exclude_cache.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Deployer;
+
+// Cache Directory Tagging Specification (https://bford.info/cachedir/), honored by
+// Mittwald's hosting backups as well as tools like rsync/borg/restic --exclude-caches.
+const CACHEDIR_TAG_SIGNATURE = 'Signature: 8a477f597d28d172789f06886806bc55';
+
+task('backup:exclude_cache', function () {
+    foreach (get('backup_exclude_dirs') as $dir) {
+        $dir = trim($dir, '/');
+
+        if ('' === $dir || in_array('..', explode('/', $dir), true) || in_array('.', explode('/', $dir), true)) {
+            warning("Skipping invalid backup_exclude_dirs entry: \"$dir\"");
+            continue;
+        }
+
+        if (!test("[ -d '{{ release_path }}/$dir' ]")) {
+            continue;
+        }
+
+        run("echo '" . CACHEDIR_TAG_SIGNATURE . "' > '{{ release_path }}/$dir/CACHEDIR.TAG'");
+        debug("Tagged {{ release_path }}/$dir as excluded from backups (CACHEDIR.TAG)");
+    }
+})
+    ->desc('Tag regenerable cache directories to exclude them from hosting backups')
+;
+
+before('deploy:symlink', 'backup:exclude_cache');

docs/BACKUP.md

@@ -0,0 +1,22 @@
+# Backup exclusion
+
+Excludes regenerable, release-local directories (composer/npm build artifacts, framework caches) from hosting backups by tagging them with a `CACHEDIR.TAG` file, following the [Cache Directory Tagging Specification](https://bford.info/cachedir/). This is honored by [Mittwald's automatic backups](https://developer.mittwald.de/de/docs/v2/guides/operations/backup-exclude/) and by common backup/archive tools (`rsync`, `borg`, `restic`, ... with `--exclude-caches`).
+
+## General
+
+The `backup:exclude_cache` task runs automatically before `deploy:symlink`, tagging every directory listed in `backup_exclude_dirs` (relative to `{{release_path}}`) that exists in the current release.
+
+The default settings can be found within the [set.php](../deployer/backup/config/set.php) file.
+
+```php
+set('backup_exclude_dirs', [
+    'vendor',
+    'var/cache',
+]);
+```
+
+Adjust the list per project, e.g. to add framework-specific temp directories, or set it to `[]` to disable the task entirely.
+
+## Caution
+
+Directories tagged this way are excluded from backups entirely and **cannot be restored**, not even by the hoster. Only list directories whose content is fully regenerated by the deploy process (`composer install`, cache warmup) — never shared or writable directories such as `fileadmin`, `uploads`, or `var/log`.