[TASK] Move advanced installation chapters from Getting started (TYPO…

…3-Documentation#4864)

We will keep basic installation guides in the getting started guide but have a home here for all advanced knowledge.

Content was not changed. Manual backport to 12.4 needed

Releases: main, 13.4, 12.4

Documentation/Administration/Index.rst

@@ -12,12 +12,12 @@ TYPO3 administration
     :gap: 4
     :card-height: 100
 
-    ..  card:: TYPO3 Installation (Composer)
+    ..  card:: TYPO3 Installation
 
-        The getting started guide covers every step required to
-        install TYPO3 using Composer.
+        This chapter covers topics about :ref:`system-requirements`, :ref:`installation`,
+        :ref:`production-settings`, :ref:`deploytypo3` and :ref:`tunetypo3`.
 
-        :ref:`Getting started: TYPO3 installation <t3start:install>`
+        :ref:`TYPO3 installation <installation_index>`
 
     ..  card:: Upgrading TYPO3
 
@@ -33,5 +33,6 @@ TYPO3 administration
     :hidden:
     :glob:
 
+    Installation/Index
     */Index
     *

Documentation/Administration/Installation/DeployTYPO3.rst

@@ -0,0 +1,111 @@
+..  include:: /Includes.rst.txt
+
+..  index:: deployment, composer, production setup
+
+..  _deploytypo3:
+
+===============
+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.
+
+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.
+
+General Deployment Steps
+========================
+
+*   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
+
+.. note::
+
+    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.
+
+    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.
+
+Deployment Automation
+=====================
+
+A typical setup for deploying web applications consists of three different parts:
+
+*   The local environment (for development)
+*   The build environment (for reproducible builds). This can be a controlled local environment or a remote continuous integration server (for example Gitlab CI or Github Actions)
+*   The live (production) environment
+
+To get an application from the local environment to the production system, the usage of a deployment tool and/or a continuous integration solution is recommended. This ensures that only version-controlled code is deployed and that builds are reproducible. Ideally setting a new release live will be an atomical operation and lead to no downtime. If there are errors in any of the deployment or test stages, most deployment tools will initiate an automatic "rollback" preventing that an erroneous build is released.
+
+One widely employed strategy is the "symlink-switching" approach:
+
+In that strategy, the webserver serves files from a virtual path :path:`releases/current/public` which consists of a symlink :path:`releases/current` pointing to the latest deployment ("release"). That symlink is switched after a new release has been successfully prepared.
+The latest deployment contains symlinks to folders that should be common among all releases (commonly called "shared folders").
+
+Usually the database is shared between releases and upgrade wizards and schema upgrades are run automatically before or
+shortly after the new release has been set live.
+
+This is an exemplatory directory structure of a "symlink-switching" TYPO3 installation:
+
+..  directory-tree::
+
+    *   :path:`shared`
+
+        *   :path:`fileadmin`
+        *   :path:`var`
+
+            *   :path:`charset`
+            *   :path:`lock`
+            *   :path:`log`
+            *   :path:`session`
+
+    *   :path:`releases`
+
+        *   :path:`current -> ./release1` (symlink to current release)
+        *   :path:`release1`
+
+            *   :path:`public` (webserver root, via releases/current/public)
+
+                *   :path:`typo3conf`
+                *   :path:`fileadmin -> ../../../shared/fileadmin` (symlink)
+                *   :file:`index.php`
+
+            *   :path:`var`
+
+                *   :path:`build`
+                *   :path:`cache`
+                *   :path:`charset -> ../../../shared/var/charset` (symlink)
+                *   :path:`labels`
+                *   :path:`lock -> ../../../shared/var/lock` (symlink)
+                *   :path:`log -> ../../../shared/var/log` (symlink)
+                *   :path:`session -> ../../../shared/var/session` (symlink)
+
+            *   :path:`vendor`
+            *   :file:`composer.json`
+            *   :file:`composer.lock`
+
+
+The files in :path:`shared` are shared between different releases of a web site.
+The :path:`releases` directory contains the TYPO3 code that will change between the release of each version.
+
+When using a deployment tool this kind of directory structure is usually created automatically.
+
+The following section contains examples for various deployment tools and how they can be configured to use TYPO3:
+
+..  toctree::
+    :titlesonly:
+
+    Deployer/Index
+    Surf/Index
+    Magallanes/Index

Documentation/Administration/Installation/Deployer/Index.rst

@@ -0,0 +1,17 @@
+.. include:: /Includes.rst.txt
+
+.. index:: Deployment; Deployer
+
+.. _deployment-deployer:
+
+========
+Deployer
+========
+
+`Deployer <https://deployer.org>`__ is a deployment tool
+written in PHP. A full description about how to get deployer running
+for TYPO3 can be found at https://t3planet.com/blog/typo3-deploy/
+
+..  literalinclude:: _deploy.php
+    :language: php
+    :caption: deploy.php

Documentation/Administration/Installation/Deployer/_deploy.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Deployer;
+
+require_once(__DIR__ . '/vendor/sourcebroker/deployer-loader/autoload.php');
+
+new \SourceBroker\DeployerExtendedTypo3\Loader();
+
+set('repository', 'git@github.com: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');

Documentation/Administration/Installation/EnvironmentConfiguration.rst

@@ -0,0 +1,161 @@
+.. include:: /Includes.rst.txt
+
+.. index:: Environment; Configuration; .env ; dotenv
+
+.. _environment-configuration:
+
+========================
+Configuring environments
+========================
+
+A TYPO3 instance is often used in different contexts that can adapt to your
+custom needs:
+
+*   Local development
+*   Staging environment
+*   Production environment
+*   Feature preview environments
+*   ...
+
+These can be managed via the same installation by applying different values
+for configuration options.
+
+The configuration options can be managed either by an :file:`.env` file or just
+simple PHP files. Each environment would load the specific
+:file:`.env`/PHP file, which is usually bound to an
+:ref:`application context <t3coreapi:application-context>` (`Development`,
+`Production`).
+
+For example, using a :file:`.env` file in your project root, you can define several
+variables:
+
+..  literalinclude:: Environments/_example.env
+    :language: bash
+    :caption: <project-root>/.env
+
+The next step is to retrieve these values in the TYPO3 application bootstrap
+process. The best place for this is inside :file:`system/additional.php` (see
+:ref:`t3coreapi:configuration-files`). The PHP code for this could look like:
+
+..  literalinclude:: Environments/_additional.php
+    :language: php
+    :caption: config/system/additional.php
+
+Each environment would have its own :file:`.env` file, which is only stored on
+the corresponding target system. The development environment file could
+be saved as :file:`.env.example` or delivered as the default :file:`.env`
+in your project.
+
+..  todo: Should we have a distinct "Versioning" chapter?
+
+It is not recommended to store the actual :file:`.env` file in your version control
+system (e.g. Git), only an example without sensitive information. The main reason
+is that these files usually hold credentials or other sensitive information.
+
+You should only store environment-specific configuration values in such a
+configuration file. Do not use this to manage all the TYPO3 configuration options.
+Examples of well-suited configuration options:
+
+* :ref:`t3coreapi:password-policies`
+* :ref:`t3coreapi:error-handling-configuration`
+* :ref:`t3coreapi:typo3ConfVars_mail`
+* :ref:`t3coreapi:typo3ConfVars_sys_encryptionKey`
+* :ref:`t3coreapi:security-install-tool`
+* Settings, tokens and URLs to additional services (Redis, Solr, third-party systems, ...)
+
+..  note::
+    The URL of your environment must be configured through
+    :ref:`site configuration <t3coreapi:sitehandling>` variables, and
+    those can actually refer to environment variables as outlined in
+    :ref:`t3coreapi:sitehandling-using-env-vars`.
+
+The following sections describe this implementation process in depth.
+
+.. _environment-dotenv:
+
+.env / dotenv files
+===================
+
+A central advantage of :file:`.env` files is that environment variables can
+also be set in :ref:`t3coreapi:cli-mode` CLI context or injected via
+Continuous Integration/Deployment (CI/CD) systems (GitLab/GitHub) or even
+webserver configuration. It is also helpful to have a central place for
+environment-specific configuration.
+
+To let your TYPO3 configuration parse keys and values stored in such a file,
+you need a library like https://github.com/symfony/dotenv/ or
+https://github.com/vlucas/phpdotenv/, and parse it in your :file:`system/additional.php`
+
+You can require these libraries through Packagist/Composer.
+
+Example for `symfony/dotenv`:
+
+..  literalinclude:: Environments/_dotenv-symfony.php
+    :language: php
+    :caption: config/system/additional.php
+
+Example for `vlucas/phpdotenv`:
+
+..  literalinclude:: Environments/_dotenv-vlucas.php
+    :language: php
+    :caption: config/system/additional.php
+
+Once this code has loaded the content from the :file:`.env` file into :php:`$_ENV`
+variables, you can access contents of the variables anywhere you need.
+
+.. _environment-helhum-dotenv:
+
+helhum/dotenv-connect
+---------------------
+
+You can also use https://github.com/helhum/dotenv-connector/ (via the Packagist
+package `helhum/dotenv-connector`) to allow accessing :php:`$_ENV` variables
+directly within the Composer autoload process.
+
+This has two nice benefits:
+
+*   You can even set the `TYPO3_CONTEXT` application context environment variable
+    through an :file:`.env` file, and no longer need to specify that in your webserver
+    configuration (for example, via :file:`.htaccess` or virtual host configuration).
+*   You do not need to add and maintain such loading code to your :file:`additional.php`
+    file.
+
+The drawback is that you will have an additional dependency on another package, and
+glue code that is outside of your own implementation.
+
+.. _environment-phpconfig:
+
+Plain PHP configuration files
+=============================
+
+If the concept of requiring a specific file format and their loader dependencies
+seems like too much overhead for you, something similar can be achieved
+by including environment-specific PHP files.
+
+For example, you can create a custom file like :file:`system/environment.php` that
+will only be placed on your specific target server (and not be kept in your versioning
+control system).
+
+..  literalinclude:: Environments/_environment.php
+    :language: php
+    :caption: config/system/environment.php
+
+This file would also need to be loaded through the additional configuration
+workflow (which can be kept in your versioning control system):
+
+..  literalinclude:: Environments/_additional-native.php
+    :language: php
+    :caption: config/system/additional.php
+
+Of course, you can move such a file to a special :file:`Shared/Data/` directory
+(see :ref:`deploytypo3`), as long as you take care the file is outside
+your public web root directory scope.
+
+The file :file:`additional.php` can still contain custom changes that shall
+be applied to every environment of yours, and that is not managed through
+:file:`settings.php`.
+
+..  hint::
+    The file :file:`settings.php` is used by TYPO3 to store changes made through
+    the GUI of the backend. :file:`additional.php` always has the higher
+    priority, so configuration values there will overwrite the GUI configuration.

