[TASK] Update INSTALL.md and README.md 88/58388/10
authorJosef Glatz <josefglatz@gmail.com>
Tue, 25 Sep 2018 11:55:17 +0000 (13:55 +0200)
committerSusanne Moog <susanne.moog@typo3.org>
Mon, 1 Oct 2018 18:41:36 +0000 (20:41 +0200)
The main goal of this patch is to update the neglected
INSTALL.md and README.md to represent the current
state of the requirements and to improve the overall
content of the two "entry" documentation files.

The install.md has been massively shortened and links to
the official guides were added to finally be able to have
one source of truth.

Resolves: #86487
Releases: master
Change-Id: Id61abf86a4113d25c940c63f1423fa341aa7e702
Reviewed-on: https://review.typo3.org/58388
Reviewed-by: Benni Mack <benni@typo3.org>
Tested-by: Benni Mack <benni@typo3.org>
Tested-by: TYPO3com <no-reply@typo3.com>
Reviewed-by: Susanne Moog <susanne.moog@typo3.org>
Tested-by: Susanne Moog <susanne.moog@typo3.org>
INSTALL.md
README.md

index 4b5ac9f..297c58c 100644 (file)
@@ -2,328 +2,41 @@ INSTALLING TYPO3
 ================
 
 TYPO3 is an open source PHP based web content management system released
-under the GNU GPL. TYPO3 is copyright (c) 1999-2018 by Kasper Skaarhoj.
+under the GNU GPL. TYPO3 is copyright © 1999-2018 by Kasper Skaarhoj.
 
-This document describes:
+Official Installation and Upgrade Guide
+---------------------------------------
 
-* System requirements for TYPO3
-* Installation routine
-* Upgrade routine
+You can find instructions regarding installation and upgrade at
+https://docs.typo3.org/typo3cms/InstallationGuide/
 
-Client browser support
-----------------------
-
-The TYPO3 backend is accessed through a web browser. TYPO3 v9
-supports the following web browsers:
-
-* Internet Explorer 11 and later
-* Microsoft Edge
-* Google Chrome (Windows, MacOS X, Linux)
-* Firefox (Windows, MacOS X, Linux)
-* Safari on MacOS X
-* and other compatible modern browsers
 
 Server system requirements
 --------------------------
 
