[TASK] Split up deployment section

TYPO3-Documentation · Mar 4, 2024 · 9386598 · 9386598
1 parent 99422df
commit 9386598
Show file tree

Hide file tree

Showing 7 changed files with 171 additions and 126 deletions.
diff --git a/Documentation/Installation/DeployTYPO3.rst b/Documentation/Installation/DeployTYPO3.rst
@@ -107,129 +107,9 @@ When using a deployment tool this kind of directory structure is usually created
 
 The following section contains examples for various deployment tools and how they can be configured to use TYPO3:
 
-.. tabs::
-
-   .. tab:: TYPO3 Surf
-
-      :doc:`TYPO3 Surf <ext_surf:Index>` is a deployment tool written in PHP.
-
-
-      .. code-block:: php
-         :caption: ~/.surf/MyDeployment.php
-
-         <?php
-         /** @var \TYPO3\Surf\Domain\Model\Deployment $deployment */
-
-         $node = new \TYPO3\Surf\Domain\Model\Node('my.node.com');
-         $node
-             ->setHostname($node->getName())
-             ->setOption('username', 'myuser')
-             ->setOption('phpBinaryPathAndFilename', '/usr/local/bin/php_cli');
-
-         $application = new \TYPO3\Surf\Application\TYPO3\CMS();
-         $application
-             ->setDeploymentPath('/httpdocs')
-             ->setOption('baseUrl', 'https://my.node.com/')
-             ->setOption('webDirectory', 'public')
-             ->setOption('symlinkDataFolders', ['fileadmin'])
-             ->setOption('repositoryUrl', 'file://' . dirname(__DIR__))
-             ->setOption('keepReleases', 3)
-             ->setOption('composerCommandPath', 'composer')
-             ->setOption('rsyncExcludes', [
-                 '.ddev',
-                 '.git',
-                 $application->getOption('webDirectory') . '/fileadmin',
-                 'packages/**.sass'
-             ])
-             ->setOption(TYPO3\Surf\Task\TYPO3\CMS\FlushCachesTask::class . '[arguments]', [])
-             ->addSymlink($application->getOption('webDirectory') . '/config/system/settings.php', '../../../../shared/Configuration/settings.php')
-             ->addNode($node);
-
-             $deployment
-                 ->addApplication($application)
-                 ->onInitialize(
-                     function () use ($deployment, $application) {
-                         $deployment->getWorkflow()
-                             ->beforeTask(\TYPO3\Surf\Task\TYPO3\CMS\SetUpExtensionsTask::class, \TYPO3\Surf\Task\TYPO3\CMS\CompareDatabaseTask::class, $application)
-                             ->beforeStage('transfer', \TYPO3\Surf\Task\Php\WebOpcacheResetCreateScriptTask::class, $application)
-                             ->afterStage('switch', \TYPO3\Surf\Task\Php\WebOpcacheResetExecuteTask::class, $application)
-                             // CreatePackageStatesTask is done by post-autoload-dump script and can be removed
-                             // https://github.com/TYPO3/TYPO3.CMS.BaseDistribution/blob/9.x/composer.json#L38
-                             ->removeTask(\TYPO3\Surf\Task\TYPO3\CMS\CreatePackageStatesTask::class, $application)
-                             ->removeTask(\TYPO3\Surf\Task\TYPO3\CMS\CopyConfigurationTask::class, $application);
-                     }
-                 );
-
-
-   .. tab:: Deployer
-
-      `Deployer <https://deployer.org>`__ is an alternative deployment tool
-      written in PHP. A full description about how to get deployer running
-      for TYPO3 can be found at https://t3terminal.com/blog/typo3-deploy/
-
-      .. code-block:: php
-
-         <?php
-
-         namespace Deployer;
-
-         require_once(__DIR__ . '/vendor/sourcebroker/deployer-loader/autoload.php');
-         new \SourceBroker\DeployerExtendedTypo3\Loader();
-
-         set('repository', '[email protected]:youraccount/yourproject.git');
-         set('bin/php', '/home/www/example-project-directory/.bin/php');
-         set('web_path', 'public/');
-
-         host('live')
-             ->hostname('production.example.org')
-             ->user('deploy')
-             ->set('branch', 'main')
-             ->set('public_urls', ['https://production.example.org'])
-             ->set('deploy_path', '/home/www/example-project-directory/live');
-
-
-   .. tab:: Magallanes
-
-      Yet another deployment tool for PHP applications written in PHP: https://www.magephp.com
-
-      .. code-block:: yaml
-         :caption: .mage.yml
-
-         magephp:
-           log_dir: ./.mage/logs
-           composer:
-             path: composer
-           exclude:
-             - ./.ddev
-             - ./.git
-             - ./.mage
-             - ./public/fileadmin
-             - ./public/typo3temp
-             - ./var
-             - ./.mage.yml
-             - ./composer.json
-             - ./composer.lock
-             - ./LICENSE
-             - ./README.md
-           environments:
-             main:
-               user: ssh-user
-               from: ./
-               host_path: /srv/vhosts/target-path/site/mage
-               releases: 3
-               hosts:
-                 - production.example.org
-               pre-deploy:
-                 - exec: { cmd: "composer install --no-dev --no-progress --optimize-autoloader"}
-               on-deploy:
-                 - fs/link: { from: "../../../../shared/public/fileadmin", to: "public/fileadmin" }
-                 - fs/link: { from: "../../../../shared/public/typo3temp", to: "public/typo3temp" }
-                 - fs/link: { from: "../../../shared/var", to: "var" }
-               on-release:
-               post-release:
-                 - exec: { cmd: './bin/typo3 backend:lock', timeout: 9000  }
-                 - exec: { cmd: './bin/typo3cms database:updateschema *.add,*.change', timeout: 9000  }
-                 - exec: { cmd: './bin/typo3cms cache:flush', timeout: 9000  }
-                 - exec: { cmd: './bin/typo3 upgrade:run', timeout: 9000  }
-                 - exec: { cmd: './bin/typo3 backend:unlock', timeout: 9000  }
-               post-deploy:
+..  toctree::
+    :titlesonly:
+
+    Deployer/Index
+    Surf/Index
+    Magallanes/Index
diff --git a/Documentation/Installation/Deployer/Index.rst b/Documentation/Installation/Deployer/Index.rst
@@ -0,0 +1,17 @@
+.. include:: /Includes.rst.txt
+
+.. index:: Deployment; Deployer
+
+.. _deployment-deployer:
+
+========
+Deployer
+========
+
+`Deployer <https://deployer.org>`__ is an alternative deployment tool
+written in PHP. A full description about how to get deployer running
+for TYPO3 can be found at https://t3terminal.com/blog/typo3-deploy/
+
+..  literalinclude:: _deploy.php
+    :language: php
+    :caption: deploy.php
diff --git a/Documentation/Installation/Deployer/_deploy.php b/Documentation/Installation/Deployer/_deploy.php
@@ -0,0 +1,16 @@
+<?php
+namespace Deployer;
+
+require_once(__DIR__ . '/vendor/sourcebroker/deployer-loader/autoload.php');
+new \SourceBroker\DeployerExtendedTypo3\Loader();
+
+set('repository', '[email protected]:youraccount/yourproject.git');
+set('bin/php', '/home/www/example-project-directory/.bin/php');
+set('web_path', 'public/');
+
+host('live')
+    ->hostname('production.example.org')
+    ->user('deploy')
+    ->set('branch', 'main')
+    ->set('public_urls', ['https://production.example.org'])
+    ->set('deploy_path', '/home/www/example-project-directory/live');
diff --git a/Documentation/Installation/Magallanes/Index.rst b/Documentation/Installation/Magallanes/Index.rst
@@ -0,0 +1,16 @@
+.. include:: /Includes.rst.txt
+
+.. index:: Deployment; Magallanes
+
+.. _deployment-magallanes:
+
+==========
+Magallanes
+==========
+
+Another deployment tool for PHP applications written in PHP: https://www.magephp.com/
+
+..  literalinclude:: _mage.yml
+    :language: yaml
+    :caption: .mage.yml
+
diff --git a/Documentation/Installation/Magallanes/_mage.yml b/Documentation/Installation/Magallanes/_mage.yml
@@ -0,0 +1,39 @@
+magephp:
+  log_dir: ./.mage/logs
+  composer:
+    path: composer
+  exclude:
+    - ./.ddev
+    - ./.git
+    - ./.mage
+    - ./public/fileadmin
+    - ./public/typo3temp
+    - ./var
+    - ./.mage.yml
+    - ./composer.json
+    - ./composer.lock
+    - ./LICENSE
+    - ./README.md
+  environments:
+    main:
+      user: ssh-user
+      from: ./
+      host_path: /srv/vhosts/target-path/site/mage
+      releases: 3
+      hosts:
+        - production.example.org
+      pre-deploy:
+        - exec: { cmd: "composer install --no-dev --no-progress --optimize-autoloader"}
+      on-deploy:
+        - fs/link: { from: "../../../../shared/public/fileadmin", to: "public/fileadmin" }
+        - fs/link: { from: "../../../../shared/public/typo3temp", to: "public/typo3temp" }
+        - fs/link: { from: "../../../shared/var", to: "var" }
+      on-release:
+      post-release:
+        - exec: { cmd: './bin/typo3 backend:lock', timeout: 9000  }
+        - exec: { cmd: './bin/typo3cms database:updateschema *.add,*.change', timeout: 9000  }
+        - exec: { cmd: './bin/typo3cms cache:flush', timeout: 9000  }
+        - exec: { cmd: './bin/typo3 upgrade:run', timeout: 9000  }
+        - exec: { cmd: './bin/typo3 backend:unlock', timeout: 9000  }
+      post-deploy:
+
diff --git a/Documentation/Installation/Surf/Index.rst b/Documentation/Installation/Surf/Index.rst
@@ -0,0 +1,17 @@
+.. include:: /Includes.rst.txt
+
+.. index:: Deployment; TYPO3 Surf
+
+.. _deployment-typo3-surf:
+
+==========
+TYPO3 Surf
+==========
+
+:doc:`TYPO3 Surf <ext_surf:Index>` is a deployment tool written in PHP.
+
+
+..  literalinclude:: _MyDeployment.php
+    :language: php
+    :caption: MyDeployment.php
+
diff --git a/Documentation/Installation/Surf/_MyDeployment.php b/Documentation/Installation/Surf/_MyDeployment.php
@@ -0,0 +1,60 @@
+<?php
+/** @var \TYPO3\Surf\Domain\Model\Deployment $deployment */
+
+$node = new \TYPO3\Surf\Domain\Model\Node('my.node.com');
+$node
+    ->setHostname($node->getName())
+    ->setOption('username', 'myuser')
+    ->setOption('phpBinaryPathAndFilename', '/usr/local/bin/php_cli');
+
+$application = new \TYPO3\Surf\Application\TYPO3\CMS();
+$application
+    ->setDeploymentPath('/httpdocs')
+    ->setOption('baseUrl', 'https://my.node.com/')
+    ->setOption('webDirectory', 'public')
+    ->setOption('symlinkDataFolders', ['fileadmin'])
+    ->setOption('repositoryUrl', 'file://' . dirname(__DIR__))
+    ->setOption('keepReleases', 3)
+    ->setOption('composerCommandPath', 'composer')
+    ->setOption('rsyncExcludes', [
+        '.ddev',
+        '.git',
+        $application->getOption('webDirectory') . '/fileadmin',
+        'packages/**.sass'
+    ])
+    ->setOption(TYPO3\Surf\Task\TYPO3\CMS\FlushCachesTask::class . '[arguments]', [])
+    ->addSymlink($application->getOption('webDirectory') . '/config/system/settings.php', '../../../../shared/Configuration/settings.php')
+    ->addNode($node);
+
+$deployment
+    ->addApplication($application)
+    ->onInitialize(
+        function () use ($deployment, $application) {
+            $deployment
+                ->getWorkflow()
+                ->beforeTask(
+                    \TYPO3\Surf\Task\TYPO3\CMS\SetUpExtensionsTask::class,
+                    \TYPO3\Surf\Task\TYPO3\CMS\CompareDatabaseTask::class,
+                    $application
+                )
+                ->beforeStage(
+                    'transfer',
+                    \TYPO3\Surf\Task\Php\WebOpcacheResetCreateScriptTask::class,
+                    $application
+                )
+                ->afterStage('switch',
+                    \TYPO3\Surf\Task\Php\WebOpcacheResetExecuteTask::class,
+                    $application
+                )
+                // CreatePackageStatesTask is done by post-autoload-dump script and can be removed
+                // https://github.com/TYPO3/TYPO3.CMS.BaseDistribution/blob/9.x/composer.json#L38
+                ->removeTask(
+                    \TYPO3\Surf\Task\TYPO3\CMS\CreatePackageStatesTask::class,
+                    $application
+                )
+                ->removeTask(
+                    \TYPO3\Surf\Task\TYPO3\CMS\CopyConfigurationTask::class,
+                    $application
+                );
+        }
+    );