From 1e9bc88eda3d5a86a4e3dacda0575a0d8e324d76 Mon Sep 17 00:00:00 2001
From: Wilfried Wolf <wilfried.wolf@sandstein.de>
Date: Thu, 21 Jul 2022 12:07:41 +0200
Subject: [PATCH 1/9] adds sticky to writable recipe

chgrp for all files, chmod g+rwxs for directories, chmod g+rw for files
---
 recipe/deploy/writable.php | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/recipe/deploy/writable.php b/recipe/deploy/writable.php
index 07bcc28b2..f317ff7ae 100644
--- a/recipe/deploy/writable.php
+++ b/recipe/deploy/writable.php
@@ -87,6 +87,13 @@
         run("$sudo chmod $recursive g+rwx $dirs");
     } elseif ($mode === 'chmod') {
         run("$sudo chmod $recursive {{writable_chmod_mode}} $dirs");
+    } elseif ($mode === 'sticky') {
+        run("for dir in $dirs;".
+            'do '.
+                $sudo.' chgrp -L '.$recursive.' {{http_group}} ${dir}; '.
+                $sudo.' find ${dir} -type d -exec chmod g+rwxs \{\} \;;'.
+                $sudo.' find ${dir} -type f -exec chmod g+rw \{\} \;;'.
+            'done');
     } elseif ($mode === 'acl') {
         $remoteUser = get('remote_user', false);
         if (empty($remoteUser)) {

From 1983d825e215602b956701bafd203c6d6b8b69e7 Mon Sep 17 00:00:00 2001
From: Wilfried Wolf <wilfried.wolf@sandstein.de>
Date: Thu, 21 Jul 2022 12:08:10 +0200
Subject: [PATCH 2/9] adds artifact deployment for magento2 recipe

---
 recipe/magento2.php | 136 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 136 insertions(+)

diff --git a/recipe/magento2.php b/recipe/magento2.php
index fc705f0b8..c8eb9da97 100644
--- a/recipe/magento2.php
+++ b/recipe/magento2.php
@@ -3,6 +3,8 @@
 
 require_once __DIR__ . '/common.php';
 
+
+use Deployer\Exception\GracefulShutdownException;
 use Deployer\Exception\RunException;
 use Deployer\Host\Host;
 
@@ -218,3 +220,137 @@
 ]);
 
 after('deploy:failed', 'magento:maintenance:disable');
+
+// artifact deployment section
+// settings section
+set('artifact_file', 'artifact.tar.gz');
+set('artifact_dir', 'artifacts');
+set('artifact_excludes_file', 'artifacts/excludes');
+
+set('artifact_path', function () {
+    if (!test('[ -d {{artifact_dir}} ]')) {
+        run('mkdir {{artifact_dir}}');
+    }
+    return get('artifact_dir') . '/' . get('artifact_file');
+});
+
+set('bin/tar', function () {
+    if (commandExist('gtar')) {
+        return which('gtar');
+    } else {
+        return which('tar');
+    }
+});
+
+set('cacheToolPath', function() {
+    return get('cacheTool', '{{current_path}}/bin/cachetool');
+});
+
+// tasks section
+desc('Packages all relevant files in an artifact.');
+task('artifact:package', function() {
+    if (!test('[ -f {{artifact_excludes_file}} ]')) {
+        throw new GracefulShutdownException(
+            "No artifact excludes file provided, provide one at artivacts/excludes or change location"
+        );
+    }
+    run('{{bin/tar}} --exclude-from={{artifact_excludes_file}} -czf {{artifact_path}} .');
+});
+
+desc('Uploads artifact in release folder for extraction.');
+task('artifact:upload', function () {
+    upload(get('artifact_path'), '{{release_path}}');
+});
+
+desc('Extracts artifact in release path.');
+task('artifact:extract', function () {
+    run('{{bin/tar}} -xzpf {{release_path}}/{{artifact_file}} -C {{release_path}}');
+    run('rm -rf {{release_path}}/{{artifact_file}}');
+});
+
+desc('Provides env.php for build.');
+task('build:prepare-env', function() {
+    $deployEnv = get('deploy_env','app/etc/deploy.php');
+    if (!test('[ -f ./'.$deployEnv.' ]')) {
+        throw new GracefulShutdownException(
+            "No deploy env provided, provide one at app/etc/deploy.php or change location"
+        );
+    }
+    run ('cp '.$deployEnv.' app/etc/env.php');
+});
+
+desc('Clears generated files prior to building.');
+task('build:remove-generated', function() {
+    run('rm -rf generated/*');
+});
+
+desc('Clears the opcache, cache tool required.');
+task('cache:clear:opcache', function() {
+    if ($fpmSocket = get('fpm_socket', '')) {
+        run('{{bin/php}} -f {{cacheToolPath}} opcache:reset --fcgi '.$fpmSocket);
+    }
+});
+
+desc('Builds an artifact.');
+task('artifact:build', function () {
+    if(currentHost()->get('local')) {
+        set('deploy_path', '.');
+        set('release_path', '.');
+        set('current_path', '.');
+        invoke('build:prepare-env');
+        invoke('build:remove-generated');
+        invoke('deploy:vendors');
+        invoke('magento:compile');
+        invoke('magento:deploy:assets');
+        invoke('artifact:package');
+    } else {
+        throw new GracefulShutdownException("Artifact can only be built locally, you provided a non local host");
+    }
+});
+
+desc('Prepares an artifact on the target server');
+task('artifact:prepare', function(){
+    if(currentHost()->get('local')) {
+        throw new GracefulShutdownException("You can only deploy to a non localhost");
+    } else {
+        add('shared_files', get('additional_shared_files') ?? []);
+        add('shared_dirs', get('additional_shared_dirs') ?? []);
+        invoke('deploy:info');
+        invoke('deploy:setup');
+        invoke('deploy:lock');
+        invoke('deploy:release');
+        invoke('artifact:upload');
+        invoke('artifact:extract');
+        invoke('deploy:shared');
+        invoke('deploy:writable');
+    }
+});
+
+desc('Executes the tasks after artifact is released');
+task('artifact:finish', function() {
+    if(currentHost()->get('local')) {
+        throw new GracefulShutdownException("You can only deploy to a non localhost");
+    } else {
+        invoke('magento:cache:flush');
+        invoke('cache:clear:opcache');
+        invoke('deploy:cleanup');
+        invoke('deploy:unlock');
+    }
+});
+
+desc('Actually releases the artifact deployment');
+task('artifact:deploy', function()  {
+
+    if(currentHost()->get('local')) {
+        throw new GracefulShutdownException("You can only deploy to a non localhost");
+    } else {
+        invoke('artifact:prepare');
+
+        invoke('magento:upgrade:db');
+        invoke('magento:config:import');
+        invoke('deploy:symlink');
+
+        invoke('artifact:finish');
+    }
+});
+