-TYPO3 requires a web server with a PHP environment and a database. The minimum
-system requirements for running TYPO3 v9 are:
-
-* Webserver capable of running PHP applications (Apache, Nginx, IIS or other)
-* PHP 7.2
-* MySQL 5.5 up to 5.7 or compatible
-* more than 200 MB of disk space
-
-Note: If you use any other webserver than Apache, make sure you add the necessary configuration normally
-provided in the various `.htaccess` files inside the TYPO3 core. This configuration is security relevant,
-therefore only experienced server administrators should create such configuration.
-
-### MySQL environment
-
-TYPO3 works with MySQL in the above mentioned versions. It will also work on
-compatible "drop-in" replacements like MariaDB or Percona. The InnoDB engine
-is required to be enabled.
-
-### MySQL required privileges
-
-The MySQL user needs a least 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
-
-### PHP environment
-
-* memory_limit set to at least 64M
-* max_execution_time set to at least 30 (240 seconds recommended)
-* AllowOverride in the Apache configuration includes "Indexes" and "FileInfo"
-  (see FAQ below)
-
-### PHP required extensions
-
-Your PHP needs to support the following extensions. Install will
-check if these are available.
-
-* These are usually part of the standard PHP package on most distributions:
-  * filter
-  * hash
-  * openssl
-  * pcre >= 8.38
-  * session
-  * SPL
-  * standard
-  * xml
-  * zip
-  * zlib
-
-* These might have to be installed separately:
-  * gd
-  * intl
-  * json
-  * mysqli
-
-### Recommended setup
-
-There are plenty of possible setups for high performance TYPO3 installations
-(i.e. using Varnish Cache, Nginx, PHP-FPM, etc). Consider this resource for
-more ideas or suggestions:  http://wiki.typo3.org/Performance_tuning
-
-This is a basic recommended setup for best performance and increased
-functionality:
-
-* Apache with mod_expires and mod_rewrite enabled
-
-* MySQL 5.5 or newer
-
-* GraphicsMagick or ImageMagick v6 or newer installed on the server
-
-* PHP
-  * version 7.2 or later
-  * memory_limit set to at least 128M
-  * max_execution_time set to at least 240
-  * max_input_vars set to at least 1500
-
-* Additional PHP extensions:
-  * PHP opcode cache, i.e.: apc, xcache, eaccelerator, Zend Optimizer, wincache (in case of an IIS installation)
-  * apcu caching (with at least 100 MB of memory available)
-  * curl
-  * mbstring
-  * FreeType 2 (usually included within the PHP distribution)
-  * fileinfo (mandatory for proper file type detection)
-  * pdo_sqlite (required if SQLite should be used as the DBMS)
-
-* PHP access to /dev/urandom or /dev/random on Unix-like platforms for
-  increased security. Make sure to add "/dev/random:/dev/urandom" to
-  open_basedir settings if you use it. If these paths are unavailable, TYPO3
-  will attempt to simulate random number generation. This is less secure,
-  reduces performance and throws out warnings in the TYPO3 system log.
-
-* TYPO3 works with PHP's IPv6 support, which is enabled by default.
-  If you compile PHP on your own, be aware not to use option "--disable-ipv6",
-  because this will break the IPv6 support and the according unit tests.
-
-Installation
-------------
-
-### Important note for upgrades from TYPO3 CMS versions **below 7 LTS**
-
-It is not possible to upgrade any version below 7 LTS to 8 directly,
-since some upgrade wizards are not available anymore on 8 and 9.
-
-It is highly recommended to upgrade to 7 LTS first and continue with
-a second upgrade to 8 and then upgrade to 9.
-
-### If SSH and symlinks are possible
-
-If you have SSH access to your webserver and are able to create symlinks,
-this is the recommended way of setting up TYPO3 so that it can easily
-be upgraded later through the Install Tool:
-
-* Uncompress the `typo3_src-9.x.x.tar.gz` file one level above the Document
-  Root of your Web server:
-```
-/var/www/site/htdocs/ $ cd ..
-/var/www/site/ $ tar xzf typo3_src-9.x.x.tar.gz
-```
-
-* Important: If you use GIT to fetch the sources, don't forget to run the following commands,
-otherwise your installation won't work!
-```
-cd typo3_src
-composer install --no-dev
-cd ..
-```
-
-* Create the symlinks in your Document Root:
-```
-  cd htdocs
-  ln -s ../typo3_src-9.x.x typo3_src
-  ln -s typo3_src/index.php
-  ln -s typo3_src/typo3
-```
-
-* In case you use Apache, copy the .htaccess to your Document Root:
-```
-  cp typo3_src/_.htaccess .htaccess
-```
-
-* In case you use IIS, install the URL Rewrite 2.x module and copy the web.config to your Document Root:
-```
-  cp typo3_src/_web.config web.config
-```
-
-You end up with the follow structure of files:
-
-```
-  typo3_src-9.x.x/
-  htdocs/typo3_src -> ../typo3_src-9.x.x/
-  htdocs/typo3 -> typo3_src/typo3/
-  htdocs/index.php -> typo3_src/index.php
-  htdocs/.htaccess (only on Apache)
-  htdocs/web.config (only on IIS)
-```
-
-This allows you to upgrade TYPO3 later by simply replacing the symlink
-with a newer version, or by using the integrated "Core Updater" which can
-be found in the Install Tool.
-
-### Windows specifics
-
-#### Symlinks
-
-On Windows Vista and newer you can create symbolic links using the `mklink` tool:
-```
-  mklink /D C:\<dir>\example.com\typo3_src C:\<dir>\typo3_src-9.x.x
-  mklink C:\<dir>\example.com\index.php C:\<dir>\typo3_src-9.x.x\index.php
-```
-Be aware that administrator rights might be needed in order to create the symlinks.
-
-Windows users might need to copy `index.php` from the source directory to the
-web site root directory in case the Windows version does not support links
-for files.
-
-TYPO3 Core upgrades through the Install Tool is not supported under
-Windows.
-
-#### Path length
-
-Up until PHP 7.0 Windows has had problems with lengths of a path.
-The TYPO3 core enforces a maximum path length of 160 characters in itself, leaving
-100 characters for your installation directory. Please note that these 100 characters
-are counted including the drive identifier (C:\ for example).
-
-In case you use composer to install your TYPO3 instance, be aware that composer will
-try to unpack TYPO3 into composer's cache dir first and then move the files to your
-target directory.
-Because composer's cache dir defaults to C:\Users\<user>\AppData\Local\Composer it is
-possible your full path becomes more than the 100 characters you're allowed to use.
-
-You can use the `cache-dir` directive to set a shorter directory specifically for
-your TYPO3 instance.
-
-See: https://getcomposer.org/doc/06-config.md#cache-dir
-
-### No SSH and symlinks possible (not recommended)
-
-In case you only have FTP or SFTP access to your hosting environment, you
-can still install TYPO3, but you won't easily be able to upgrade your
-installation once a new patch-level release is out.
-
-Please note that this is not a recommended setup!
-
-* Uncompress `typo3_src-9.x.x.zip` locally
-* Upload all files and subdirectories directly in your Document Root
-  (where files that are served by your webserver are located).
-* In case your provider uses Apache, rename the file `_.htaccess` to `.htaccess`.
-* In case your provider uses IIS, rename the file `_web.config` to `web.config`.
-
-You end up with this files in your Document Root:
-
-```
- .htaccess (only on Apache)
- web.config (only on IIS)
- CONTRIBUTING.md
- index.php
- INSTALL.md
- LICENSE.txt
- README.md
- typo3/
-```
-
-Installation: further steps
----------------------------
-
-Now access the web server using a web browser. You will be redirected to the
-Install Tool which will walk you through the steps for setting up TYPO3 for
-the first time.
-
-It will check if your environment conforms to the minimum system requirements
-and gives you some suggestions on what to change in case there are any
-discrepancies.
-
-The Install Tool will create the required directory structure for you
-(typo3conf, fileadmin, typo3temp).
+Find the official system requirements at [get.typo3.org](https://get.typo3.org/version/9#system-requirements).
 
 TYPO3 Security
 --------------
 
-To ensure a secure installation, you have to make sure that you keep your
-TYPO3 core and the extensions up to date.
+To ensure a secure installation, you have to make sure that you keep
+your TYPO3 core and the extensions up to date.
 
-* Subscribe to the announcement mailing list. This will inform you about new
-  releases of the TYPO3 core and security bulletins of core and community
-  extensions.
+* Subscribe to the announcement mailing list. This will inform you about
+  new releases of the TYPO3 core and security bulletins of core and
+  community extensions.
   http://lists.typo3.org/cgi-bin/mailman/listinfo/typo3-announce
 
-* Use the scheduler task "Update Extension List (em)" to update the list of
-  available extensions regularly. You should check regularly, if new versions
-  of these extensions are available and apply these updates.
-
 * Please refer to official TYPO3 Security Guide for further information
-  about security-related topics of TYPO3 CMS and the resources compiled by
-  the Security Team.
-  https://docs.typo3.org/typo3cms/SecurityGuide/
+  about security-related topics of TYPO3 CMS and the resources compiled
+  by the Security Team. https://docs.typo3.org/typo3cms/SecurityGuide/
   https://typo3.org/teams/security/resources/
 
-Installation FAQ
-----------------
-
-### 1
-Q:  Why do I get "500 Server error" when I navigate to my TYPO3 web site
-    immediately after installation?
-
-A:  If you are using Apache web server, check the Apache error log for specifics
-    on the error. The cause might be some missing module, or some syntax error
-    in your .htaccess file. The error log is usually located in /var/log/apache2
-    or /var/log/httpd. Check with your hosting provider if you are in doubt
-    where the logs are located.
-
-### 2
-Q:  I went through the setup process and created an admin user. Why can't I log
-    in now?
-
-A:  If you use MySQL 5.x or newer, try setting it to "compatible" mode. Open the
-    TYPO3 Install Tool under http://example.com/typo3/install/ (where
-    example.com is the web site domain), navigate to "All configuration".
-    Find "setDBinit", and add this line to the top of the input field:
-```
-       SET SESSION sql_mode=''
-```
+* Please consider also hardening your TYPO3 instance further by
+  adjusting permissions on non-changing files/folders.
 
