[TASK] Move automatic deployment to TYPO3 explained (#501)

Chapter needs more love in general: #498

Releases: main, 13.4, 12.4

(cherry picked from commit 4d7727d)

Documentation/Glossary/Index.rst

@@ -103,7 +103,7 @@ Glossary
         easy to start developing, testing, and managing TYPO3 projects without complex configuration.
 
     Deployment
-        :ref:`Deployment <t3start:deployment>` refers to the process of transferring your website’s code, content, and settings from a
+        :ref:`Deployment <deployment>` refers to the process of transferring your website’s code, content, and settings from a
         development environment to a live server, making it accessible to users online.
 
     Debug mode

Documentation/Installation/DeployTYPO3.rst

@@ -1,38 +1,77 @@
 ..  include:: /Includes.rst.txt
-
 ..  index:: deployment, composer, production setup
 
 ..  _deploytypo3:
+..  _deployment:
 
 ===============
 Deploying TYPO3
 ===============
 
-This guide outlines the steps required to manually deploy TYPO3 and ensure the installation
-is secure and ready to be used in a production context. This guide also highlights a number of
-automation tools that can help automate the deployment process.
+..  _deployment-git-composer:
+
+Using Git and Composer on the webserver
+=======================================
+
+*   Check if Composer is available on the production server. If it is not
+    available consider to use the
+    `latest composer.phar <https://getcomposer.org/download/>`__.
+*   Keep all development related files in a Git repository.
+*   Clone this repository on your production server.
+*   Copy the database to the production server.
+*   Install TYPO3 without dev dependencies on the production server:
+
+    ..  code-block::
+
+        composer install --no-dev
+
+*   Compare the database
+*   Fix file permissions
+*   Clear caches
+
+..  todo: Link these steps once documented
 
-There are several different ways to deploy TYPO3. One of the more simple
-options is to manually copy its files and database
-from a local machine to the live server, adjusting the configuration where
-necessary.
+If you do a `composer install` directly on the production server you might
+experience some problems. For this reason some developers and administrators
+decide not to do it:
 
-General Deployment Steps
-========================
+*   There can be several minutes of downtime even if the installation goes
+    smoothly.
+*   The installation might fail if some packages are not available.
+*   You might accidentally call `composer update` as is often done during
+    development and do unintended, untested updates.
+*   You might omit the `--no-dev` option and accidentally install packages
+    that are not save to be used during production.
+
+Some of these problems can be fixed by using a symlink strategy where one
+directory is running on production and another one is being updated.
+
+..  _deployment-copy-files:
+
+Build locally and copy all files and symlinks to the server
+===========================================================
 
 *   Build the local environment (installing everything necessary for the website)
 *   Run :bash:`composer install --no-dev` to install without development dependencies
 *   Copy files to the production server
 *   Copy the database to the production server
-*   Clearing the caches
+*   Compare the database
+*   Fix file permissions
+*   Clear caches
+
+..  todo: Link these steps once documented
+
+There can be several problems with this strategy:
+
+*   Copying files or unzipping files can be slow, there can be several minutes
+    of downtime.
+*   A TYPO3 installation depends on symlinks. Make sure these symlinks are
+    preserved during copying and or compressing files.
 
-.. note::
+..  _deployment-automatic:
 
-    The :bash:`composer install` command should not be run on the live environment.
-    Ideally, Composer should only run locally or on a dedicated deployment machine,
-    to allow testing before going live.
+Automatic deployment
+====================
 
-    To avoid conflicts between the local and the server's PHP version,
-    the server's PHP version can be defined in the :file:`composer.json` file
-    (e.g. ``{"platform": {"php": "8.2"}}``), so Composer will always check
-    the correct dependencies.
+There are multiple tools that can be used to automate deployment. Read more
+about it: :ref:`TYPO3 Explained, automatic deployment <t3coreapi:deployment-automatic>`.