From 8a9ef9bbac17d15920abc102e0d874be6d2ad978 Mon Sep 17 00:00:00 2001
From: Wilfried Wolf <wilfried.wolf@sandstein.de>
Date: Thu, 22 Sep 2022 22:45:23 +0200
Subject: [PATCH 3/9] Updates Documentation

---
 docs/recipe/magento2.md | 189 +++++++++++++++++++++++++++++++++++-----
 1 file changed, 167 insertions(+), 22 deletions(-)

diff --git a/docs/recipe/magento2.md b/docs/recipe/magento2.md
index ff123ec8e..2d4c171ab 100644
--- a/docs/recipe/magento2.md
+++ b/docs/recipe/magento2.md
@@ -56,7 +56,7 @@ The magento2 recipe is based on the [common](/docs/recipe/common.md) recipe.
 
 ## Configuration
 ### static_content_locales
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L20)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L22)
 
 By default setup:static-content:deploy uses `en_US`.
 To change that, simply put `set('static_content_locales', 'en_US de_DE');`
@@ -68,7 +68,7 @@ in you deployer script.
 
 
 ### magento_themes
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L26)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L28)
 
 You can also set the themes to run against. By default it'll deploy
 all themes - `add('magento_themes', ['Magento/luma', 'Magento/backend']);`
@@ -81,7 +81,7 @@ all themes - `add('magento_themes', ['Magento/luma', 'Magento/backend']);`
 
 
 ### static_content_jobs
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L34)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L36)
 
 Also set the number of conccurent jobs to run. The default is 1
 Update using: `set('static_content_jobs', '1');`
@@ -92,7 +92,7 @@ Update using: `set('static_content_jobs', '1');`
 
 
 ### content_version
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L36)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L38)
 
 
 
@@ -102,7 +102,7 @@ return time();
 
 
 ### shared_files
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L40)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L42)
 
 Overrides [shared_files](/docs/recipe/deploy/shared.md#shared_files) from `recipe/deploy/shared.php`.
 
@@ -117,7 +117,7 @@ Overrides [shared_files](/docs/recipe/deploy/shared.md#shared_files) from `recip
 
 
 ### shared_dirs
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L44)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L46)
 
 Overrides [shared_dirs](/docs/recipe/deploy/shared.md#shared_dirs) from `recipe/deploy/shared.php`.
 
@@ -142,7 +142,7 @@ Overrides [shared_dirs](/docs/recipe/deploy/shared.md#shared_dirs) from `recipe/
 
 
 ### writable_dirs
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L58)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L60)
 
 Overrides [writable_dirs](/docs/recipe/deploy/writable.md#writable_dirs) from `recipe/deploy/writable.php`.
 
@@ -160,7 +160,7 @@ Overrides [writable_dirs](/docs/recipe/deploy/writable.md#writable_dirs) from `r
 
 
 ### clear_paths
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L65)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L67)
 
 Overrides [clear_paths](/docs/recipe/deploy/clear_paths.md#clear_paths) from `recipe/deploy/clear_paths.php`.
 
@@ -179,7 +179,7 @@ Overrides [clear_paths](/docs/recipe/deploy/clear_paths.md#clear_paths) from `re
 
 
 ### magento_version
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L74)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L76)
 
 
 
@@ -192,7 +192,7 @@ return $matches[0] ?? '2.0';
 
 
 ### maintenance_mode_status_active
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L81)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L83)
 
 
 
@@ -204,7 +204,7 @@ return strpos($maintenanceModeStatusOutput, MAINTENANCE_MODE_ACTIVE_OUTPUT_MSG)
 
 
 ### enable_zerodowntime
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L88)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L90)
 
 Deploy without setting maintenance mode if possible
 
