diff --git a/Documentation/Administration/Index.rst b/Documentation/Administration/Index.rst index 90a41cd5cc..1b53b0fe9c 100644 --- a/Documentation/Administration/Index.rst +++ b/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 ` + :ref:`TYPO3 installation ` .. card:: Upgrading TYPO3 @@ -33,5 +33,6 @@ TYPO3 administration :hidden: :glob: + Installation/Index */Index * diff --git a/Documentation/Administration/Installation/DeployTYPO3.rst b/Documentation/Administration/Installation/DeployTYPO3.rst new file mode 100644 index 0000000000..eced59fc28 --- /dev/null +++ b/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 diff --git a/Documentation/Administration/Installation/Deployer/Index.rst b/Documentation/Administration/Installation/Deployer/Index.rst new file mode 100644 index 0000000000..a9aca4b3f7 --- /dev/null +++ b/Documentation/Administration/Installation/Deployer/Index.rst @@ -0,0 +1,17 @@ +.. include:: /Includes.rst.txt + +.. index:: Deployment; Deployer + +.. _deployment-deployer: + +======== +Deployer +======== + +`Deployer `__ 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 diff --git a/Documentation/Administration/Installation/Deployer/_deploy.php b/Documentation/Administration/Installation/Deployer/_deploy.php new file mode 100644 index 0000000000..acc0a05b66 --- /dev/null +++ b/Documentation/Administration/Installation/Deployer/_deploy.php @@ -0,0 +1,18 @@ +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/Administration/Installation/EnvironmentConfiguration.rst b/Documentation/Administration/Installation/EnvironmentConfiguration.rst new file mode 100644 index 0000000000..5caa740d9d --- /dev/null +++ b/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 ` (`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: /.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 ` 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. diff --git a/Documentation/Administration/Installation/Environments/_additional-context.php b/Documentation/Administration/Installation/Environments/_additional-context.php new file mode 100644 index 0000000000..f5208730b3 --- /dev/null +++ b/Documentation/Administration/Installation/Environments/_additional-context.php @@ -0,0 +1,23 @@ +load(Environment::getProjectPath() . '/.env'); diff --git a/Documentation/Administration/Installation/Environments/_dotenv-vlucas.php b/Documentation/Administration/Installation/Environments/_dotenv-vlucas.php new file mode 100644 index 0000000000..bea666e2b7 --- /dev/null +++ b/Documentation/Administration/Installation/Environments/_dotenv-vlucas.php @@ -0,0 +1,9 @@ +load(); diff --git a/Documentation/Administration/Installation/Environments/_environment.php b/Documentation/Administration/Installation/Environments/_environment.php new file mode 100644 index 0000000000..5fdfbb82c3 --- /dev/null +++ b/Documentation/Administration/Installation/Environments/_environment.php @@ -0,0 +1,25 @@ +` + + System requirements for the host operating system, including its web + server and database and how they should be configured prior to + installation. + + .. card:: :ref:`Installing TYPO3 ` + + The Installation Guide covers everything needed to install TYPO3. Including a preinstallation + checklist and a detailed walk through that details every step of the installation process. + + .. card:: :ref:`Deploying TYPO3 ` + + The deployment guide highlights some of solutions available that can help automate the process of deploying TYPO3 to + a remote server. + + .. card:: :ref:`Tuning TYPO3 ` + + This chapter contains information on how to configure and optimize the infrastructure running TYPO3. + + .. card:: :ref:`TYPO3 Release Integrity ` + + Every release of TYPO3 is electronically signed by the TYPO3 release team. + In addition, every TYPO3 package also contains a unique file hash that + can be used to ensure file integrity when downloading the release. This guide + details how these signatures can be checked and how file hashes can be compared. + + .. card:: :ref:`Legacy Installation Guide ` + + Looking to install TYPO3 the classic way? Whilst this method of installation is no longer recommended, the Legacy Installation + Guide demonstrates how TYPO3 can be installed without using Composer. + +.. toctree:: + :hidden: + :titlesonly: + + SystemRequirements/Index + Install + EnvironmentConfiguration + ProductionSettings + TuneTYPO3 + DeployTYPO3 + LegacyInstallation diff --git a/Documentation/Administration/Installation/Install.rst b/Documentation/Administration/Installation/Install.rst new file mode 100644 index 0000000000..f2a1b21d23 --- /dev/null +++ b/Documentation/Administration/Installation/Install.rst @@ -0,0 +1,275 @@ +.. include:: /Includes.rst.txt + +.. index:: installation, deployment, requirements + +.. _installation: + +================ +Installing TYPO3 +================ + +.. tip:: + For a tutorial on how to quickly install TYPO3 on DDEV see + :ref:`Getting Started Guide: Installing TYPO3 with + DDEV `. + +This chapter covers each of the steps required to install TYPO3 using Composer. + +For more information on how to deploy TYPO3 to a live environment, visit the +:ref:`deploying TYPO3 ` chapter. + +.. contents:: + :local: + +Pre-installation checklist +========================== + +* Command line (CLI) access with the ability to create directories and + symbolic links. +* Access to `Composer `__ via the CLI (for local + development) +* Access to the web server's root directory +* Database with appropriate credentials + + +Create the project with Composer +================================ + +The following command will install TYPO3 v12. If you want to install another +version of TYPO3 find documentation by using the version selector on the left side of this page. + +At the root level of your web server, execute the following command: + +.. tabs:: + + .. group-tab:: bash + + .. code-block:: bash + + composer create-project typo3/cms-base-distribution example-project-directory "^12" + + .. group-tab:: powershell + + .. code-block:: powershell + + composer create-project "typo3/cms-base-distribution:^12" example-project-directory + + .. group-tab:: ddev + + .. code-block:: bash + + # Create a directory for your project + mkdir example-project-directory + + # Go into that directory + cd example-project-directory + + # Tell DDEV to create a new project of type "typo3" + # 'docroot' MUST be set to 'public' + # At least PHP 8.1 is required by TYPO3 v12. Adapt the PHP version to your needs. + ddev config --project-type=typo3 --docroot=public --php-version 8.1 + + # Start the server + ddev start + + # Fetch a basic TYPO3 installation and its dependencies + ddev composer create "typo3/cms-base-distribution:^12" + +.. tip:: + The command `composer create-project` expect a completely empty directory. Do not open the project in an + IDE like PhpStorm before the commands have been executed. IDEs will usually create a hidden folder like + :path:`.idea` that will cause an error message with the `composer create-project` command. + `ddev composer create` also works on non-empty paths. + + +This command pulls down the latest release of the given TYPO3 version and places +it in the :file:`example-project-directory/`. + +After this command has finished running, the :file:`example-project-directory/` +folder contains the following files and folders, where :file:`var/` +is added after the first login into the TYPO3 backend: + +.. directory-tree:: + + * :path:`public` + * :path:`var` + * :path:`vendor` + * :file:`.gitignore` + * :file:`composer.json` + * :file:`composer.lock` + * :file:`LICENSE` + * :file:`README.md` + + +Run the setup process +===================== + +Setup TYPO3 in the console +-------------------------- + +.. versionadded:: 12.1 + A :ref:`CLI command ` `setup` has + been introduced as an alternative to the existing + :abbr:`GUI (Graphical User Interface)`-based web installer. + +Interactive / guided setup (questions/answers): + +.. tabs:: + + .. group-tab:: bash + + .. code-block:: bash + + # Use console command to run the install process + # or use the Install Tool GUI (See below) + ./vendor/bin/typo3 setup + + .. group-tab:: powershell + + .. code-block:: powershell + + # Use console command to run the install process + # or use the Install Tool GUI (See below) + ./vendor/bin/typo3 setup + + .. group-tab:: ddev + + .. code-block:: bash + + # Use console command to run the install process + # or use the Install Tool GUI (See below) + ddev exec ./vendor/bin/typo3 setup + +Or use the GUI installer in the browser +--------------------------------------- + +Create an empty file called `FIRST_INSTALL` in the `public/` directory: + +.. tabs:: + + .. group-tab:: bash + + .. code-block:: bash + + touch example-project-directory/public/FIRST_INSTALL + + .. group-tab:: powershell + + .. code-block:: powershell + + echo $null >> public/FIRST_INSTALL + + .. group-tab:: ddev + + .. code-block:: bash + + ddev exec touch public/FIRST_INSTALL + + +.. directory-tree:: + + * :path:`public` + + * :file:`FIRST_INSTALL` + + * :path:`var` + * :path:`vendor` + * :file:`.gitignore` + * :file:`composer.json` + * :file:`composer.lock` + * :file:`LICENSE` + * :file:`README.md` + +.. _install-access-typo3-via-a-web-browser: + +Access TYPO3 via a web browser +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After you have configured your web server to point at the `public` directory of +your project, TYPO3 can be accessed via a web browser. When accessing a new site +for the first time, TYPO3 automatically redirects all requests to +:samp:`/typo3/install.php` to complete the installation process. + +.. tip:: + When accessing the page via HTTPS, a "Privacy error" or similar warning is + likely to occur. In a local environment it is safe to ignore this warning by + forcing the browser to ignore similar exceptions for this domain. + + The warning is due to the fact that self-signed certificates are being used. + + If there is a :ref:`trustedHostsPattern ` + error on initial access, accessing TYPO3 without HTTPS (`http://`) is also + an option. + + +Scan environment +~~~~~~~~~~~~~~~~ + +TYPO3 will now scan the host environment. During the scan TYPO3 will check the +host system for the following: + +* Minimum required version of PHP is installed. +* Required PHP extensions are loaded. +* :file:`php.ini` is configured. +* TYPO3 is able to create and delete files and directories within the + installation's root directory. + +If no issues are detected, the installation process can continue. + +In the event that certain criteria are not met, TYPO3 will display a list of +issues it has detected accompanied by a resolution for each issue. + +Once changes have been made, TYPO3 can re-scan the host environment by reloading +the page :samp:`https://example-project-site.local/typo3/install.php`. + +.. include:: /Images/AutomaticScreenshots/QuickInstall/Step1SystemEnvironment.rst.txt + +Select a database +~~~~~~~~~~~~~~~~~ + +Select a database connection driver and enter the credentials for the database. + +.. include:: /Images/AutomaticScreenshots/QuickInstall/Step2DatabaseConnection.rst.txt + +TYPO3 can either connect to an existing empty database or create a new one. + +The list of databases available is dependent on which database drivers are installed on the host. + + +For example, if an instance of TYPO3 is intended to be used with a MySQL database then the PHP extension `pdo_mysql` is required. +Once it is installed, :guilabel:`MySQL Database` will be available as an option. + + +.. include:: /Images/AutomaticScreenshots/QuickInstall/Step3ChooseDb.rst.txt + +Create administrative user & set site name +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An administrator account needs to be created to gain access to TYPO3's backend. + +An email address for this user can also be specified and a name can be given. + +.. include:: /Images/AutomaticScreenshots/QuickInstall/Step4AdminUserSitename.rst.txt + +.. note:: + The password must comply with the configured + :ref:`password policy `. + +Initialize +---------- + +TYPO3 offers two options for initialisation: creating an empty starting page or +it can go directly to the backend administrative interface. + +Beginners should +select the first option and allow TYPO3 to create an empty starting page. +This will also generate a site configuration file. + +.. include:: /Images/AutomaticScreenshots/QuickInstall/Step5LastStep.rst.txt + +Using DDEV +---------- + +A step-by-step tutorial is available on how to +:ref:`Install TYPO3 using DDEV `. +The tutorial also includes a video. diff --git a/Documentation/Administration/Installation/LegacyInstallation.rst b/Documentation/Administration/Installation/LegacyInstallation.rst new file mode 100644 index 0000000000..785ca2a83e --- /dev/null +++ b/Documentation/Administration/Installation/LegacyInstallation.rst @@ -0,0 +1,112 @@ +.. include:: /Includes.rst.txt + +.. index:: legacy installation + +.. _legacyinstallation: + +=================== +Legacy Installation +=================== + +.. warning:: + This guide details how TYPO3 can be installed without using Composer. This method of installation + is now considered **out of date**, users are strongly encouraged to use the + :ref:`Composer-based installation instructions `. + +Installing on a Unix Server +=========================== + +#. Download TYPO3's source package from `https://get.typo3.org/ + `_: + + .. code-block:: bash + :caption: /var/www/site/$ + + wget --content-disposition https://get.typo3.org/12 + + Ensure that the package is one level above the web server's document root. + + .. note:: + Make sure to check the :ref:`release_integrity` of the downloaded files. + + +#. Unpack the :file:`typo3_src-12.4.x.tar.gz`: + + .. code-block:: bash + :caption: /var/www/site/$ + + tar xzf typo3_src-12.4.x.tar.gz + + Note that the `x` in the extracted folder will be replaced with the latest bugfix version of TYPO3. + + +#. Create the following symlinks in the document root: + + + .. code-block:: bash + :caption: /var/www/site/$ + + cd public + ln -s ../typo3_src-12.4.x typo3_src + ln -s typo3_src/index.php index.php + ln -s typo3_src/typo3 typo3 + + .. important:: + Make sure to upload the whole TYPO3 source directory including the + :path:`vendor` directory, otherwise you will miss important dependencies. + +#. This will then create the following structure: + +.. directory-tree:: + + * :path:`typo3_src-12.4.x/` + * :path:`public/` + + * :path:`typo3_src -> ../typo3_src-12.4.x/` + * :path:`typo3 -> typo3_src/typo3/` + * :file:`index.php -> typo3_src/index.php` + +Installing on a Windows Server +============================== + +#. Download TYPO3's source package from `https://get.typo3.org/ + `_ and extract the :file:`.zip` file on the web server. + + Ensure that the package is one level above the web server's document root. + + +#. Use the shell to create the following symlinks in the document root: + + .. code-block:: bash + :caption: /var/www/site/$ + + cd public + mklink /d typo3_src ..\typo3_src-12.4.x + mklink /d typo3 typo3_src\typo3 + mklink index.php typo3_src\index.php + +#. This will then create the following structure: + + .. directory-tree:: + + * :path:`typo3_src-12.4.x/` + * :path:`public/` + + * :path:`typo3_src -> ../typo3_src-12.4.x/` + * :path:`typo3 -> typo3_src/typo3/` + * :file:`index.php -> typo3_src/index.php` + + +Completing The Installation +=========================== + +After the source package has been extracted and the symlinks created, continue from the +:ref:`Access TYPO3 via a web browser ` +section of the :ref:`instructions for installing TYPO3 using Composer ` to +complete the installation. + +.. toctree:: + :hidden: + :titlesonly: + + ReleaseIntegrity diff --git a/Documentation/Administration/Installation/Magallanes/Index.rst b/Documentation/Administration/Installation/Magallanes/Index.rst new file mode 100644 index 0000000000..a687e7677c --- /dev/null +++ b/Documentation/Administration/Installation/Magallanes/Index.rst @@ -0,0 +1,15 @@ +.. 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/Administration/Installation/Magallanes/_mage.yml b/Documentation/Administration/Installation/Magallanes/_mage.yml new file mode 100644 index 0000000000..9e95d385b5 --- /dev/null +++ b/Documentation/Administration/Installation/Magallanes/_mage.yml @@ -0,0 +1,38 @@ +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/Administration/Installation/ProductionSettings.rst b/Documentation/Administration/Installation/ProductionSettings.rst new file mode 100644 index 0000000000..b55ef8630b --- /dev/null +++ b/Documentation/Administration/Installation/ProductionSettings.rst @@ -0,0 +1,31 @@ +.. include:: /Includes.rst.txt + +.. index:: Production Settings; Environment + +.. _production-settings: + +=================== +Production Settings +=================== + +To ensure a secure installation of TYPO3 on a production server, the following settings need to be set: + +- :guilabel:`Admin Tools > Settings > Configuration Presets` The "Live" preset has to be chosen to make sure no debug output is displayed. + When using environment specific configurations, the recommended way is to specifically set the values for + error/debugging configuration values instead of presets, like: + + .. code-block:: php + :caption: config/system/additional.php | typo3conf/system/additional.php + + $GLOBALS['TYPO3_CONF_VARS']['SYS']['displayErrors'] = '0'; + $GLOBALS['TYPO3_CONF_VARS']['SYS']['sqlDebug'] = '0'; + $GLOBALS['TYPO3_CONF_VARS']['FE']['debug'] = '0'; + $GLOBALS['TYPO3_CONF_VARS']['BE']['debug'] = '0'; + + These can be set for example through the :ref:`environment-configuration`. +- `HTTPS` should be used on production servers and :php:`$GLOBALS['TYPO3_CONF_VARS']['BE']['lockSSL']` should be set to `true`. +- Enforce HSTS (Strict-Transport-Security header) in the web servers configuration. +- The `TYPO3_CONTEXT` environment variable should be set to a main context of `Production` (can be verified on the top right in the TYPO3 backend :guilabel:`Application Information`). It should be used to select the appropriate `base variant` for the target system in the Site Configuration. +- Configure the :ref:`TYPO3 logging framework ` to log messages of high severity including and above WARNING or ERROR + and continue to rotate log files stored in :file:`var/log`. +- Verify the :ref:`file permissions ` are correct on the live system. diff --git a/Documentation/Administration/Installation/ReleaseIntegrity.rst b/Documentation/Administration/Installation/ReleaseIntegrity.rst new file mode 100644 index 0000000000..52b7ce5081 --- /dev/null +++ b/Documentation/Administration/Installation/ReleaseIntegrity.rst @@ -0,0 +1,262 @@ +.. include:: /Includes.rst.txt + +.. _release_integrity: + +======================= +TYPO3 release integrity +======================= + +TYPO3 release packages (the downloadable tarballs and zip files) as well as +Git tags are signed using :abbr:`PGP (Pretty Good Privacy)` signatures during +the automated release process. SHA2-256, SHA1 and MD5 hashes are also generated +for these files. + +Release contents +================ + +Every release of TYPO3 is made available with the following files: + +.. code-block:: bash + :caption: `TYPO3 CMS 12.4.11 `_ release as an example + + typo3_src-12.4.11.tar.gz + typo3_src-12.4.11.tar.gz.sig + typo3_src-12.4.11.zip + typo3_src-12.4.11.zip.sig + +* :file:`*.tar.gz` and :file:`*.zip` files are the actual release packages, + containing the source code of TYPO3 +* :file:`*.sig` files contain the corresponding signatures for each release + package file + +Checking file hashes +==================== + +File hashes are used to check that a downloaded file was transferred and stored +correctly on the local system. TYPO3 uses cryptographic hash methods including `MD5`_ +and `SHA2-256`_. + +The file hashes for each version are published on get.typo3.org and can be found +on the corresponding release page, for example https://get.typo3.org/version/12#package-checksums contains: + +.. code-block:: text + :caption: TYPO3 v12.4.11 checksums + :name: Checksums + + SHA256: + a93bb3e8ceae5f00c77f985438dd948d2a33426ccfd7c2e0e5706325c43533a3 typo3_src-12.4.11.tar.gz + 8e0a8eaeed082e273289f3e17318817418c38c295833a12e7f94abb2845830ee typo3_src-12.4.11.zip + + SHA1: + 9fcecf7b0e72074b060516c22115d57dd29fd5b0 typo3_src-12.4.11.tar.gz + 3606bcc9331f2875812ddafd89ccc2ddf8922b63 typo3_src-12.4.11.zip + + MD5: + a4fbb1da81411f350081872fe2ff2dac typo3_src-12.4.11.tar.gz + c514ef9b7aad7c476fa4f36703e686fb typo3_src-12.4.11.zip + + +To verify file hashes, the hashes need to be generated locally for the packages +downloaded and then compared to the published hashes on get.typo3.org. +To generate the hashes locally, one of the following command line tools +:bash:`md5sum`, :bash:`sha1sum` or :bash:`shasum` needs to be used. + +The following commands generate hashes for the :file:`.tar.gz` and :file:`.zip` +packages: + +.. code-block:: bash + :caption: ~$ + + shasum -a 256 typo3_src-*.tar.gz typo3_src-*.zip + a93bb3e8ceae5f00c77f985438dd948d2a33426ccfd7c2e0e5706325c43533a3 typo3_src-12.4.11.tar.gz + 8e0a8eaeed082e273289f3e17318817418c38c295833a12e7f94abb2845830ee typo3_src-12.4.11.zip + +.. code-block:: bash + :caption: ~$ + + sha1sum -c typo3_src-*.tar.gz typo3_src-*.zip + 9fcecf7b0e72074b060516c22115d57dd29fd5b0 typo3_src-12.4.11.tar.gz + 3606bcc9331f2875812ddafd89ccc2ddf8922b63 typo3_src-12.4.11.zip + +.. code-block:: bash + :caption: ~$ + + md5sum typo3_src-*.tar.gz typo3_src-*.zip + a4fbb1da81411f350081872fe2ff2dac typo3_src-12.4.11.tar.gz + c514ef9b7aad7c476fa4f36703e686fb typo3_src-12.4.11.zip + +These hashes must match the hashes published on get.typo3.org to ensure package integrity. + +.. _MD5: https://en.wikipedia.org/wiki/MD5 +.. _SHA2-256: https://en.wikipedia.org/wiki/SHA-2 + + +Checking file signatures +======================== + +TYPO3 uses `Pretty Good Privacy`_ to sign release packages and Git release tags. +To validate these signatures `The GNU Privacy Guard`_ is recommend, however +any `OpenPGP`_ compliant tool can also be used. + +The release packages are using a detached binary signature. This means that +the file :file:`typo3_src-12.4.11.tar.gz` has an additional signature file +:file:`typo3_src-12.4.11.tar.gz.sig` which is the detached signature. + +.. code-block:: bash + :caption: ~$ + + gpg --verify typo3_src-12.4.11.tar.gz.sig typo3_src-12.4.11.tar.gz + +.. code-block:: text + + gpg: Signature made 13 Feb 2024 10:56:11 CET + gpg: using RSA key 2B1F3D58AEEFB6A7EE3241A0C19FAFD699012A5A + gpg: Can't check signature: No public key + +The warning means that the public key ``2B1F3D58AEEFB6A7EE3241A0C19FAFD699012A5A`` is not yet available on the +local system and cannot be used to validate the signature. The public key can be +obtained by any key server - a popular one is `pgpkeys.mit.edu`_. + +.. code-block:: bash + :caption: ~$ + + wget -qO- https://get.typo3.org/KEYS | gpg --import + +.. code-block:: text + + gpg: requesting key 59BC94C4 from hkp server pgpkeys.mit.edu + gpg: key 59BC94C4: public key "TYPO3 Release Team (RELEASE) " imported + gpg: key FA9613D1: public key "Benjamin Mack " imported + gpg: key 16490937: public key "Oliver Hader " imported + gpg: no ultimately trusted keys found + gpg: Total number processed: 3 + gpg: imported: 3 (RSA: 3) + +Once the public key has been imported, the previous command on verifying the +signature of the :file:`typo3_src-12.4.11.tar.gz` file can be repeated. + +.. code-block:: bash + :caption: ~$ + + gpg --verify typo3_src-12.4.11.tar.gz.sig typo3_src-12.4.11.tar.gz + +.. code-block:: text + + gpg: Signature made Tue Feb 13 10:56:11 2024 CET + gpg: using RSA key 2B1F3D58AEEFB6A7EE3241A0C19FAFD699012A5A + gpg: Good signature from "Oliver Hader " [unknown] + gpg: aka "Oliver Hader " [unknown] + gpg: WARNING: This key is not certified with a trusted signature! + gpg: There is no indication that the signature belongs to the owner. + Primary key fingerprint: 0C4E 4936 2CFA CA0B BFCE 5D16 A36E 4D1F 1649 0937 + Subkey fingerprint: 2B1F 3D58 AEEF B6A7 EE32 41A0 C19F AFD6 9901 2A5A + +The new warning is expected since everybody could have created the public key +and uploaded it to the key server. The important point here is to validate the key +fingerprint `0C4E 4936 2CFA CA0B BFCE 5D16 A36E 4D1F 1649 0937` which is in +this case the correct one for TYPO3 CMS release packages (see below for a list +of currently used keys or access the https://get.typo3.org/KEYS file directly). + +.. code-block:: bash + :caption: ~$ + + gpg --fingerprint 0C4E49362CFACA0BBFCE5D16A36E4D1F16490937 + +.. code-block:: text + + pub rsa4096 2017-08-10 [SC] [expires: 2024-08-14] + 0C4E 4936 2CFA CA0B BFCE 5D16 A36E 4D1F 1649 0937 + uid [ unknown] Oliver Hader + uid [ unknown] Oliver Hader + sub rsa4096 2017-08-10 [E] [expires: 2024-08-14] + sub rsa4096 2017-08-10 [S] [expires: 2024-08-14] + +.. _Pretty Good Privacy: https://en.wikipedia.org/wiki/Pretty_Good_Privacy +.. _The GNU Privacy Guard: http://www.gnupg.org/ +.. _OpenPGP: http://www.openpgp.org/ +.. _pgpkeys.mit.edu: https://pgpkeys.mit.edu/ + + +Checking tag signature +====================== + +Checking signatures on Git tags works similar to verifying the results using the +:bash:`gpg` tool, but with using the :bash:`git tag --verify` command directly. + +.. code-block:: bash + :caption: ~$ + + git tag --verify v12.4.11 + + +.. code-block:: text + + object 3f83ff31e72053761f33b975410fa2881174e0e5 + type commit + tag v12.4.11 + tagger Oliver Hader 1707818102 +0100 + + Release of TYPO3 12.4.11 + gpg: Signature made Tue Feb 13 10:55:02 2024 CET + gpg: using RSA key 2B1F3D58AEEFB6A7EE3241A0C19FAFD699012A5A + gpg: Good signature from "Oliver Hader " [unknown] + gpg: aka "Oliver Hader " [unknown] + Primary key fingerprint: 0C4E 4936 2CFA CA0B BFCE 5D16 A36E 4D1F 1649 0937 + Subkey fingerprint: 2B1F 3D58 AEEF B6A7 EE32 41A0 C19F AFD6 9901 2A5A + +The :bash:`git show` command on the name of the tag reveals more details. + +.. code-block:: bash + :caption: ~$ + + git show v12.4.11 + +.. code-block:: text + + tag v12.4.11 + Tagger: Oliver Hader + Date: Tue Feb 13 10:55:02 2024 +0100 + + Release of TYPO3 12.4.11 + -----BEGIN PGP SIGNATURE----- + ... + -----END PGP SIGNATURE----- + + + +Public keys +=========== + +.. note:: + Starting in June 2017, TYPO3 releases have been cryptographically signed by the + `TYPO3 Release Team ` with a dedicated public key. + Since July 2017 releases are signed by individual members of the TYPO3 + Release Team directly, namely `Benni Mack ` and + `Oliver Hader `. + +You can download the used public keys from `get.typo3.org.keys`_ + +* TYPO3 Release Team + + * 4096 bit RSA key + * Key ID `0x9B9CB92E59BC94C4`_ + * Fingerprint `7AF5 1AAA DED9 D002 4F89 B06B 9B9C B92E 59BC 94C4` + +* Benni Mack + + * 4096 bit RSA key + * Key ID `0x3304BBDBFA9613D1`_ + * Fingerprint `E7ED 29A7 0309 A0D1 AE34 DA73 3304 BBDB FA96 13D1` + +* Oliver Hader + + * 4096 bit RSA key + * Key ID `0xC19FAFD699012A5A`_, subkey of `0xA36E4D1F16490937`_ + * Fingerprint `0C4E 4936 2CFA CA0B BFCE 5D16 A36E 4D1F 1649 0937` + + +.. _0x9B9CB92E59BC94C4: https://keys.openpgp.org/search?q=9B9CB92E59BC94C4 +.. _0x3304BBDBFA9613D1: https://keys.openpgp.org/search?q=3304BBDBFA9613D1 +.. _0xC19FAFD699012A5A: https://keys.openpgp.org/search?q=C19FAFD699012A5A +.. _0xA36E4D1F16490937: https://keys.openpgp.org/search?q=A36E4D1F16490937 +.. _get.typo3.org.keys: https://get.typo3.org/KEYS diff --git a/Documentation/Administration/Installation/Surf/Index.rst b/Documentation/Administration/Installation/Surf/Index.rst new file mode 100644 index 0000000000..4a1ec5e10d --- /dev/null +++ b/Documentation/Administration/Installation/Surf/Index.rst @@ -0,0 +1,16 @@ +.. include:: /Includes.rst.txt + +.. index:: Deployment; TYPO3 Surf + +.. _deployment-typo3-surf: + +========== +TYPO3 Surf +========== + +:doc:`TYPO3 Surf ` is a deployment tool written in PHP. + + +.. literalinclude:: _MyDeployment.php + :language: php + :caption: MyDeployment.php diff --git a/Documentation/Administration/Installation/Surf/_MyDeployment.php b/Documentation/Administration/Installation/Surf/_MyDeployment.php new file mode 100644 index 0000000000..cfb2468f57 --- /dev/null +++ b/Documentation/Administration/Installation/Surf/_MyDeployment.php @@ -0,0 +1,61 @@ +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, + ); + }, + ); diff --git a/Documentation/Administration/Installation/SystemRequirements/Apache.rst.txt b/Documentation/Administration/Installation/SystemRequirements/Apache.rst.txt new file mode 100644 index 0000000000..269a5d3b92 --- /dev/null +++ b/Documentation/Administration/Installation/SystemRequirements/Apache.rst.txt @@ -0,0 +1,42 @@ +.. include:: /Includes.rst.txt + +.. _system-requirements-apache: + +During the initial installation, TYPO3's default :file:`.htaccess` file is copied to the installation root folder. + +**Virtual Host Record** + +* `AllowOverride `__ needs to include "Indexes" and "FileInfo" in the Virtual Host record. + +**Apache Modules** + +The following Apache modules are required. The list is based on what is used in +the default TYPO3 +`.htaccess `__. +In some cases, it is not a "hard" requirement, but is strongly recommended for +security or performance reasons, but you can also handle the desired outcome +in a different way with a different module. + +mod_alias: + Block access to vcs directories + +mod_authz_core: + Block access to specific files and directories + +mod_deflate: + Used for compression and performance. + +mod_expires: + Adds HTTP headers for browser caching and performance. + +mod_filter: + Used with mod_deflate. + +mod_headers: + Used in combination with `mod_deflate`. + +mod_rewrite: + Enable human readable urls. + +mod_setenvif: + Also used with `mod_deflate`. diff --git a/Documentation/Administration/Installation/SystemRequirements/Database.rst.txt b/Documentation/Administration/Installation/SystemRequirements/Database.rst.txt new file mode 100644 index 0000000000..973e9f58a2 --- /dev/null +++ b/Documentation/Administration/Installation/SystemRequirements/Database.rst.txt @@ -0,0 +1,40 @@ +.. include:: /Includes.rst.txt + + +.. _system-requirements-database: + +Required Database Privileges +---------------------------- + +The database user requires the following privileges on the TYPO3 +database: + +* SELECT, INSERT, UPDATE, DELETE + +* CREATE, DROP, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES + +It is recommended to also grant the following privileges: + +* CREATE VIEW, SHOW VIEW + +* EXECUTE, CREATE ROUTINE, ALTER ROUTINE + +Some database systems like MySQL and MariaDB allow to configure +SQL language support through a :sql`SQL_MODE` setting. + +TYPO3 strives to be compatible to the DEFAULT `SQL_MODE` settings +of the database engine versions supported by a specific TYPO3 release. + +If you change any setting to a NON-default SQL mode, be prepared to +audit all involved code to be compatible to your server mode choice. +Notably the settings `ANSI` and `ANSI_QUOTES` may cause issues. + +`NO_AUTO_VALUE_ON_ZERO`, `NO_ENGINE_SUBSTITUTION`, `NO_AUTO_CREATE_USER`, +`ERROR_FOR_DIVISION_BY_ZERO`, `ONLY_FULL_GROUP_BY`, `NO_ZERO_DATE`, +`NO_ZERO_IN_DATE`, `STRICT_ALL_TABLES` and `STRICT_TRANS_TABLES` should +work with TYPO3 versions 12 and upwards, as the internal tests are +performed with the `SQL_MODE` set to those keys. + +Custom or third-party extensions need to be evaluated individually. + +Listed as being incompatible is: `NO_BACKSLASH_ESCAPES`. diff --git a/Documentation/Administration/Installation/SystemRequirements/IIS.rst.txt b/Documentation/Administration/Installation/SystemRequirements/IIS.rst.txt new file mode 100644 index 0000000000..c58cfd0463 --- /dev/null +++ b/Documentation/Administration/Installation/SystemRequirements/IIS.rst.txt @@ -0,0 +1,12 @@ +.. include:: /Includes.rst.txt + + +.. _system-requirements-iis: + +* During the initial installation of TYPO3, the default IIS web config file is + copied to the installation root folder. + +* Default IIS web config file with rewrite rules can be found in + :file:`EXT:install/Resources/Private/FolderStructureTemplateFiles/root-web-config` + +* The `URL Rewrite plugin `__ is required. diff --git a/Documentation/Administration/Installation/SystemRequirements/Index.rst b/Documentation/Administration/Installation/SystemRequirements/Index.rst new file mode 100644 index 0000000000..46b1986803 --- /dev/null +++ b/Documentation/Administration/Installation/SystemRequirements/Index.rst @@ -0,0 +1,54 @@ +.. include:: /Includes.rst.txt + +.. index:: system requirements, apache, nginx, database, mysql, sqlite + +.. _system-requirements: + +=================== +System Requirements +=================== + +TYPO3 requires a web server running PHP and access to a database. + +Composer is also required for local development. + +If you want TYPO3 to automatically carry out image processing – for example +scaling or cropping – you will need +`GraphicsMagick (version 1.3 or newer) `__ or +`ImageMagick (version 6 or newer) `__ installed on +the server. (GraphicsMagick is preferable.) + +For up-to-date information about TYPO3's system requirements visit `get.typo3.org +`_. + +.. include:: PHP.rst.txt + +Web Server +========== + +.. tabs:: + + .. tab:: Apache + + .. include:: Apache.rst.txt + + .. tab:: NGINX + + .. include:: NGINX.rst.txt + + .. tab:: IIS + + .. include:: IIS.rst.txt + +Database +======== + +.. include:: Database.rst.txt + +Composer +======== + +Composer is only required for **local** installations - see +`https://getcomposer.org `_ for further information. +It is recommended to always use the latest available Composer version. +TYPO3 v12 LTS requires at least Composer version 2.1.0. diff --git a/Documentation/Administration/Installation/SystemRequirements/NGINX.rst.txt b/Documentation/Administration/Installation/SystemRequirements/NGINX.rst.txt new file mode 100644 index 0000000000..a2650b0bbf --- /dev/null +++ b/Documentation/Administration/Installation/SystemRequirements/NGINX.rst.txt @@ -0,0 +1,111 @@ +.. include:: /Includes.rst.txt + + +.. _system-requirements-nginx: + + +NGINX does not support static configuration files that are stored in a projects root like Apache and IIS would. Instead, NGINX requires a configuration file +to be created within the applications own configuration directory. + +Example NGINX configuration file: + +.. code-block:: nginx + :caption: /etc/nginx/conf.d/nginx.conf + + # Compressing resource files will save bandwidth and so improve loading speed especially for users + # with slower internet connections. TYPO3 can compress the .js and .css files for you. + # *) Set $GLOBALS['TYPO3_CONF_VARS']['BE']['compressionLevel'] = 9 for the Backend + # *) Set $GLOBALS['TYPO3_CONF_VARS']['FE']['compressionLevel'] = 9 together with the TypoScript properties + # config.compressJs and config.compressCss for GZIP compression of Frontend JS and CSS files. + location ~ \.js\.gzip$ { + add_header Content-Encoding gzip; + gzip off; + types { text/javascript gzip; } + } + location ~ \.css\.gzip$ { + add_header Content-Encoding gzip; + gzip off; + types { text/css gzip; } + } + + # TYPO3 - Rule for versioned static files, configured through: + # - $GLOBALS['TYPO3_CONF_VARS']['BE']['versionNumberInFilename'] + # - $GLOBALS['TYPO3_CONF_VARS']['FE']['versionNumberInFilename'] + if (!-e $request_filename) { + rewrite ^/(.+)\.(\d+)\.(php|js|css|png|jpg|gif|gzip)$ /$1.$3 last; + } + + # TYPO3 - Block access to composer files + location ~* composer\.(?:json|lock) { + deny all; + } + + # TYPO3 - Block access to flexform files + location ~* flexform[^.]*\.xml { + deny all; + } + + # TYPO3 - Block access to language files + location ~* locallang[^.]*\.(?:xml|xlf)$ { + deny all; + } + + # TYPO3 - Block access to static typoscript files + location ~* ext_conf_template\.txt|ext_typoscript_constants\.txt|ext_typoscript_setup\.txt { + deny all; + } + + # TYPO3 - Block access to miscellaneous protected files + location ~* /.*\.(?:bak|co?nf|cfg|ya?ml|ts|typoscript|tsconfig|dist|fla|in[ci]|log|sh|sql|sqlite)$ { + deny all; + } + + # TYPO3 - Block access to recycler and temporary directories + location ~ _(?:recycler|temp)_/ { + deny all; + } + + # TYPO3 - Block access to configuration files stored in fileadmin + location ~ fileadmin/(?:templates)/.*\.(?:txt|ts|typoscript)$ { + deny all; + } + + # TYPO3 - Block access to libraries, source and temporary compiled data + location ~ ^(?:vendor|typo3_src|typo3temp/var) { + deny all; + } + + # TYPO3 - Block access to protected extension directories + location ~ (?:typo3conf/ext|typo3/sysext|typo3/ext)/[^/]+/(?:Configuration|Resources/Private|Tests?|Documentation|docs?)/ { + deny all; + } + + location / { + try_files $uri $uri/ /index.php$is_args$args; + } + + location = /typo3 { + rewrite ^ /typo3/; + } + + location /typo3/ { + absolute_redirect off; + try_files $uri /typo3/index.php$is_args$args; + } + + location ~ [^/]\.php(/|$) { + fastcgi_split_path_info ^(.+?\.php)(/.*)$; + if (!-f $document_root$fastcgi_script_name) { + return 404; + } + fastcgi_buffer_size 32k; + fastcgi_buffers 8 16k; + fastcgi_connect_timeout 240s; + fastcgi_read_timeout 240s; + fastcgi_send_timeout 240s; + + # this is the PHP-FPM upstream - see also: https://www.nginx.com/resources/wiki/start/topics/examples/phpfcgi/#connecting-nginx-to-php-fpm + fastcgi_pass php-fpm:9000; + fastcgi_index index.php; + include fastcgi.conf; + } diff --git a/Documentation/Administration/Installation/SystemRequirements/PHP.rst.txt b/Documentation/Administration/Installation/SystemRequirements/PHP.rst.txt new file mode 100644 index 0000000000..e90ff09b31 --- /dev/null +++ b/Documentation/Administration/Installation/SystemRequirements/PHP.rst.txt @@ -0,0 +1,86 @@ +.. include:: /Includes.rst.txt + + +.. _system-requirements-php: + +PHP +=== + +.. _system-requirements-php-configuration: + +Configure +--------- + +The following settings need to be set in the installations :file:`php.ini` + +.. code-block:: ini + :caption: php.ini + + ; memory_limit >= 256MB + memory_limit=256M + + ; max_execution_time >= 240 seconds + max_execution_time=240 + + ; max_input_vars >= 1500 + max_input_vars=1500 + + ; PHP JIT compiler must be activated. Needed for proper Fluid parsing + pcre.jit=1 + +The following settings control the maximum upload file size (and should be +adapted if necessary): + +.. code-block:: ini + :caption: php.ini + + ; To allow uploads of a maximum of 10 MB + post_max_size = 10M + upload_max_filesize = 10M + +.. _system-requirements-php-extensions: + +Required Extensions +------------------- + +* **pdo** +* **session** +* **xml** +* **filter** +* **SPL** +* **standard** +* **tokenizer** +* **mbstring** +* **intl** + +Depending on the use case, the following extensions may also be required: + +* **fileinfo** (used to detect file extensions of uploaded files) +* **gd** (GDlib/Freetype is required for building images with text (GIFBUILDER) and is also be used to scale images) +* **zip** (TYPO3 uses zip to extract language archives as well as extracting and archiving extensions) +* **zlib** (TYPO3 uses zlib for output compression) +* **openssl** (OpenSSL is required for sending SMTP mails over an encrypted channel endpoint) + + +.. _system-requirements-php-database-extensions: + +Required Database Extensions +---------------------------- + +.. tabs:: + + .. tab:: MySQL / MariaDB + + * pdo_mysql (recommended) + * OR mysqli + + The InnoDB engine is required for MySQL and MariaDB instances. + + .. tab:: Postgres + + * pdo_pgsql + * postgresql + + .. tab:: SQLite + + * sqlite diff --git a/Documentation/Administration/Installation/TuneTYPO3.rst b/Documentation/Administration/Installation/TuneTYPO3.rst new file mode 100644 index 0000000000..80b93d55ad --- /dev/null +++ b/Documentation/Administration/Installation/TuneTYPO3.rst @@ -0,0 +1,90 @@ +.. include:: /Includes.rst.txt + +.. index:: tuning + +.. _tunetypo3: + +============ +Tuning TYPO3 +============ + +This chapter contains information on how to configure and optimize the infrastructure +running TYPO3. + +OPcache +======= + +It is recommended that OPcache be enabled on the web server running TYPO3. OPcache's +default settings will provide significant performance improvements; however there are +some changes you can make to help further improve stability and performance. In addition +enabling certain features in OPcache can lead to performance degradation. + +Enabling OPcache +---------------- + +.. code-block:: ini + :caption: php.ini + + opcache.enable=1 + opcache.revalidate_freq=30 + opcache.revalidate_path=0 + +Tuning OPcache +-------------- + +Below is list a of OPcache features with information on how they can impact TYPO3's performance. + +.. confval:: opcache.save_comments + + :Default: 1 + :Recommended: 1 + + Setting this to 0 may improve performance but some parts of TYPO3 (including Extbase) + rely on information stored in phpDoc comments to function correctly. + +.. confval:: opcache.use_cwd + + :Default: 1 + :Recommended: 1 + + Setting the value to 0 may cause problems in certain applications because files + that have the same name may get mixed up due to the complete path of the file not + being stored as a key. TYPO3 works with absolute paths so this would + return no improvements to performance. + +.. confval:: opcache.validate_timestamps + + :Default: 1 + :Recommended: 1 + + While setting this to 0 may speed up performance, you **must** make sure to + flush opcache whenever changes are made to the PHP scripts or they will not + be updated in OPcache. This can be achieved by using a proper deployment + pipeline. Additionally, some files can be added to the blacklist, see `opcache.blacklist_filename` for more information. + +.. confval:: opcache.revalidate_freq + + :Default: 2 + :Recommended: 30 + + Setting this to a high value can improve performance but shares the same issue + when setting `validate_timestamps` to 0. + +.. confval:: opcache.revalidate_path + + :Default: 1 + :Recommended: 0 + + Setting this value to 0 should be safe with TYPO3. This may be a problem if + relative path names are used to load scripts and if the same file exists several + times in the include path. + +.. confval:: opcache.max_accelerated_files + + :Default: 10000 + :Recommended: 10000 + + The default setting should be enough for TYPO3, but this depends + on the number of additional scripts that need to be loaded by the system. + +For more information on OPcache visit the `Official PHP documentation `__. diff --git a/Documentation/Images/AutomaticScreenshots/QuickInstall/EnableFirstInstall.png b/Documentation/Images/AutomaticScreenshots/QuickInstall/EnableFirstInstall.png new file mode 100644 index 0000000000..e73de91bc3 Binary files /dev/null and b/Documentation/Images/AutomaticScreenshots/QuickInstall/EnableFirstInstall.png differ diff --git a/Documentation/Images/AutomaticScreenshots/QuickInstall/EnableFirstInstall.rst.txt b/Documentation/Images/AutomaticScreenshots/QuickInstall/EnableFirstInstall.rst.txt new file mode 100644 index 0000000000..c832569ee0 --- /dev/null +++ b/Documentation/Images/AutomaticScreenshots/QuickInstall/EnableFirstInstall.rst.txt @@ -0,0 +1,7 @@ +.. Automatic screenshot: Remove this line if you want to manually change this file + +.. figure:: /Images/AutomaticScreenshots/QuickInstall/EnableFirstInstall.png + :alt: Success message after download + :class: with-shadow + + Success message after download diff --git a/Documentation/Images/AutomaticScreenshots/QuickInstall/Step1SystemEnvironment.png b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step1SystemEnvironment.png new file mode 100644 index 0000000000..71af7e428e Binary files /dev/null and b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step1SystemEnvironment.png differ diff --git a/Documentation/Images/AutomaticScreenshots/QuickInstall/Step1SystemEnvironment.rst.txt b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step1SystemEnvironment.rst.txt new file mode 100644 index 0000000000..4316447787 --- /dev/null +++ b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step1SystemEnvironment.rst.txt @@ -0,0 +1,6 @@ +.. Automatic screenshot: Remove this line if you want to manually change this file + +.. figure:: /Images/AutomaticScreenshots/QuickInstall/Step1SystemEnvironment.png + :class: with-shadow + + Install Tool in 1-2-3 mode, first step. diff --git a/Documentation/Images/AutomaticScreenshots/QuickInstall/Step2DatabaseConnection.png b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step2DatabaseConnection.png new file mode 100644 index 0000000000..96b2608f0a Binary files /dev/null and b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step2DatabaseConnection.png differ diff --git a/Documentation/Images/AutomaticScreenshots/QuickInstall/Step2DatabaseConnection.rst.txt b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step2DatabaseConnection.rst.txt new file mode 100644 index 0000000000..07ab4a0b32 --- /dev/null +++ b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step2DatabaseConnection.rst.txt @@ -0,0 +1,6 @@ +.. Automatic screenshot: Remove this line if you want to manually change this file + +.. figure:: /Images/AutomaticScreenshots/QuickInstall/Step2DatabaseConnection.png + :class: with-shadow + + Install Tool in 1-2-3 mode, second step. diff --git a/Documentation/Images/AutomaticScreenshots/QuickInstall/Step3ChooseDb.png b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step3ChooseDb.png new file mode 100644 index 0000000000..ea02628733 Binary files /dev/null and b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step3ChooseDb.png differ diff --git a/Documentation/Images/AutomaticScreenshots/QuickInstall/Step3ChooseDb.rst.txt b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step3ChooseDb.rst.txt new file mode 100644 index 0000000000..a38979dfeb --- /dev/null +++ b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step3ChooseDb.rst.txt @@ -0,0 +1,6 @@ +.. Automatic screenshot: Remove this line if you want to manually change this file + +.. figure:: /Images/AutomaticScreenshots/QuickInstall/Step3ChooseDb.png + :class: with-shadow + + Install Tool in 1-2-3 mode, third step. diff --git a/Documentation/Images/AutomaticScreenshots/QuickInstall/Step4AdminUserSitename.png b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step4AdminUserSitename.png new file mode 100644 index 0000000000..59b1703fdb Binary files /dev/null and b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step4AdminUserSitename.png differ diff --git a/Documentation/Images/AutomaticScreenshots/QuickInstall/Step4AdminUserSitename.rst.txt b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step4AdminUserSitename.rst.txt new file mode 100644 index 0000000000..27bdae62a3 --- /dev/null +++ b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step4AdminUserSitename.rst.txt @@ -0,0 +1,6 @@ +.. Automatic screenshot: Remove this line if you want to manually change this file + +.. figure:: /Images/AutomaticScreenshots/QuickInstall/Step4AdminUserSitename.png + :class: with-shadow + + Install Tool in 1-2-3 mode, forth step. diff --git a/Documentation/Images/AutomaticScreenshots/QuickInstall/Step5LastStep.png b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step5LastStep.png new file mode 100644 index 0000000000..7eb44c8d10 Binary files /dev/null and b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step5LastStep.png differ diff --git a/Documentation/Images/AutomaticScreenshots/QuickInstall/Step5LastStep.rst.txt b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step5LastStep.rst.txt new file mode 100644 index 0000000000..0caaf4d978 --- /dev/null +++ b/Documentation/Images/AutomaticScreenshots/QuickInstall/Step5LastStep.rst.txt @@ -0,0 +1,6 @@ +.. Automatic screenshot: Remove this line if you want to manually change this file + +.. figure:: /Images/AutomaticScreenshots/QuickInstall/Step5LastStep.png + :class: with-shadow + + Install Tool in 1-2-3 mode, fifth step. diff --git a/Documentation/Introduction/Index.rst b/Documentation/Introduction/Index.rst index 1a004e51b1..1e6655a0c1 100644 --- a/Documentation/Introduction/Index.rst +++ b/Documentation/Introduction/Index.rst @@ -62,7 +62,7 @@ The frontend doesn't have to be a website, it could be a native mobile application, a web application built in a frontend framework, or an API to interface with other systems. -.. _installation: +.. _introduction-installation: A basic installation ==================== diff --git a/Documentation/guides.xml b/Documentation/guides.xml index 8f8042b8df..3896654051 100644 --- a/Documentation/guides.xml +++ b/Documentation/guides.xml @@ -21,6 +21,7 @@ /> +