Documentation/Administration/Installation/Environments/_additional-context.php

@@ -0,0 +1,23 @@
+<?php
+
+use TYPO3\CMS\Core\Core\Environment;
+
+defined('TYPO3') or die();
+
+$context       = Environment::getContext();
+$baseDirectory = Environment::getConfigPath();
+$subContexts   = explode('/', strtolower($context));
+
+// Include a file like system/production.php, system/development.php
+// or system/staging.php - depending on the TYPO3_CONTEXT application
+// context that is currently active.
+if (file_exists($baseDirectory . '/system/' . $subContexts[0] . '.php')) {
+    include $baseDirectory . '/system/' . $subContexts[0] . '.php';
+}
+
+// ALSO overload an environment-specific configuration, to allow more
+// specific environment configuration on top of the "global" application
+// context.
+if (file_exists($baseDirectory . '/system/environment.php')) {
+    include $baseDirectory . '/system/environment.php';
+}

Documentation/Administration/Installation/Environments/_additional-native.php

@@ -0,0 +1,5 @@
+<?php
+
+defined('TYPO3') or die();
+
+require __DIR__ . '/environment.php';

Documentation/Administration/Installation/Environments/_additional.php

@@ -0,0 +1,25 @@
+<?php
+
+defined('TYPO3') or die();
+
+$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport']
+    = $_ENV['TYPO3_MAIL_TRANSPORT'];
+$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_smtp_server']
+    = $_ENV['TYPO3_MAIL_TRANSPORT_SMTP_SERVER'];
+$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_smtp_username']
+    = $_ENV['TYPO3_MAIL_TRANSPORT_SMTP_USERNAME'];
+$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_smtp_password']
+    = $_ENV['TYPO3_MAIL_TRANSPORT_SMTP_PASSWORD'];
+
+$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default']['dbname']
+    = $_ENV['TYPO3_DB_DBNAME'];
+$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default']['host']
+    = $_ENV['TYPO3_DB_HOST'];
+$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default']['password']
+    = $_ENV['TYPO3_DB_PASSWORD'];
+$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default']['user']
+    = $_ENV['TYPO3_DB_USER'];
+
+$GLOBALS['TYPO3_CONF_VARS']['BE']['lockRootPath'] = [
+    $_ENV['TYPO3_BE_LOCKROOTPATH'],
+];

Documentation/Administration/Installation/Environments/_dotenv-symfony.php

@@ -0,0 +1,7 @@
+<?php
+
+use Symfony\Component\Dotenv\Dotenv;
+use TYPO3\CMS\Core\Core\Environment;
+
+$dotenv = new Dotenv();
+$dotenv->load(Environment::getProjectPath() . '/.env');