@@ -213,11 +213,76 @@ true
 ```
 
 
+### artifact_file
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L227)
+
+artifact deployment section
+settings section
+
+```php title="Default value"
+'artifact.tar.gz'
+```
+
+
+### artifact_dir
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L228)
+
+
+
+```php title="Default value"
+'artifacts'
+```
+
+
+### artifact_excludes_file
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L229)
+
+
+
+```php title="Default value"
+'artifacts/excludes'
+```
+
+
+### artifact_path
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L231)
+
+
+
+```php title="Default value"
+if (!test('[ -d {{artifact_dir}} ]')) {
+run('mkdir {{artifact_dir}}');
+}
+return get('artifact_dir') . '/' . get('artifact_file');
+```
+
+
+### bin/tar
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L238)
+
+
+:::info Autogenerated
+The value of this configuration is autogenerated on access.
+:::
+
+
+
+
+### cacheToolPath
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L246)
+
+
+
+```php title="Default value"
+return get('cacheTool', '{{current_path}}/bin/cachetool');
+```
+
+
 
 ## Tasks
 
 ### magento:compile
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L92)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L94)
 
 Compiles magento di.
 
@@ -225,7 +290,7 @@ Tasks
 
 
 ### magento:deploy:assets
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L99)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L101)
 
 Deploys assets.
 
@@ -233,7 +298,7 @@ Deploys assets.
 
 
 ### magento:sync:content_version
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L112)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L114)
 
 Syncs content version.
 
@@ -241,7 +306,7 @@ Syncs content version.
 
 
 ### magento:maintenance:enable
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L122)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L124)
 
 Enables maintenance mode.
 
@@ -249,7 +314,7 @@ Enables maintenance mode.
 
 
 ### magento:maintenance:disable
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L127)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L129)
 
 Disables maintenance mode.
 
@@ -257,7 +322,7 @@ Disables maintenance mode.
 
 
 ### magento:config:import
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L132)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L134)
 
 Config Import.
 
@@ -265,7 +330,7 @@ Config Import.
 
 
 ### magento:upgrade:db
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L167)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L169)
 
 Upgrades magento database.
 
@@ -273,7 +338,7 @@ Upgrades magento database.
 
 
 ### magento:cache:flush
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L194)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L196)
 
 Flushes Magento Cache.
 
@@ -281,7 +346,7 @@ Flushes Magento Cache.
 
 
 ### deploy:magento
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L199)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L201)
 
 Magento2 deployment operations.
 
@@ -296,7 +361,7 @@ This task is group task which contains next tasks:
 
 
 ### magento:build
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L207)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L209)
 
 Magento2 build operations.
 
@@ -309,7 +374,7 @@ This task is group task which contains next tasks:
 
 
 ### deploy
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L213)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L215)
 
 Deploys your project.
 
@@ -324,3 +389,83 @@ This task is group task which contains next tasks:
 * [deploy:publish](/docs/recipe/common.md#deploypublish)
 
 
+### artifact:package
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L252)
+
+Packages all relevant files in an artifact.
+
+tasks section
+
+
+### artifact:upload
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L262)
+
+Uploads artifact in release folder for extraction.
+
+
+
+
+### artifact:extract
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L267)
+
+Extracts artifact in release path.
+
+
+
+
+### build:prepare-env
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L273)
+
+Provides env.php for build.
+
+
+
+
+### build:remove-generated
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L284)
+
+Clears generated files prior to building.
+
+
+
+
+### cache:clear:opcache
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L289)
+
+Clears the opcache, cache tool required.
+
+
+
+
+### artifact:build
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L296)
+
+Builds an artifact.
+
+
+
+
+### artifact:prepare
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L313)
+
+Prepares an artifact on the target server.
+
+
+
+
+### artifact:finish
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L331)
+
+Executes the tasks after artifact is released.
+
+
+
+
+### artifact:deploy
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L343)
+
+Actually releases the artifact deployment.
+
+
+
+

From 0c65ba7334256a0f87134d820eac8d614bb12906 Mon Sep 17 00:00:00 2001
From: Wilfried Wolf <wilfried.wolf@sandstein.de>
Date: Thu, 22 Sep 2022 22:51:45 +0200
Subject: [PATCH 4/9] removes mode that has been submitted in other MR

---
 recipe/deploy/writable.php | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/recipe/deploy/writable.php b/recipe/deploy/writable.php
index f317ff7ae..07bcc28b2 100644
--- a/recipe/deploy/writable.php
+++ b/recipe/deploy/writable.php
@@ -87,13 +87,6 @@
         run("$sudo chmod $recursive g+rwx $dirs");
     } elseif ($mode === 'chmod') {
         run("$sudo chmod $recursive {{writable_chmod_mode}} $dirs");
-    } elseif ($mode === 'sticky') {
-        run("for dir in $dirs;".
-            'do '.
-                $sudo.' chgrp -L '.$recursive.' {{http_group}} ${dir}; '.
-                $sudo.' find ${dir} -type d -exec chmod g+rwxs \{\} \;;'.
-                $sudo.' find ${dir} -type f -exec chmod g+rw \{\} \;;'.
-            'done');
     } elseif ($mode === 'acl') {
         $remoteUser = get('remote_user', false);
         if (empty($remoteUser)) {

From 1c1f03d11d6b158f89e0d864e16bd95c747f777b Mon Sep 17 00:00:00 2001
From: Wilfried Wolf <wilfried.wolf@sandstein.de>
Date: Thu, 3 Nov 2022 17:51:46 +0100
Subject: [PATCH 5/9] adds divers discussion results from PR #3317

- uses contrib/cachetool
- removes task build:prepare-env
- comments additional_shared_files and additonal_shared_dirs
- avoids invoke()
---
 recipe/magento2.php | 139 ++++++++++++++++++++------------------------
 1 file changed, 64 insertions(+), 75 deletions(-)

diff --git a/recipe/magento2.php b/recipe/magento2.php
index 471764e9b..211890bae 100644
--- a/recipe/magento2.php
+++ b/recipe/magento2.php
@@ -2,6 +2,7 @@
 namespace Deployer;
 
 require_once __DIR__ . '/common.php';
+require_once __DIR__ . '/../contrib/cachetool.php';
 
 
 use Deployer\Exception\GracefulShutdownException;
@@ -243,10 +244,6 @@
     }
 });
 
-set('cacheToolPath', function() {
-    return get('cacheTool', '{{current_path}}/bin/cachetool');
-});
-
 // tasks section
 desc('Packages all relevant files in an artifact.');
 task('artifact:package', function() {
@@ -269,89 +266,81 @@
     run('rm -rf {{release_path}}/{{artifact_file}}');
 });
 
-desc('Provides env.php for build.');
-task('build:prepare-env', function() {
-    $deployEnv = get('deploy_env','app/etc/deploy.php');
-    if (!test('[ -f ./'.$deployEnv.' ]')) {
-        throw new GracefulShutdownException(
-            "No deploy env provided, provide one at app/etc/deploy.php or change location"
-        );
-    }
-    run ('cp '.$deployEnv.' app/etc/env.php');
-});
-
 desc('Clears generated files prior to building.');
 task('build:remove-generated', function() {
     run('rm -rf generated/*');
 });
 
-desc('Clears the opcache, cache tool required.');
-task('cache:clear:opcache', function() {
-    if ($fpmSocket = get('fpm_socket', '')) {
-        run('{{bin/php}} -f {{cacheToolPath}} opcache:reset --fcgi '.$fpmSocket);
+desc('Prepare local artifact build');
+task('build:prepare', function() {
+    if(! currentHost()->get('local')) {
+        {
+            throw new GracefulShutdownException("Artifact can only be built locally, you provided a non local host");
+        }
     }
+    set('deploy_path', '.');
+    set('release_path', '.');
+    set('current_path', '.');
 });
 
 desc('Builds an artifact.');
-task('artifact:build', function () {
-    if(currentHost()->get('local')) {
-        set('deploy_path', '.');
-        set('release_path', '.');
-        set('current_path', '.');
-        invoke('build:prepare-env');
-        invoke('build:remove-generated');
-        invoke('deploy:vendors');
-        invoke('magento:compile');
-        invoke('magento:deploy:assets');
-        invoke('artifact:package');
-    } else {
-        throw new GracefulShutdownException("Artifact can only be built locally, you provided a non local host");
-    }
-});
+task(
+    'artifact:build',
+    [
+        'build:prepare',
+        'build:remove-generated',
+        'deploy:vendors',
+        'magento:compile',
+        'magento:deploy:assets',
+        'artifact:package',
+    ]
+);
+
+// Array of shared files that will be added to the default shared_files without overriding
+set('additional_shared_files', []);
+// Array of shared directories that will be added to the default shared_dirs without overriding
+set('additional_shared_dirs', []);
+
+
+add('shared_files', get('additional_shared_files'));
+add('shared_dirs', get('additional_shared_dirs'));
 
 desc('Prepares an artifact on the target server');
-task('artifact:prepare', function(){
-    if(currentHost()->get('local')) {
-        throw new GracefulShutdownException("You can only deploy to a non localhost");
-    } else {
-        add('shared_files', get('additional_shared_files') ?? []);
-        add('shared_dirs', get('additional_shared_dirs') ?? []);
-        invoke('deploy:info');
-        invoke('deploy:setup');
-        invoke('deploy:lock');
-        invoke('deploy:release');
-        invoke('artifact:upload');
-        invoke('artifact:extract');
-        invoke('deploy:shared');
-        invoke('deploy:writable');
-    }
-});
+task(
+    'artifact:prepare',
+    [
+        'deploy:info',
+        'deploy:setup',
+        'deploy:lock',
+        'deploy:release',
+        'artifact:upload',
+        'artifact:extract',
+        'deploy:shared',
+        'deploy:writable',
+    ]
+);
 
 desc('Executes the tasks after artifact is released');
-task('artifact:finish', function() {
-    if(currentHost()->get('local')) {
-        throw new GracefulShutdownException("You can only deploy to a non localhost");
-    } else {
-        invoke('magento:cache:flush');
-        invoke('cache:clear:opcache');
-        invoke('deploy:cleanup');
-        invoke('deploy:unlock');
-    }
-});
+task(
+    'artifact:finish',
+    [
+        'magento:cache:flush',
+        'cachetool:clear:opcache',
+        'deploy:cleanup',
+        'deploy:unlock',
+    ]
+);
 
 desc('Actually releases the artifact deployment');
-task('artifact:deploy', function()  {
-
-    if(currentHost()->get('local')) {
-        throw new GracefulShutdownException("You can only deploy to a non localhost");
-    } else {
-        invoke('artifact:prepare');
-
-        invoke('magento:upgrade:db');
-        invoke('magento:config:import');
-        invoke('deploy:symlink');
-
-        invoke('artifact:finish');
-    }
-});
-
+task(
+    'artifact:deploy',
+    [
+        'artifact:prepare',
+        'magento:upgrade:db',
+        'magento:config:import',
+        'deploy:symlink',
+        'artifact:finish'
+    ]
+);
+
+fail('artifact:deploy', 'deploy:failed');

From b42e3d81cca5f8d4b92e8715ffe1e58c45ff005d Mon Sep 17 00:00:00 2001
From: Wilfried Wolf <wilfried.wolf@sandstein.de>
Date: Thu, 3 Nov 2022 17:57:58 +0100
Subject: [PATCH 6/9] updates docs

---
 docs/recipe/magento2.md | 122 ++++++++++++++--------------------------
 1 file changed, 43 insertions(+), 79 deletions(-)

diff --git a/docs/recipe/magento2.md b/docs/recipe/magento2.md
index 2d4c171ab..142399767 100644
--- a/docs/recipe/magento2.md
+++ b/docs/recipe/magento2.md
@@ -56,7 +56,7 @@ The magento2 recipe is based on the [common](/docs/recipe/common.md) recipe.
 
 ## Configuration
 ### static_content_locales
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L22)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L23)
 
 By default setup:static-content:deploy uses `en_US`.
 To change that, simply put `set('static_content_locales', 'en_US de_DE');`
@@ -68,7 +68,7 @@ in you deployer script.
 
 
 ### magento_themes
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L28)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L29)
 
 You can also set the themes to run against. By default it'll deploy
 all themes - `add('magento_themes', ['Magento/luma', 'Magento/backend']);`
@@ -81,7 +81,7 @@ all themes - `add('magento_themes', ['Magento/luma', 'Magento/backend']);`
 
 
 ### static_content_jobs
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L36)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L37)
 
 Also set the number of conccurent jobs to run. The default is 1
 Update using: `set('static_content_jobs', '1');`
@@ -92,7 +92,7 @@ Update using: `set('static_content_jobs', '1');`
 
 
 ### content_version
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L38)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L39)
 
 
 
@@ -102,7 +102,7 @@ return time();
 
 
 ### shared_files
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L42)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L43)
 
 Overrides [shared_files](/docs/recipe/deploy/shared.md#shared_files) from `recipe/deploy/shared.php`.
 
@@ -117,7 +117,7 @@ Overrides [shared_files](/docs/recipe/deploy/shared.md#shared_files) from `recip
 
 
 ### shared_dirs
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L46)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L47)
 
 Overrides [shared_dirs](/docs/recipe/deploy/shared.md#shared_dirs) from `recipe/deploy/shared.php`.
 
@@ -142,7 +142,7 @@ Overrides [shared_dirs](/docs/recipe/deploy/shared.md#shared_dirs) from `recipe/
 
 
 ### writable_dirs
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L60)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L61)
 
 Overrides [writable_dirs](/docs/recipe/deploy/writable.md#writable_dirs) from `recipe/deploy/writable.php`.
 
@@ -160,7 +160,7 @@ Overrides [writable_dirs](/docs/recipe/deploy/writable.md#writable_dirs) from `r
 
 
 ### clear_paths
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L67)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L68)
 
 Overrides [clear_paths](/docs/recipe/deploy/clear_paths.md#clear_paths) from `recipe/deploy/clear_paths.php`.
 
@@ -179,7 +179,7 @@ Overrides [clear_paths](/docs/recipe/deploy/clear_paths.md#clear_paths) from `re
 
 
 ### magento_version
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L76)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L77)
 
 
 