-### 3
-Q:  Some modules or extensions make Apache crash on Windows. What is the cause?
+TYPO3 Contribution Guide
+------------------------
 
-A:  Fluid uses complex regular expressions which require a lot of stack space
-    during the first processing. On Windows the default stack size for Apache
-    is a lot smaller than on unix. You can increase the size to 8MB (default on
-    unix) by adding to the httpd.conf:
-```
-       <IfModule mpm_winnt_module>
-               ThreadStackSize 8388608
-       </IfModule>
-```
-    Restart Apache after this change.
+You can find further information in the
+[README.md](README.md#contributing).
index 99b586e..b781597 100644 (file)
--- a/README.md
+++ b/README.md
@@ -11,22 +11,23 @@ This document provides a basic introduction to TYPO3.
 Getting Started
 ---------------
 
-TYPO3 requires a webserver with PHP and a database (MySQL recommended).
+TYPO3 requires a web server with PHP and a database (e.g. MySQL).
 Accessing the backend through a supported browser.
 
-Please see the INSTALL.md in this folder in order to set up a basic TYPO3
-installation on your webserver.
+Please see the [Installation Guide](https://docs.typo3.org/typo3cms/InstallationGuide/) 
+in order to set up a basic TYPO3 installation on your web server.
 
 What is TYPO3?
 --------------
 
-TYPO3 is a free and open source Content Management Framework. It is released
-under the GNU General Public License. It can run on several web servers, such
-as Apache or IIS, on top of many operating systems, among them Linux, Microsoft
-Windows, FreeBSD or MacOS X.
+TYPO3 is a free and open source Content Management Framework. It is
+released under the GNU General Public License. It can run on several web
+servers, such as Apache, nginx or IIS, on top of many operating systems,
+among them Linux, Microsoft Windows, FreeBSD or MacOS.
 
-TYPO3 was initially authored by Kasper Skårhøj and is now further developed
-by a community of Active Contributors around a small TYPO3 CMS Team.
+TYPO3 was initially authored by Kasper Skårhøj and is now further
+developed by a community of contributors and the [TYPO3 Core Development
+Team](https://typo3.org/community/teams/typo3-development/).
 
 To get more info about the GPL license, visit
 http://www.opensource.org/licenses/gpl-license.php
@@ -34,51 +35,54 @@ http://www.opensource.org/licenses/gpl-license.php
 What is a Content Management Framework?
 ---------------------------------------
 
-A Content Management Framework is more than just a content management system,
-due to the separation of the streamlined core and optional plugins
-(extensions). TYPO3 has an open API that allows you to extend the frontend (web
-site) and/or backend (administration) functionalities.
+A Content Management Framework is more than just a content management
+system, due to the separation of the streamlined core and optional
+plugins (extensions). TYPO3 has an open API that allows you to extend
+the frontend (web site) and/or backend (administration) functionality.
 
-The concept of extensions makes TYPO3 capable of being developed and used
-in almost any way you can imagine, either by using any of the many extensions
-which are available for download, or by writing your own.
+The concept of extensions makes TYPO3 capable of being developed and
+used in almost any way you can imagine, either by using any of the many
+extensions which are available for download, or by writing your own.
 
 TYPO3 System requirements
------------------------------
+-------------------------
 
-TYPO3 is based upon PHP and uses a MySQL database. For more information
-regarding these requirements see the [INSTALL.md](INSTALL.md) file in this folder.
+TYPO3 is based upon PHP and uses a database management system like
+MySQL.
 
-Using the Database Abstraction Layer (DBAL) allows one to use TYPO3 with other
-Database Management Systems, like PostgreSQL, Oracle and MSSQL.
+For more specific information regarding requirements see the
+[INSTALL.md](INSTALL.md#server-system-requirements) file in this folder.
 
 TYPO3 resources
 ---------------
 
-Here is an overview of the most important TYPO3 resources to help you get
-started:
+Here is an overview of the most important TYPO3 resources to help you
+get started:
 
 ### Get more information
 
-* https://typo3.org is the main project website. It provides up to
-  date official news, information about events, access to downloading the
+* https://typo3.org is the main project website. It provides up to date
+  official news, information about events, access to downloading the
   products and extensions.
 
-* https://wiki.typo3.org is a collaborative wiki, providing access to
-  all kind of information around the TYPO3 ecosphere.
-
 * https://docs.typo3.org/: TYPO3 is one of the most thoroughly
   documented OpenSource products around, with manuals covering basic
-  tutorials, TypoScript, administration, development, core structure, etc.
-  You should make the time to locate the various documents, and read those
-  that apply to the work you want to do.
+  tutorials, TypoScript, administration, development, core structure,
+  etc. You should make the time to locate the various documents, and
+  read those that apply to the work you want to do.
+
+* https://get.typo3.org/ is the platform where you can download TYPO3
+  and find all release notes and change logs of TYPO3 releases.
+
+* https://extensions.typo3.org/ is the platform where you can search for
+  and download TYPO3 extensions.
 
 ### Chat with us
 
-The TYPO3 team is using a tool called Slack to openly communicate with each
-other and with the public. Several teams use Slack as a way to communicate
-internally and most channels are a welcome place for you to join and get
-yourself involved.
+The TYPO3 community is using a tool called Slack to openly communicate
+with each other and with the public. Several TYPO3 teams use Slack as a
+way to communicate internally and most channels are a welcome place for
+you to join and get yourself involved.
 
 * Register: https://forger.typo3.org/slack/
 * Slack: https://typo3.slack.com/
@@ -86,73 +90,74 @@ yourself involved.
 ### Exchange information, ask questions, get help
 
 Slack is nice for short discussions, but when asking questions, most
-answers are lost in the noise after a few minutes. To let everyone
-profit from an answer, we recommend to ask questions on StackOverflow.
-If you like, you can then post a link into the corresponding Slack
-channel to raise attention. And please, do not forget to tag your
-questions correctly with `TYPO3` (and possibly other tags like `Fluid`
-or `Extbase`).
+answers are lost in the noise after a few minutes.
+
+#### StackOverflow
+
+**To let everyone profit from an answer, we recommend to ask questions
+on StackOverflow**. If you like, you can then post a link into the
+corresponding Slack channel to raise attention. And please, do not
+forget to tag your questions correctly with `typo3` (and possibly other
+tags like `typo3-9.5.x`, `Fluid` or `Extbase`).
 
 * [StackOverflow questions tagged "TYPO3"](https://stackoverflow.com/questions/tagged/typo3)
 
-The community and all TYPO3 teams communicate through newsgroups, which can
-also be accessed through mailing lists and forums. Any of these three ways
-provide access to the same communication channels:
+#### Official meet the TYPO3 Community overview:
 
-* Forum (Web): https://forum.typo3.org/
-* Mailing Lists (Mail): https://typo3.org/support/mailing-lists/
-* Newsgroups (NNTP): news://lists.typo3.org/
+Visit https://typo3.org/community/meet/
 
 Contributing
 ------------
 
-If you want to contribute to the TYPO3 CMS source code, take a look at our
+If you want to contribute to the TYPO3 source code, take a look at our
 Contributors Walkthrough and Review System:
 
 * https://docs.typo3.org/typo3cms/ContributionWorkflowGuide/
 * https://review.typo3.org/
 
+> Please use the [TYPO3 Slack chat](#chat-with-us), if you need help in
+> setting up your contribution environment. The community is very
+> helpful and get you up and running! (Please post your questions in
+> Slack Channel `#typo3-cms-coredev` regarding contribution support)
+
 The [repository at GitHub](https://github.com/TYPO3/TYPO3.CMS) is a
-synchronized mirror of the primary TYPO3 CMS core git repository:
+synchronized mirror of the primary TYPO3 core git repository:
 
 * https://git.typo3.org/Packages/TYPO3.CMS.git
 
-If you want to file a bug report, maintain your own extension using our
-infrastructure (Git, Issue Tracker, Wiki, etc), take a look at:
+If you want to file a bug report, take a look at:
 
-* https://forge.typo3.org
+* [https://forge.typo3.org](https://forge.typo3.org/projects/typo3cms-core/issues)
 
 Final notes
 -----------
 
 TYPO3 is said to be one of the most sophisticated PHP / Internet related
-applications available, and the more you play with it, the more you will agree.
-
-Due to the advanced level of the code and functionality, a degree of study,
-time and perseverance is required to fully understand it, and get the best from
-it. You should keep trying, as we say it's definitely worth it. TYPO3 is the
-Enterprise Content Management System "for all".
-
-The GPL license allows for developments that are based upon TYPO3 to also be
-freely available under the GPL. Please remember this, because TYPO3 is about
-"Inspiring People To Share". If you are making money with TYPO3 you can donate
-or become a member of the TYPO3 Association.
-
-By becoming a supporting member, individuals and organisations mainly fund
-core development of TYPO3. The decision about what the funds are used for, is
-made by all members of the Association and the Expert Advisory Board (EAB).
-The decisions will be made transparent to the community and especially the
-supporting members. Your funds will also serve for other purposes as laid
-out in the bylaws.
+applications available, and the more you play with it, the more you will
+agree.
+
+Due to the advanced level of the code and functionality, a degree of
+study, time and perseverance is required to fully understand it, and get
+the best from it. You should keep trying, as we say it's definitely
+worth it. TYPO3 is the Enterprise Content Management System "for all".
+
+The GPL license allows for developments that are based upon TYPO3 to
+also be freely available under the GPL. Please remember this, because
+TYPO3 is about "Inspiring People To Share". If you are making money with
+TYPO3 you can donate or become a member of the TYPO3 Association.
+
+By becoming a supporting member, individuals and organisations mainly
+fund core development of TYPO3. The decision about what the funds are
+used for, is made by all members of the Association and the Expert
+Advisory Board (EAB). The decisions will be made transparent to the
+community and especially the supporting members. Your funds will also
+serve for other purposes as laid out in the bylaws.
 
 * Donate: https://typo3.org/donate
 * Become a member of the TYPO3 Association:
-  https://typo3.org/association/membership/levels/
+  https://typo3.org/project/association/
 
 Copyleft
 --------
 
 This document is a part of the TYPO3 project.
-
-Written by Nigel Jackson, Ingmar Schlecht, Ernesto Baschny, Michael Stucki,
-Oliver Hader, Ben van 't Ende and others.