[Backport 13.4] [TASK] Add section about 'htaccess', also for upgrades (

#5088)

* [TASK] Add section about 'htaccess', also for upgrades

This adds a section about what the 'htaccess' file is used for,
and a section how to adapt webserver configuration for major upgrades.

Sections are cross-referenced.

Drive-by fixes: Remove redundant "include" statements in includes.

Closes https://forge.typo3.org/issues/99041

Releases: main, 13.4, 12.4

* Update Documentation/Administration/Installation/SystemRequirements/Apache.rst.txt

Co-authored-by: Lina Wolf <[email protected]>

* [TASK] Move headlines around

---------

Co-authored-by: Garvin Hicking <[email protected]>
Co-authored-by: Lina Wolf <[email protected]>

Documentation/Administration/Installation/SystemRequirements/Apache.rst.txt

@@ -1,14 +1,39 @@
-.. include:: /Includes.rst.txt
 
-.. _system-requirements-apache:
+..  _system-requirements-apache:
 
 During the initial installation, TYPO3's default :file:`.htaccess` file is copied to the installation root folder.
 
-**Virtual Host Record**
+..  _htaccess:
+
+.htaccess
+=========
+
+The :file:`.htaccess` file allows to configure Apache-specific TYPO3-related webserver settings.
+
+The most important use of the file is to configure `RewriteRules`, security settings, PHP settings and MIME-type
+handling.
+
+TYPO3 ships a boilerplate configuration file (`.htaccess <https://github.com/TYPO3/typo3/blob/main/typo3/sysext/install/Resources/Private/FolderStructureTemplateFiles/root-htaccess>`__),
+which is installed on first-time installation and then is assumed to be maintained depending on your project.
+
+This means, on major TYPO3 updates, you need to ensure possible new TYPO3 adjustments are integrated in your
+configuration. If you never update the file manually, copy over the contents of the new file from the
+TYPO3 upgrade release. See :ref:`<maintain-htaccess>` for details on maintaining the file after a major
+version upgrade.
+
+The TYPO3 environment check (:guilabel:`Admin Tools > Environment > Check Directory Status`) will report whether a :file:`.htaccess` file differs from the default.
+
+..  _vhost-records:
+
+Virtual Host Record
+===================
 
 *  `AllowOverride <https://httpd.apache.org/docs/current/mod/core.html#allowoverride>`__ needs to include "Indexes" and "FileInfo" in the Virtual Host record.
 
-**Apache Modules**
+..  _apache-modules:
+
+Apache Modules
+==============
 
 The following Apache modules are required. The list is based on what is used in
 the default TYPO3

Documentation/Administration/Upgrade/Major/PostupgradeTasks/BackendTranslations.rst.txt

@@ -1,5 +1,3 @@
-..  include:: /Includes.rst.txt
-
 ..  _update-translations:
 
 In the Install tool, go to the module "Maintenance" -> "Manage languages" and

Documentation/Administration/Upgrade/Major/PostupgradeTasks/ClearCaches.rst.txt

@@ -1,5 +1,3 @@
-..  include:: /Includes.rst.txt
-
 ..  _clear_caches:
 
 You have to clear all caches when upgrading.

Documentation/Administration/Upgrade/Major/PostupgradeTasks/DatabaseAnalyser.rst.txt

@@ -1,5 +1,3 @@
-..  include:: /Includes.rst.txt
-
 ..  _database_analyser:
 
 While in the previous step, tables and columns have been *changed or added* to

Documentation/Administration/Upgrade/Major/PostupgradeTasks/Index.rst

@@ -45,3 +45,10 @@ Update backend translations
 ===========================
 
 ..  include:: BackendTranslations.rst.txt
+
+..  _maintain-htaccess:
+
+Verify webserver configuration (.htaccess)
+==========================================
+
+..  include:: WebserverConfiguration.rst.txt

Documentation/Administration/Upgrade/Major/PostupgradeTasks/UpgradeWizard.rst.txt

@@ -1,5 +1,3 @@
-..  include:: /Includes.rst.txt
-
 ..  _use-the-upgrade-wizard:
 
 Enter the Install Tool at :samp:`https://example.org/typo3/install.php` on your

Documentation/Administration/Upgrade/Major/PostupgradeTasks/UserSettings.rst.txt

@@ -1,5 +1,3 @@
-..  include:: /Includes.rst.txt
-
 You might consider clearing the Backend user preferences. This
 can avoid problems, if something in the upgrade requires this. Go to
 "Clean up", scroll to "Reset user preferences" and click "Reset backend

Documentation/Administration/Upgrade/Major/PostupgradeTasks/WebserverConfiguration.rst.txt

@@ -0,0 +1,15 @@
+After an update, the :file:`.htaccess` file may need adoption for the latest TYPO3
+major version (for Apache webservers), :ref:`see details on .htaccess <htaccess>`.
+
+Compare the file :file:`vendor/typo3/cms-install/Resources/Private/FolderStructureTemplateFiles/root-htaccess`
+(or `.htaccess <https://github.com/TYPO3/typo3/blob/main/typo3/sysext/install/Resources/Private/FolderStructureTemplateFiles/root-htaccess>`__)
+with your project's :file:`.htaccess` file and adapt new rules accordingly. If you never
+edited the file, copy it over to your project to ensure using the most recent version.
+
+Your project's :file:`.htaccess` file should be under version control and part of your
+deployment strategy.
+
+For NGINX based webservers, you may also need to adapt configuration. The changelogs of
+TYPO3 will contain upgrade instructions, like in
+:ref:`Deprecation: #87889 - TYPO3 backend entry point script deprecated <changelog:deprecation-87889-1705928143>`
+

Documentation/Security/GuidelinesAdministrators/RestrictAccessToFiles.rst

@@ -85,6 +85,9 @@ should compare their specific version with the reference files found at
 and :t3src:`install/Resources/Private/FolderStructureTemplateFiles/root-web-config`
 and adapt or update local versions if needed.
 
+See :ref:`<maintain-htaccess>` for details on maintaining the file after a major
+version upgrade.
+
 
 NGINX web servers
 =================