@@ -192,7 +192,7 @@ return $matches[0] ?? '2.0';
 
 
 ### maintenance_mode_status_active
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L83)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L84)
 
 
 
@@ -204,7 +204,7 @@ return strpos($maintenanceModeStatusOutput, MAINTENANCE_MODE_ACTIVE_OUTPUT_MSG)
 
 
 ### enable_zerodowntime
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L90)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L91)
 
 Deploy without setting maintenance mode if possible
 
@@ -214,7 +214,7 @@ true
 
 
 ### artifact_file
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L227)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L228)
 
 artifact deployment section
 settings section
@@ -225,7 +225,7 @@ settings section
 
 
 ### artifact_dir
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L228)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L229)
 
 
 
@@ -235,7 +235,7 @@ settings section
 
 
 ### artifact_excludes_file
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L229)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L230)
 
 
 
@@ -245,7 +245,7 @@ settings section
 
 
 ### artifact_path
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L231)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L232)
 
 
 
@@ -258,7 +258,7 @@ return get('artifact_dir') . '/' . get('artifact_file');
 
 
 ### bin/tar
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L238)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L239)
 
 
 :::info Autogenerated
@@ -268,21 +268,25 @@ The value of this configuration is autogenerated on access.
 
 
 
-### cacheToolPath
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L246)
+### additional_shared_files
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L300)
 
+Array of shared files that will be added to the default shared_files without overriding
 
 
-```php title="Default value"
-return get('cacheTool', '{{current_path}}/bin/cachetool');
-```
+
+### additional_shared_dirs
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L302)
+
+Array of shared directories that will be added to the default shared_dirs without overriding
+
 
 
 
 ## Tasks
 
 ### magento:compile
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L94)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L95)
 
 Compiles magento di.
 
@@ -290,7 +294,7 @@ Tasks
 
 
 ### magento:deploy:assets
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L101)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L102)
 
 Deploys assets.
 
@@ -298,7 +302,7 @@ Deploys assets.
 
 
 ### magento:sync:content_version
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L114)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L115)
 
 Syncs content version.
 
@@ -306,7 +310,7 @@ Syncs content version.
 
 
 ### magento:maintenance:enable
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L124)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L125)
 
 Enables maintenance mode.
 
@@ -314,7 +318,7 @@ Enables maintenance mode.
 
 
 ### magento:maintenance:disable
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L129)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L130)
 
 Disables maintenance mode.
 
@@ -322,7 +326,7 @@ Disables maintenance mode.
 
 
 ### magento:config:import
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L134)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L135)
 
 Config Import.
 
@@ -330,7 +334,7 @@ Config Import.
 
 
 ### magento:upgrade:db
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L169)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L170)
 
 Upgrades magento database.
 
@@ -338,7 +342,7 @@ Upgrades magento database.
 
 
 ### magento:cache:flush
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L196)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L197)
 
 Flushes Magento Cache.
 
@@ -346,7 +350,7 @@ Flushes Magento Cache.
 
 
 ### deploy:magento
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L201)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L202)
 
 Magento2 deployment operations.
 
@@ -361,7 +365,7 @@ This task is group task which contains next tasks:
 
 
 ### magento:build
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L209)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L210)
 
 Magento2 build operations.
 
@@ -374,7 +378,7 @@ This task is group task which contains next tasks:
 
 
 ### deploy
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L215)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L216)
 
 Deploys your project.
 
@@ -390,7 +394,7 @@ This task is group task which contains next tasks:
 
 
 ### artifact:package
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L252)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L249)
 
 Packages all relevant files in an artifact.
 
@@ -398,7 +402,7 @@ tasks section
 
 
 ### artifact:upload
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L262)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L259)
 
 Uploads artifact in release folder for extraction.
 
@@ -406,65 +410,25 @@ Uploads artifact in release folder for extraction.
 
 
 ### artifact:extract
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L267)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L264)
 
 Extracts artifact in release path.
 
 
 
 
-### build:prepare-env
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L273)
-
-Provides env.php for build.
-
-
-
-
 ### build:remove-generated
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L284)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L270)
 
 Clears generated files prior to building.
 
 
 
 
-### cache:clear:opcache
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L289)
-
-Clears the opcache, cache tool required.
-
-
-
-
-### artifact:build
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L296)
-
-Builds an artifact.
-
-
-
-
-### artifact:prepare
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L313)
-
-Prepares an artifact on the target server.
-
-
-
-
-### artifact:finish
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L331)
-
-Executes the tasks after artifact is released.
-
-
-
-
-### artifact:deploy
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L343)
+### build:prepare
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L275)
 
-Actually releases the artifact deployment.
+Prepare local artifact build.
 
 
 

From c93d9a13da8da7f8457e03910f4bb3c5ea472ab9 Mon Sep 17 00:00:00 2001
From: Wilfried Wolf <wilfried.wolf@sandstein.de>
Date: Fri, 4 Nov 2022 16:16:56 +0100
Subject: [PATCH 7/9] corrects additional shared

---
 docs/recipe/magento2.md | 8 ++++++++
 recipe/magento2.php     | 9 +++++++--
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/docs/recipe/magento2.md b/docs/recipe/magento2.md
index 142399767..0e19ded93 100644
--- a/docs/recipe/magento2.md
+++ b/docs/recipe/magento2.md
@@ -433,3 +433,11 @@ Prepare local artifact build.
 
 
 
+### deploy:additional-shared
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L306)
+
+Adds additional files and dirs to the list of shared files and dirs.
+
+
+
+
diff --git a/recipe/magento2.php b/recipe/magento2.php
index 211890bae..b7038d898 100644
--- a/recipe/magento2.php
+++ b/recipe/magento2.php
@@ -302,8 +302,12 @@
 set('additional_shared_dirs', []);
 
 
-add('shared_files', get('additional_shared_files'));
-add('shared_dirs', get('additional_shared_dirs'));
+desc('Adds additional files and dirs to the list of shared files and dirs');
+task('deploy:additional-shared', function () {
+    add('shared_files', get('additional_shared_files'));
+    add('shared_dirs', get('additional_shared_dirs'));
+});
+
 
 desc('Prepares an artifact on the target server');
 task(
@@ -315,6 +319,7 @@
         'deploy:release',
         'artifact:upload',
         'artifact:extract',
+        'deploy:additional-shared',
         'deploy:shared',
         'deploy:writable',
     ]

From dc06a8034c405df6cd8e986d9e05d636e658f2ce Mon Sep 17 00:00:00 2001
From: Wilfried Wolf <wilfried.wolf@sandstein.de>
Date: Fri, 24 Feb 2023 10:52:56 +0100
Subject: [PATCH 8/9] expands DocGen for artifact deployment and adds
 documentation to the magento2 recipe

---
 docs/recipe/magento2.md      | 219 +++++++++++++++++++++++++++++------
 recipe/magento2.php          |  71 ++++++++----
 src/Documentation/DocGen.php |  73 +++++++++---
 3 files changed, 290 insertions(+), 73 deletions(-)

diff --git a/docs/recipe/magento2.md b/docs/recipe/magento2.md
index 35cc53c09..09a1d024d 100644
--- a/docs/recipe/magento2.md
+++ b/docs/recipe/magento2.md
@@ -1,3 +1,6 @@
+<!-- DO NOT EDIT THIS FILE! -->
+<!-- Instead edit recipe/magento2.php -->
+<!-- Then run bin/docgen -->
 
 # How to Deploy a Magento 2 Project
 
@@ -49,6 +52,61 @@ The [deploy](#deploy) task of **Magento 2** consists of:
   * [deploy:success](/docs/recipe/common.md#deploysuccess) – 
 
 
+In addition the **Magento 2** recipe contains an artifact deployment.
+This is a two step process where you first execute
+
+```php
+bin/dep artifact:build [options] [localhost]
+```
+
+to build an artifact, which then is deployed on a server with
+
+```php
+bin/dep artifact:deploy [host]
+```
+
+The `localhost` to build the artifact on has to be declared local, so either add
+```php
+localhost()
+    ->set('local', true);
+```
+to your deploy.php or
+```yaml
+hosts:
+    localhost:
+        local: true
+```
+to your deploy yaml.
+
+The [artifact:build](#artifact:build) command of **Magento 2** consists of: * [build:prepare](/docs/recipe/magento2.md#buildprepare) – Prepare local artifact build
+* [build:remove-generated](/docs/recipe/magento2.md#buildremove-generated) – Clears generated files prior to building.
+* [deploy:vendors](/docs/recipe/deploy/vendors.md#deployvendors) – Installs vendors
+* [magento:compile](/docs/recipe/magento2.md#magentocompile) – Compiles magento di
+* [magento:deploy:assets](/docs/recipe/magento2.md#magentodeployassets) – Deploys assets
+* [artifact:package](/docs/recipe/magento2.md#artifactpackage) – Packages all relevant files in an artifact.
+
+
+ The [artifact:deploy](#artifact:deploy) command of **Magento 2** consists of:
+* [artifact:prepare](/docs/recipe/magento2.md#artifactprepare) – Prepares an artifact on the target server
+  * [deploy:info](/docs/recipe/deploy/info.md#deployinfo) – Displays info about deployment
+  * [deploy:setup](/docs/recipe/deploy/setup.md#deploysetup) – Prepares host for deploy
+  * [deploy:lock](/docs/recipe/deploy/lock.md#deploylock) – Locks deploy
+  * [deploy:release](/docs/recipe/deploy/release.md#deployrelease) – Prepares release
+  * [artifact:upload](/docs/recipe/magento2.md#artifactupload) – Uploads artifact in release folder for extraction.
+  * [artifact:extract](/docs/recipe/magento2.md#artifactextract) – Extracts artifact in release path.
+  * [deploy:additional-shared](/docs/recipe/magento2.md#deployadditional-shared) – Adds additional files and dirs to the list of shared files and dirs
+  * [deploy:shared](/docs/recipe/deploy/shared.md#deployshared) – Creates symlinks for shared files and dirs
+  * [deploy:writable](/docs/recipe/deploy/writable.md#deploywritable) – Makes writable dirs
+* [magento:upgrade:db](/docs/recipe/magento2.md#magentoupgradedb) – Upgrades magento database
+* [magento:config:import](/docs/recipe/magento2.md#magentoconfigimport) – Config Import
+* [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink) – Creates symlink to release
+* [artifact:finish](/docs/recipe/magento2.md#artifactfinish) – Executes the tasks after artifact is released
+  * [magento:cache:flush](/docs/recipe/magento2.md#magentocacheflush) – Flushes Magento Cache
+  * [cachetool:clear:opcache](/docs/contrib/cachetool.md#cachetoolclearopcache) – Clears OPcode cache
+  * [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup) – Cleanup old releases
+  * [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock) – Unlocks deploy
+
+
 The magento2 recipe is based on the [common](/docs/recipe/common.md) recipe.
 
 ## Configuration
@@ -232,10 +290,9 @@ true
 
 
 ### artifact_file
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L236)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L263)
 
-artifact deployment section
-settings section
+The file the artifact is saved to
 
 ```php title="Default value"
 'artifact.tar.gz'
@@ -243,9 +300,9 @@ settings section
 
 
 ### artifact_dir
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L237)
-
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L266)
 
+The directory the artifact is saved in
 
 ```php title="Default value"
 'artifacts'
@@ -253,9 +310,10 @@ settings section
 
 
 ### artifact_excludes_file
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L238)
-
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L270)
 
+Points to a file with a list of files to exclude from packaging.
+The format is as with the `tar --exclude-from=[file]` option
 
 ```php title="Default value"
 'artifacts/excludes'
@@ -263,7 +321,7 @@ settings section
 
 
 ### build_from_repo
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L240)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L273)
 
 If set to true, the artifact is built from a clean copy of the project repository instead of the current working directory
 
@@ -273,7 +331,7 @@ false
 
 
 ### repository
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L242)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L276)
 
 Overrides [repository](/docs/recipe/common.md#repository) from `recipe/common.php`.
 
@@ -285,9 +343,9 @@ null
 
 
 ### artifact_path
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L244)
-
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L279)
 
+The relative path to the artifact file. If the directory does not exist, it will be created
 
 ```php title="Default value"
 if (!testLocally('[ -d {{artifact_dir}} ]')) {
@@ -298,9 +356,9 @@ return get('artifact_dir') . '/' . get('artifact_file');
 
 
 ### bin/tar
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L251)
-
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L287)
 
+The location of the tar command. On MacOS you should have installed gtar, as it supports the required settings
 :::info Autogenerated
 The value of this configuration is autogenerated on access.
 :::
@@ -309,14 +367,14 @@ The value of this configuration is autogenerated on access.
 
 
 ### additional_shared_files
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L325)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L359)
 
 Array of shared files that will be added to the default shared_files without overriding
 
 
 
 ### additional_shared_dirs
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L327)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L361)
 
 Array of shared directories that will be added to the default shared_dirs without overriding
 
@@ -326,23 +384,46 @@ Array of shared directories that will be added to the default shared_dirs withou
 ## Tasks
 
 ### magento:compile
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L102)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L108)
 
 Compiles magento di.
 
-Tasks
+To work correctly with artifact deployment, it is necessary to set the MAGE_MODE correctly in `app/etc/config.php`
+e.g.
+```php
+'MAGE_MODE' => 'production'
+```
 
 
 ### magento:deploy:assets
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L108)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L134)
 
 Deploys assets.
 
-
+To work correctly with artifact deployment it is necessary to set `system/dev/js` , `system/dev/css` and `system/dev/template`
+in `app/etc/config.php`, e.g.:
+```php
+'system' => [
+    'default' => [
+        'dev' => [
+            'js' => [
+                'merge_files' => '1',
+                'minify_files' => '1'
+            ],
+            'css' => [
+                'merge_files' => '1',
+                'minify_files' => '1'
+            ],
+            'template' => [
+                'minify_html' => '1'
+            ]
+        ]
+    ]
+```
 
 
 ### magento:sync:content_version
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L121)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L147)
 
 Syncs content version.
 
@@ -350,7 +431,7 @@ Syncs content version.
 
 
 ### magento:maintenance:enable
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L131)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L157)
 
 Enables maintenance mode.
 
@@ -358,7 +439,7 @@ Enables maintenance mode.
 
 
 ### magento:maintenance:disable
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L137)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L163)
 
 Disables maintenance mode.
 
@@ -366,7 +447,7 @@ Disables maintenance mode.
 
 
 ### magento:config:import
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L143)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L169)
 
 Config Import.
 
@@ -374,7 +455,7 @@ Config Import.
 
 
 ### magento:upgrade:db
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L178)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L204)
 
 Upgrades magento database.
 
@@ -382,7 +463,7 @@ Upgrades magento database.
 
 
 ### magento:cache:flush
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L205)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L231)
 
 Flushes Magento Cache.
 
@@ -390,7 +471,7 @@ Flushes Magento Cache.
 
 
 ### deploy:magento
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L210)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L236)
 
 Magento2 deployment operations.
 
@@ -405,7 +486,7 @@ This task is group task which contains next tasks:
 
 
 ### magento:build
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L218)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L244)
 
 Magento2 build operations.
 
@@ -418,7 +499,7 @@ This task is group task which contains next tasks:
 
 
 ### deploy
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L224)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L250)
 
 Deploys your project.
 
@@ -434,15 +515,15 @@ This task is group task which contains next tasks:
 
 
 ### artifact:package
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L261)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L298)
 
 Packages all relevant files in an artifact.
 
-tasks section
+
 
 
 ### artifact:upload
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L271)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L308)
 
 Uploads artifact in release folder for extraction.
 
@@ -450,7 +531,7 @@ Uploads artifact in release folder for extraction.
 
 
 ### artifact:extract
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L276)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L313)
 
 Extracts artifact in release path.
 
@@ -458,7 +539,7 @@ Extracts artifact in release path.
 
 
 ### build:remove-generated
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L282)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L319)
 
 Clears generated files prior to building.
 
@@ -466,18 +547,86 @@ Clears generated files prior to building.
 
 
 ### build:prepare
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L287)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L324)
 
 Prepare local artifact build.
 
 
 
 
+### artifact:build
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L349)
+
+Builds an artifact.
+
+
+
+
+This task is group task which contains next tasks:
+* [build:prepare](/docs/recipe/magento2.md#buildprepare)
+* [build:remove-generated](/docs/recipe/magento2.md#buildremove-generated)
+* [deploy:vendors](/docs/recipe/deploy/vendors.md#deployvendors)
+* [magento:compile](/docs/recipe/magento2.md#magentocompile)
+* [magento:deploy:assets](/docs/recipe/magento2.md#magentodeployassets)
+* [artifact:package](/docs/recipe/magento2.md#artifactpackage)
+
+
 ### deploy:additional-shared
-[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L331)
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L365)
 
 Adds additional files and dirs to the list of shared files and dirs.
 
 
 
 
+### artifact:prepare
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L372)
+
+Prepares an artifact on the target server.
+
+
+
+
+This task is group task which contains next tasks:
+* [deploy:info](/docs/recipe/deploy/info.md#deployinfo)
+* [deploy:setup](/docs/recipe/deploy/setup.md#deploysetup)
+* [deploy:lock](/docs/recipe/deploy/lock.md#deploylock)
+* [deploy:release](/docs/recipe/deploy/release.md#deployrelease)
+* [artifact:upload](/docs/recipe/magento2.md#artifactupload)
+* [artifact:extract](/docs/recipe/magento2.md#artifactextract)
+* [deploy:additional-shared](/docs/recipe/magento2.md#deployadditional-shared)
+* [deploy:shared](/docs/recipe/deploy/shared.md#deployshared)
+* [deploy:writable](/docs/recipe/deploy/writable.md#deploywritable)
+
+
+### artifact:finish
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L385)
+
+Executes the tasks after artifact is released.
+
+
+
+
+This task is group task which contains next tasks:
+* [magento:cache:flush](/docs/recipe/magento2.md#magentocacheflush)
+* [cachetool:clear:opcache](/docs/contrib/cachetool.md#cachetoolclearopcache)
+* [deploy:cleanup](/docs/recipe/deploy/cleanup.md#deploycleanup)
+* [deploy:unlock](/docs/recipe/deploy/lock.md#deployunlock)
+
+
+### artifact:deploy
+[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L393)
+
+Actually releases the artifact deployment.
+
+
+
+
+This task is group task which contains next tasks:
+* [artifact:prepare](/docs/recipe/magento2.md#artifactprepare)
+* [magento:upgrade:db](/docs/recipe/magento2.md#magentoupgradedb)
+* [magento:config:import](/docs/recipe/magento2.md#magentoconfigimport)
+* [deploy:symlink](/docs/recipe/deploy/symlink.md#deploysymlink)
+* [artifact:finish](/docs/recipe/magento2.md#artifactfinish)
+
+
diff --git a/recipe/magento2.php b/recipe/magento2.php
index 056fd7cda..15e1dc608 100644
--- a/recipe/magento2.php
+++ b/recipe/magento2.php
@@ -98,12 +98,38 @@
 set('enable_zerodowntime', true);
 
 // Tasks
+
+// To work correctly with artifact deployment, it is necessary to set the MAGE_MODE correctly in `app/etc/config.php`
+// e.g.
+// ```php
+// 'MAGE_MODE' => 'production'
+// ```
 desc('Compiles magento di');
 task('magento:compile', function () {
     run("{{bin/php}} {{bin/magento}} setup:di:compile");
     run('cd {{release_or_current_path}}/{{magento_dir}} && {{bin/composer}} dump-autoload -o');
 });
 
+// To work correctly with artifact deployment it is necessary to set `system/dev/js` , `system/dev/css` and `system/dev/template`
+// in `app/etc/config.php`, e.g.:
+// ```php
+// 'system' => [
+//     'default' => [
+//         'dev' => [
+//             'js' => [
+//                 'merge_files' => '1',
+//                 'minify_files' => '1'
+//             ],
+//             'css' => [
+//                 'merge_files' => '1',
+//                 'minify_files' => '1'
+//             ],
+//             'template' => [
+//                 'minify_html' => '1'
+//             ]
+//         ]
+//     ]
+// ```
 desc('Deploys assets');
 task('magento:deploy:assets', function () {
 
@@ -231,16 +257,25 @@
 
 after('deploy:failed', 'magento:maintenance:disable');
 
-// artifact deployment section
-// settings section
+// artifact deployemnt section
+
+// The file the artifact is saved to
 set('artifact_file', 'artifact.tar.gz');
+
+// The directory the artifact is saved in
 set('artifact_dir', 'artifacts');
+
+// Points to a file with a list of files to exclude from packaging.
+// The format is as with the `tar --exclude-from=[file]` option
 set('artifact_excludes_file', 'artifacts/excludes');
+
 // If set to true, the artifact is built from a clean copy of the project repository instead of the current working directory
 set('build_from_repo', false);
+
 // Set this value if "build_from_repo" is set to true. The target to deploy must also be set with "--branch", "--tag" or "--revision"
 set('repository', null);
 
+// The relative path to the artifact file. If the directory does not exist, it will be created
 set('artifact_path', function () {
     if (!testLocally('[ -d {{artifact_dir}} ]')) {
         runLocally('mkdir -p {{artifact_dir}}');
@@ -248,6 +283,7 @@
     return get('artifact_dir') . '/' . get('artifact_file');
 });
 
+// The location of the tar command. On MacOS you should have installed gtar, as it supports the required settings
 set('bin/tar', function () {
     if (commandExist('gtar')) {
         return which('gtar');
@@ -257,6 +293,7 @@
 });
 
 // tasks section
+
 desc('Packages all relevant files in an artifact.');
 task('artifact:package', function() {
     if (!test('[ -f {{artifact_excludes_file}} ]')) {
@@ -309,17 +346,14 @@
 });
 
 desc('Builds an artifact.');
-task(
-    'artifact:build',
-    [
+task('artifact:build', [
         'build:prepare',
         'build:remove-generated',
         'deploy:vendors',
         'magento:compile',
         'magento:deploy:assets',
         'artifact:package',
-    ]
-);
+]);
 
 // Array of shared files that will be added to the default shared_files without overriding
 set('additional_shared_files', []);
@@ -335,9 +369,7 @@
 
 
 desc('Prepares an artifact on the target server');
-task(
-    'artifact:prepare',
-    [
+task('artifact:prepare', [
         'deploy:info',
         'deploy:setup',
         'deploy:lock',
@@ -347,30 +379,23 @@
         'deploy:additional-shared',
         'deploy:shared',
         'deploy:writable',
-    ]
-);
+]);
 
 desc('Executes the tasks after artifact is released');
-task(
-    'artifact:finish',
-    [
+task('artifact:finish', [
         'magento:cache:flush',
         'cachetool:clear:opcache',
         'deploy:cleanup',
         'deploy:unlock',
-    ]
-);
+]);
 
 desc('Actually releases the artifact deployment');
-task(
-    'artifact:deploy',
-    [
+task('artifact:deploy', [
         'artifact:prepare',
         'magento:upgrade:db',
         'magento:config:import',
         'deploy:symlink',
-        'artifact:finish'
-    ]
-);
+        'artifact:finish',
+]);
 
 fail('artifact:deploy', 'deploy:failed');
diff --git a/src/Documentation/DocGen.php b/src/Documentation/DocGen.php
index b12059454..9712c1116 100644
--- a/src/Documentation/DocGen.php
+++ b/src/Documentation/DocGen.php
@@ -108,7 +108,7 @@ public function gen(string $destination): ?string
                 }
                 return $output;
             };
-            $findTask = function (string $name) use ($recipe): ?DocTask {
+            $findTask = function (string $name, bool $searchOtherRecipes = true) use ($recipe): ?DocTask {
                 if (array_key_exists($name, $recipe->tasks)) {
                     return $recipe->tasks[$name];
                 }
@@ -119,9 +119,11 @@ public function gen(string $destination): ?string
                         }
                     }
                 }
-                foreach ($this->recipes as $r) {
-                    if (array_key_exists($name, $r->tasks)) {
-                        return $r->tasks[$name];
+                if ($searchOtherRecipes) {
+                    foreach ($this->recipes as $r) {
+                        if (array_key_exists($name, $r->tasks)) {
+                            return $r->tasks[$name];
+                        }
                     }
                 }
                 return null;
@@ -165,24 +167,65 @@ public function gen(string $destination): ?string
 
 MARKDOWN;
 
+                $map = function (DocTask $task, $ident = '') use (&$map, $findTask, &$intro): void {
+                    foreach ($task->group as $taskName) {
+                        $t = $findTask($taskName);
+                        if ($t !== null) {
+                            $intro .= "$ident* {$t->mdLink()} – $t->desc\n";
+                            if ($t->group !== null) {
+                                $map($t, $ident . '  ');
+                            }
+                        }
+                    }
+                };
                 $deployTask = $findTask('deploy');
                 if ($deployTask !== null) {
                     $intro .= "The [deploy](#deploy) task of **$brandName** consists of:\n";
-                    $map = function (DocTask $task, $ident = '') use (&$map, $findTask, &$intro): void {
-                        foreach ($task->group as $taskName) {
-                            $t = $findTask($taskName);
-                            if ($t !== null) {
-                                $intro .= "$ident* {$t->mdLink()} – $t->desc\n";
-                                if ($t->group !== null) {
-                                    $map($t, $ident . '  ');
-                                }
-                            }
-                        }
-                    };
                     $map($deployTask);
                 }
 
                 $intro .= "\n\n";
+
+                $artifactBuildTask = $findTask('artifact:build', false);
+                $artifactDeployTask = $findTask('artifact:deploy', false);
+                if ($artifactDeployTask !== null && $artifactBuildTask !== null) {
+                    $intro .= "In addition the **$brandName** recipe contains an artifact deployment.\n";
+                    $intro .= <<<MD
+This is a two step process where you first execute
+
+```php
+bin/dep artifact:build [options] [localhost]
+```
+
+to build an artifact, which then is deployed on a server with
+
+```php
+bin/dep artifact:deploy [host]
+```
+
+The `localhost` to build the artifact on has to be declared local, so either add
+```php
+localhost()
+    ->set('local', true);
+```
+to your deploy.php or
+```yaml
+hosts:
+    localhost:
+        local: true
+```
+to your deploy yaml.
+
+The [artifact:build](#artifact:build) command of **$brandName** consists of: 
+MD;
+                    $map($artifactBuildTask);
+
+                    $intro .= "\n\n The [artifact:deploy](#artifact:deploy) command of **$brandName** consists of:\n";
+
+                    $map($artifactDeployTask);
+
+                    $intro .= "\n\n";
+                }
             }
             if (count($recipe->require) > 0) {
                 if (is_framework_recipe($recipe)) {

From f7b99e78746b86fe14264db62d0ab35690542447 Mon Sep 17 00:00:00 2001
From: Wilfried Wolf <wilfried.wolf@sandstein.de>
Date: Mon, 27 Feb 2023 16:18:03 +0100
Subject: [PATCH 9/9] corrects missing capital and typo

---
 recipe/magento2.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/recipe/magento2.php b/recipe/magento2.php
index 15e1dc608..bbb8ffa7c 100644
--- a/recipe/magento2.php
+++ b/recipe/magento2.php
@@ -257,7 +257,7 @@
 
 after('deploy:failed', 'magento:maintenance:disable');
 
-// artifact deployemnt section
+// Artifact deployment section
 
 // The file the artifact is saved to
 set('artifact_file', 'artifact.tar.gz');