Same filename in this branch
  1. 10 INSTALL.txt
  2. 10 core/INSTALL.txt
Same filename and directory in other branches
  1. 8.9.x core/INSTALL.txt
  2. 9 core/INSTALL.txt
CONTENTS OF THIS FILE
---------------------

 * Quickstart
 * Requirements and notes
 * Optional server requirements
 * Installation
 * Reinstall
 * Building and customizing your site
 * Multisite configuration
 * Multilingual configuration

QUICKSTART
----------------------

Prerequisites:
- PHP 8.1.0 (or greater) (https://php.net).

In the instructions below, replace the version x.y.z with the specific version
you wish to download. Example: 8.6.0.zip. You can find the latest stable version
at https://www.drupal.org/project/drupal.

Download and extract the Drupal package:
- curl -sS https://ftp.drupal.org/files/projects/drupal-x.y.z.zip --output drupal-x.y.z.zip
- unzip drupal-x.y.z.zip
- cd /path/to/drupal-x.y.z
- php core/scripts/drupal quick-start

Wait… installation can take a minute or two. A successful installation will
result in opening the new site in your browser.

Run the following command for a list of available options that you may need to
configure quick-start:
- php core/scripts/drupal quick-start --help

Follow the instructions in the REINSTALL section below to start over.

NOTE: This quick start solution uses PHP's built-in web server and is not
intended for production use. Read more about how to run Drupal in a production
environment below.

REQUIREMENTS AND NOTES
----------------------

Drupal requires:

- A web server with PHP support, for example:
  - Apache 2.4.7 (or greater) (http://httpd.apache.org/).
  - Nginx 1.1 (or greater) (http://nginx.com/).
- PHP 8.1.0 (or greater) (http://php.net/).
- One of the following databases:
  - MySQL 5.7.8 (or greater) (http://www.mysql.com/).
  - MariaDB 10.3.7 (or greater) (https://mariadb.org/). MariaDB is a fully
    compatible drop-in replacement for MySQL.
  - Percona Server 5.7.8 (or greater) (http://www.percona.com/). Percona
    Server is a backwards-compatible replacement for MySQL.
  - PostgreSQL 10 (or greater) (http://www.postgresql.org/).
  - SQLite 3.26 (or greater) (http://www.sqlite.org/).

For more detailed information about Drupal requirements, including a list of
PHP extensions and configurations that are required, see "System requirements"
(https://www.drupal.org/docs/system-requirements) in the Drupal.org online
documentation.

For detailed information on how to configure a test server environment using a
variety of operating systems and web servers, see "Local server setup"
(https://www.drupal.org/node/157602) in the Drupal.org online documentation.

Note that all directories mentioned in this document are always relative to the
directory of your Drupal installation, and commands are meant to be run from
this directory (except for the initial commands that create that directory).

OPTIONAL SERVER REQUIREMENTS
----------------------------

- If you want to use Drupal's "Clean URLs" feature on an Apache web server, you
  will need the mod_rewrite module and the ability to use local .htaccess
  files. For Clean URLs support on IIS, see "Clean URLs with IIS"
  (https://www.drupal.org/node/3854) in the Drupal.org online documentation.

- If you plan to use XML-based services such as RSS aggregation, you will need
  PHP's XML extension. This extension is enabled by default on most PHP
  installations.

- To serve gzip compressed CSS and JS files on an Apache web server, you will
  need the mod_headers module and the ability to use local .htaccess files.

- Some Drupal functionality (e.g., checking whether Drupal and contributed
  modules need updates, RSS aggregation, etc.) require that the web server be
  able to go out to the web and download information. If you want to use this
  functionality, you need to verify that your hosting provider or server
  configuration allows the web server to initiate outbound connections. Most web
  hosting setups allow this.

INSTALLATION
------------

1. Download and extract Drupal.

   You can obtain the latest Drupal release from https://www.drupal.org -- the
   files are available in .tar.gz and .zip formats and can be extracted using
   most compression tools.

   To download and extract the files, on a typical Unix/Linux command line, use
   the following commands (assuming you want version x.y.z of Drupal in .tar.gz
   format):

     wget https://www.drupal.org/files/projects/drupal-x.y.z.tar.gz
     tar -zxvf drupal-x.y.z.tar.gz

   This will create a new directory drupal-x.y.z/ containing all Drupal files
   and directories. Then, to move the contents of that directory into a
   directory within your web server's document root or your public HTML
   directory, continue with this command:

     mv drupal-x.y.z/* drupal-x.y.z/.htaccess drupal-x.y.z/.csslintrc drupal-x.y.z/.editorconfig drupal-x.y.z/.eslintignore drupal-x.y.z/.eslintrc.json drupal-x.y.z/.gitattributes /path/to/your/installation

   You can also download the latest version of Drupal using Git on the command
   line and set up a repository by following the instructions at
   https://www.drupal.org/project/drupal/git-instructions for "Setting up
   repository for the first time".

   Once you have downloaded Drupal successfully, you may install Composer
   globally using the instructions at
   https://getcomposer.org/doc/00-intro.md#globally

   With Composer installed, run the following command from the Drupal web root:

     composer install

2. Create the Drupal database.

   Because Drupal stores all site information in a database, the Drupal
   installer will attempt to create this database for you. If you create the
   database manually, you must grant Drupal certain database privileges (such as
   the ability to create tables).  For details, consult INSTALL.mysql.txt,
   INSTALL.pgsql.txt, or INSTALL.sqlite.txt. You may also need to consult your
   web hosting provider for instructions specific to your web host.

   Take note of the username, password, database name, and hostname as you
   create the database. You will enter this information during the install.

3. Run the install script.

   To run the install script, point your browser to the base URL of your
   website (e.g., http://www.example.com).

   You will be guided through several screens to set up the database, add the
   site maintenance account (the first user, also known as user/1), and provide
   basic website settings.

   During installation, several files and directories need to be created, which
   the install script will try to do automatically. However, on some hosting
   environments, manual steps are required, and the install script will tell
   you that it cannot proceed until you fix certain issues. This is normal and
   does not indicate a problem with your server.

   The most common steps you may need to perform are:

   a. Missing files directory.

      The install script will attempt to create a public file storage directory
      in the default location at sites/default/files (the location of the files
      directory may be changed after Drupal is installed).

      If auto-creation fails, you can create the directory yourself. (If you are
      creating a multisite installation, substitute the correct sites directory
      for sites/default; see the Multisite Configuration section of this file,
      below.) Sample commands from a Unix/Linux command line:

        mkdir sites/default/files
        chmod a+w sites/default/files

      Alternatively, you can make the install script work by changing
      permissions on the sites/default directory. The web server can then
      create the files directory within it for you.

      For example, on a Unix/Linux command line, you can grant everyone
      (including the web server) permission to write to the sites/default
      directory with this command:

        chmod a+w sites/default

      Then re-run install.php (e.g. by clicking "try again" at the bottom of
      the Requirements problem page. Once the files directory is created, you
      will need to grant everyone (including the web server) permission to
      write to it with this command:

        chmod a+w sites/default/files

      Be sure to set the permissions for the default directory back after the
      installation is finished! (Leave the files directory writable.)
      Sample command:

        chmod go-w sites/default

   b. Missing settings file.

      Drupal will try to automatically create a settings.php configuration file,
      which is normally in the directory sites/default (to avoid problems when
      upgrading, Drupal is not packaged with this file). If auto-creation fails,
      you will need to create this file yourself, using the file
      sites/default/default.settings.php as a template.

      For example, on a Unix/Linux command line, you can make a copy of the
      default.settings.php file with the command:

        cp sites/default/default.settings.php sites/default/settings.php

      Next, grant write privileges to the file to everyone (including the web
      server) with the command:

        chmod a+w sites/default/settings.php

      Be sure to set the permissions back after the installation is finished!
      Sample command:

        chmod go-w sites/default/settings.php

   c. Write permissions after install.

      The install script will attempt to write-protect the settings.php file and
      the sites/default directory after saving your configuration. If this
      fails, you will be notified, and you can do it manually. Sample commands
      from a Unix/Linux command line:

        chmod go-w sites/default/settings.php
        chmod go-w sites/default

4. Verify that the site is working.

   When the install script finishes, you will be logged in with the site
   maintenance account on a "Welcome" page. If the default Drupal theme is not
   displaying properly and links on the page result in "Page Not Found" errors,
   you may be experiencing problems with clean URLs. Visit
   https://www.drupal.org/docs/8/clean-urls-in-drupal-8 to troubleshoot.

5. Change file system storage settings (optional).

   The files directory created in step 3 is the default file system path used to
   store all uploaded files, as well as some temporary files created by
   Drupal. After installation, you can modify the file system path to store
   uploaded files in a different location.

   It is not necessary to modify this path, but you may wish to change it if:

   - Your site runs multiple Drupal installations from a single codebase (modify
     the file system path of each installation to a different directory so that
     uploads do not overlap between installations).

   - Your site runs on a number of web servers behind a load balancer or reverse
     proxy (modify the file system path on each server to point to a shared file
     repository).

   - You want to restrict access to uploaded files.

   To modify the file system path:

   a. Ensure that the new location for the path exists and is writable by the
      web server. For example, to create a new directory named uploads and grant
      write permissions, use the following commands on a Unix/Linux command
      line:

        mkdir uploads
        chmod a+w uploads

   b. Open your settings.php in a plain-text editor, and uncomment (remove the #
      at the start of line) this line:

        # $settings['file_public_path'] = 'sites/default/files';

      Enter the desired path and save the file.

      If you want to use private file storage, you need to uncomment (remove
      the # at the start of line) the following line in settings.php:

        # $settings['file_private_path'] = '';

      Enter the path for private files and save the file.

   Changing the file system path after files have been uploaded may cause
   unexpected problems on an existing site. If you modify the file system path
   on an existing site, remember to copy all files from the original location
   to the new location.

6. Revoke documentation file permissions (optional).

   Some administrators suggest making the documentation files, especially
   CHANGELOG.txt, non-readable so that the exact version of Drupal you are
   running is slightly more difficult to determine. If you wish to implement
   this optional security measure, from a Unix/Linux command line you can use
   the following command:

     chmod a-r core/CHANGELOG.txt

   Note that the example only affects CHANGELOG.txt. To completely hide all
   documentation files from public view, repeat this command for each of the
   Drupal documentation files in the installation directory, substituting the
   name of each file for CHANGELOG.txt in the example.

   For more information on setting file permissions, see "Modifying Linux,
   Unix, and Mac file permissions" (https://www.drupal.org/node/202483) or
   "Modifying Windows file permissions" (https://www.drupal.org/node/202491) in
   the Drupal.org online documentation.

7. Set up independent "cron" maintenance jobs.

   Many Drupal modules have tasks that must be run periodically, including the
   Search module (building and updating the index used for keyword searching)
   and the System module (performing routine maintenance and pruning of
   database tables). These tasks are known as "cron maintenance tasks", named
   after the Unix/Linux "cron" utility.

   When you install Drupal, its built-in cron feature is enabled, which
   automatically runs the cron tasks periodically, triggered by people visiting
   pages of your site. You can configure the built-in cron feature by navigating
   to Administration > Configuration > System > Cron.

   It is also possible to run the cron tasks independent of site visits; this is
   recommended for most sites. To do this, you will need to set up an automated
   process to visit the page /cron on your site, which executes the cron
   tasks.

   The URL of the cron page requires a "cron key" to protect against
   unauthorized access. Your site's cron key is automatically generated during
   installation and is specific to your site. The full URL of the page, with the
   cron key, is available in the "Cron maintenance tasks" section of the Status
   report page at Administration > Reports > Status report.

   As an example of how to set up this automated process, you can use the
   crontab utility on Unix/Linux systems. The following crontab line uses the
   wget command to visit the cron page, and runs each hour, on the hour:

   0 * * * * wget -O - -q -t 1 http://example.com/cron/YOURKEY

   Replace the text "http://example.com/cron/YOURKEY" in the example with the
   full URL displayed under "Cron maintenance tasks" on the "Status report"
   page.

   More information about cron maintenance tasks is available at
   https://www.drupal.org/docs/administering-a-drupal-site/cron-automated-tasks,
   and sample cron shell scripts can be found in the core/scripts/ directory.
   (Note that these scripts must be customized like the above example, to add
   your site-specific cron key and domain name.)

REINSTALL
------------

Drupal can be reinstalled without downloading and extracting the Drupal release.

1. Drop all the tables in your database.

2. Remove everything in sites/default/files.

3. Remove sites/default/settings.php.

4. Follow the Installation Instructions above starting from Step 3 (Run the
   install script).

BUILDING AND CUSTOMIZING YOUR SITE
----------------------------------

A new installation of Drupal defaults to a very basic configuration. To extend
your site, you use "modules" and "themes". A module is a plugin that adds
functionality to Drupal, while a theme changes the look of your site. The core
of Drupal provides several optional modules and themes, and you can download
more at https://www.drupal.org/project/project_module and
https://www.drupal.org/project/project_theme

Do not mix downloaded or custom modules and themes with Drupal's core modules
and themes. Drupal's modules and themes are located in the /core/modules and
/core/themes directories, while the modules and themes you add to Drupal are
normally placed in the /modules and /themes directories. If you run a multisite
installation, you can also place modules and themes in the site-specific
directories -- see the Multisite Configuration section, below.

Never edit Drupal's core modules and themes; instead, use the hooks available in
the Drupal API. To modify the behavior of Drupal, develop a module as described
at https://www.drupal.org/developing/modules. To modify the look of Drupal,
create a subtheme as described at https://www.drupal.org/node/2165673, or a
completely new theme as described at https://www.drupal.org/docs/8/theming

MULTISITE CONFIGURATION
-----------------------

A single Drupal installation can host several Drupal-powered sites, each with
its own individual configuration.

For this to work you need the file sites/sites.php to exist. Make a copy of
the example.sites.php file:

  $ cp sites/example.sites.php sites/sites.php

Additional site configurations are created in subdirectories within the 'sites'
directory. Each subdirectory must have a 'settings.php' file, which specifies
the configuration settings. The easiest way to create additional sites is to
copy file 'default.settings.php' from the 'sites/default' directory into the
new site directory with file name 'settings.php' and modify as appropriate.
The new directory name is constructed from the site's URL. The configuration
for www.example.com could be in 'sites/example.com/settings.php' (note that
'www.' should be omitted if users can access your site at http://example.com/).

  $ cp sites/default/default.settings.php sites/example.com/settings.php

Sites do not have to have a different domain. You can also use subdomains and
subdirectories for Drupal sites. For example, example.com, sub.example.com, and
sub.example.com/site3 can all be defined as independent Drupal sites. The setup
for a configuration such as this would look like the following:

  sites/default/settings.php
  sites/example.com/settings.php
  sites/sub.example.com/settings.php
  sites/sub.example.com.site3/settings.php

When searching for a site configuration (for example www.sub.example.com/site3),
Drupal will search for configuration files in the following order, using the
first configuration it finds:

  sites/www.sub.example.com.site3/settings.php
  sites/sub.example.com.site3/settings.php
  sites/example.com.site3/settings.php
  sites/www.sub.example.com/settings.php
  sites/sub.example.com/settings.php
  sites/example.com/settings.php
  sites/default/settings.php

If you are installing on a non-standard port, the port number is treated as the
deepest subdomain. For example: http://www.example.com:8080/ could be loaded
from sites/8080.www.example.com/. The port number will be removed according to
the pattern above if no port-specific configuration is found, just like a real
subdomain.

Each site configuration can have its own site-specific modules and themes in
addition to those installed in the standard 'modules' and 'themes' directories.
To use site-specific modules or themes, simply create a 'modules' or 'themes'
directory within the site configuration directory. For example, if
sub.example.com has a custom theme and a custom module that should not be
accessible to other sites, the setup would look like this:

  sites/sub.example.com/
    settings.php
    themes/custom_theme
    modules/custom_module

For more information about multiple virtual hosts or the configuration
settings, consult https://www.drupal.org/docs/8/multisite

For more information on configuring Drupal's file system path in a multisite
configuration, see step 6 above.

MULTILINGUAL CONFIGURATION
--------------------------

By default, Drupal is installed in one language, and further languages may be
installed later.

For detailed instructions, visit
https://www.drupal.org/docs/8/multilingual

File

core/INSTALL.txt
View source
  1. CONTENTS OF THIS FILE
  2. ---------------------
  3. * Quickstart
  4. * Requirements and notes
  5. * Optional server requirements
  6. * Installation
  7. * Reinstall
  8. * Building and customizing your site
  9. * Multisite configuration
  10. * Multilingual configuration
  11. QUICKSTART
  12. ----------------------
  13. Prerequisites:
  14. - PHP 8.1.0 (or greater) (https://php.net).
  15. In the instructions below, replace the version x.y.z with the specific version
  16. you wish to download. Example: 8.6.0.zip. You can find the latest stable version
  17. at https://www.drupal.org/project/drupal.
  18. Download and extract the Drupal package:
  19. - curl -sS https://ftp.drupal.org/files/projects/drupal-x.y.z.zip --output drupal-x.y.z.zip
  20. - unzip drupal-x.y.z.zip
  21. - cd /path/to/drupal-x.y.z
  22. - php core/scripts/drupal quick-start
  23. Wait… installation can take a minute or two. A successful installation will
  24. result in opening the new site in your browser.
  25. Run the following command for a list of available options that you may need to
  26. configure quick-start:
  27. - php core/scripts/drupal quick-start --help
  28. Follow the instructions in the REINSTALL section below to start over.
  29. NOTE: This quick start solution uses PHP's built-in web server and is not
  30. intended for production use. Read more about how to run Drupal in a production
  31. environment below.
  32. REQUIREMENTS AND NOTES
  33. ----------------------
  34. Drupal requires:
  35. - A web server with PHP support, for example:
  36. - Apache 2.4.7 (or greater) (http://httpd.apache.org/).
  37. - Nginx 1.1 (or greater) (http://nginx.com/).
  38. - PHP 8.1.0 (or greater) (http://php.net/).
  39. - One of the following databases:
  40. - MySQL 5.7.8 (or greater) (http://www.mysql.com/).
  41. - MariaDB 10.3.7 (or greater) (https://mariadb.org/). MariaDB is a fully
  42. compatible drop-in replacement for MySQL.
  43. - Percona Server 5.7.8 (or greater) (http://www.percona.com/). Percona
  44. Server is a backwards-compatible replacement for MySQL.
  45. - PostgreSQL 10 (or greater) (http://www.postgresql.org/).
  46. - SQLite 3.26 (or greater) (http://www.sqlite.org/).
  47. For more detailed information about Drupal requirements, including a list of
  48. PHP extensions and configurations that are required, see "System requirements"
  49. (https://www.drupal.org/docs/system-requirements) in the Drupal.org online
  50. documentation.
  51. For detailed information on how to configure a test server environment using a
  52. variety of operating systems and web servers, see "Local server setup"
  53. (https://www.drupal.org/node/157602) in the Drupal.org online documentation.
  54. Note that all directories mentioned in this document are always relative to the
  55. directory of your Drupal installation, and commands are meant to be run from
  56. this directory (except for the initial commands that create that directory).
  57. OPTIONAL SERVER REQUIREMENTS
  58. ----------------------------
  59. - If you want to use Drupal's "Clean URLs" feature on an Apache web server, you
  60. will need the mod_rewrite module and the ability to use local .htaccess
  61. files. For Clean URLs support on IIS, see "Clean URLs with IIS"
  62. (https://www.drupal.org/node/3854) in the Drupal.org online documentation.
  63. - If you plan to use XML-based services such as RSS aggregation, you will need
  64. PHP's XML extension. This extension is enabled by default on most PHP
  65. installations.
  66. - To serve gzip compressed CSS and JS files on an Apache web server, you will
  67. need the mod_headers module and the ability to use local .htaccess files.
  68. - Some Drupal functionality (e.g., checking whether Drupal and contributed
  69. modules need updates, RSS aggregation, etc.) require that the web server be
  70. able to go out to the web and download information. If you want to use this
  71. functionality, you need to verify that your hosting provider or server
  72. configuration allows the web server to initiate outbound connections. Most web
  73. hosting setups allow this.
  74. INSTALLATION
  75. ------------
  76. 1. Download and extract Drupal.
  77. You can obtain the latest Drupal release from https://www.drupal.org -- the
  78. files are available in .tar.gz and .zip formats and can be extracted using
  79. most compression tools.
  80. To download and extract the files, on a typical Unix/Linux command line, use
  81. the following commands (assuming you want version x.y.z of Drupal in .tar.gz
  82. format):
  83. wget https://www.drupal.org/files/projects/drupal-x.y.z.tar.gz
  84. tar -zxvf drupal-x.y.z.tar.gz
  85. This will create a new directory drupal-x.y.z/ containing all Drupal files
  86. and directories. Then, to move the contents of that directory into a
  87. directory within your web server's document root or your public HTML
  88. directory, continue with this command:
  89. mv drupal-x.y.z/* drupal-x.y.z/.htaccess drupal-x.y.z/.csslintrc drupal-x.y.z/.editorconfig drupal-x.y.z/.eslintignore drupal-x.y.z/.eslintrc.json drupal-x.y.z/.gitattributes /path/to/your/installation
  90. You can also download the latest version of Drupal using Git on the command
  91. line and set up a repository by following the instructions at
  92. https://www.drupal.org/project/drupal/git-instructions for "Setting up
  93. repository for the first time".
  94. Once you have downloaded Drupal successfully, you may install Composer
  95. globally using the instructions at
  96. https://getcomposer.org/doc/00-intro.md#globally
  97. With Composer installed, run the following command from the Drupal web root:
  98. composer install
  99. 2. Create the Drupal database.
  100. Because Drupal stores all site information in a database, the Drupal
  101. installer will attempt to create this database for you. If you create the
  102. database manually, you must grant Drupal certain database privileges (such as
  103. the ability to create tables). For details, consult INSTALL.mysql.txt,
  104. INSTALL.pgsql.txt, or INSTALL.sqlite.txt. You may also need to consult your
  105. web hosting provider for instructions specific to your web host.
  106. Take note of the username, password, database name, and hostname as you
  107. create the database. You will enter this information during the install.
  108. 3. Run the install script.
  109. To run the install script, point your browser to the base URL of your
  110. website (e.g., http://www.example.com).
  111. You will be guided through several screens to set up the database, add the
  112. site maintenance account (the first user, also known as user/1), and provide
  113. basic website settings.
  114. During installation, several files and directories need to be created, which
  115. the install script will try to do automatically. However, on some hosting
  116. environments, manual steps are required, and the install script will tell
  117. you that it cannot proceed until you fix certain issues. This is normal and
  118. does not indicate a problem with your server.
  119. The most common steps you may need to perform are:
  120. a. Missing files directory.
  121. The install script will attempt to create a public file storage directory
  122. in the default location at sites/default/files (the location of the files
  123. directory may be changed after Drupal is installed).
  124. If auto-creation fails, you can create the directory yourself. (If you are
  125. creating a multisite installation, substitute the correct sites directory
  126. for sites/default; see the Multisite Configuration section of this file,
  127. below.) Sample commands from a Unix/Linux command line:
  128. mkdir sites/default/files
  129. chmod a+w sites/default/files
  130. Alternatively, you can make the install script work by changing
  131. permissions on the sites/default directory. The web server can then
  132. create the files directory within it for you.
  133. For example, on a Unix/Linux command line, you can grant everyone
  134. (including the web server) permission to write to the sites/default
  135. directory with this command:
  136. chmod a+w sites/default
  137. Then re-run install.php (e.g. by clicking "try again" at the bottom of
  138. the Requirements problem page. Once the files directory is created, you
  139. will need to grant everyone (including the web server) permission to
  140. write to it with this command:
  141. chmod a+w sites/default/files
  142. Be sure to set the permissions for the default directory back after the
  143. installation is finished! (Leave the files directory writable.)
  144. Sample command:
  145. chmod go-w sites/default
  146. b. Missing settings file.
  147. Drupal will try to automatically create a settings.php configuration file,
  148. which is normally in the directory sites/default (to avoid problems when
  149. upgrading, Drupal is not packaged with this file). If auto-creation fails,
  150. you will need to create this file yourself, using the file
  151. sites/default/default.settings.php as a template.
  152. For example, on a Unix/Linux command line, you can make a copy of the
  153. default.settings.php file with the command:
  154. cp sites/default/default.settings.php sites/default/settings.php
  155. Next, grant write privileges to the file to everyone (including the web
  156. server) with the command:
  157. chmod a+w sites/default/settings.php
  158. Be sure to set the permissions back after the installation is finished!
  159. Sample command:
  160. chmod go-w sites/default/settings.php
  161. c. Write permissions after install.
  162. The install script will attempt to write-protect the settings.php file and
  163. the sites/default directory after saving your configuration. If this
  164. fails, you will be notified, and you can do it manually. Sample commands
  165. from a Unix/Linux command line:
  166. chmod go-w sites/default/settings.php
  167. chmod go-w sites/default
  168. 4. Verify that the site is working.
  169. When the install script finishes, you will be logged in with the site
  170. maintenance account on a "Welcome" page. If the default Drupal theme is not
  171. displaying properly and links on the page result in "Page Not Found" errors,
  172. you may be experiencing problems with clean URLs. Visit
  173. https://www.drupal.org/docs/8/clean-urls-in-drupal-8 to troubleshoot.
  174. 5. Change file system storage settings (optional).
  175. The files directory created in step 3 is the default file system path used to
  176. store all uploaded files, as well as some temporary files created by
  177. Drupal. After installation, you can modify the file system path to store
  178. uploaded files in a different location.
  179. It is not necessary to modify this path, but you may wish to change it if:
  180. - Your site runs multiple Drupal installations from a single codebase (modify
  181. the file system path of each installation to a different directory so that
  182. uploads do not overlap between installations).
  183. - Your site runs on a number of web servers behind a load balancer or reverse
  184. proxy (modify the file system path on each server to point to a shared file
  185. repository).
  186. - You want to restrict access to uploaded files.
  187. To modify the file system path:
  188. a. Ensure that the new location for the path exists and is writable by the
  189. web server. For example, to create a new directory named uploads and grant
  190. write permissions, use the following commands on a Unix/Linux command
  191. line:
  192. mkdir uploads
  193. chmod a+w uploads
  194. b. Open your settings.php in a plain-text editor, and uncomment (remove the #
  195. at the start of line) this line:
  196. # $settings['file_public_path'] = 'sites/default/files';
  197. Enter the desired path and save the file.
  198. If you want to use private file storage, you need to uncomment (remove
  199. the # at the start of line) the following line in settings.php:
  200. # $settings['file_private_path'] = '';
  201. Enter the path for private files and save the file.
  202. Changing the file system path after files have been uploaded may cause
  203. unexpected problems on an existing site. If you modify the file system path
  204. on an existing site, remember to copy all files from the original location
  205. to the new location.
  206. 6. Revoke documentation file permissions (optional).
  207. Some administrators suggest making the documentation files, especially
  208. CHANGELOG.txt, non-readable so that the exact version of Drupal you are
  209. running is slightly more difficult to determine. If you wish to implement
  210. this optional security measure, from a Unix/Linux command line you can use
  211. the following command:
  212. chmod a-r core/CHANGELOG.txt
  213. Note that the example only affects CHANGELOG.txt. To completely hide all
  214. documentation files from public view, repeat this command for each of the
  215. Drupal documentation files in the installation directory, substituting the
  216. name of each file for CHANGELOG.txt in the example.
  217. For more information on setting file permissions, see "Modifying Linux,
  218. Unix, and Mac file permissions" (https://www.drupal.org/node/202483) or
  219. "Modifying Windows file permissions" (https://www.drupal.org/node/202491) in
  220. the Drupal.org online documentation.
  221. 7. Set up independent "cron" maintenance jobs.
  222. Many Drupal modules have tasks that must be run periodically, including the
  223. Search module (building and updating the index used for keyword searching)
  224. and the System module (performing routine maintenance and pruning of
  225. database tables). These tasks are known as "cron maintenance tasks", named
  226. after the Unix/Linux "cron" utility.
  227. When you install Drupal, its built-in cron feature is enabled, which
  228. automatically runs the cron tasks periodically, triggered by people visiting
  229. pages of your site. You can configure the built-in cron feature by navigating
  230. to Administration > Configuration > System > Cron.
  231. It is also possible to run the cron tasks independent of site visits; this is
  232. recommended for most sites. To do this, you will need to set up an automated
  233. process to visit the page /cron on your site, which executes the cron
  234. tasks.
  235. The URL of the cron page requires a "cron key" to protect against
  236. unauthorized access. Your site's cron key is automatically generated during
  237. installation and is specific to your site. The full URL of the page, with the
  238. cron key, is available in the "Cron maintenance tasks" section of the Status
  239. report page at Administration > Reports > Status report.
  240. As an example of how to set up this automated process, you can use the
  241. crontab utility on Unix/Linux systems. The following crontab line uses the
  242. wget command to visit the cron page, and runs each hour, on the hour:
  243. 0 * * * * wget -O - -q -t 1 http://example.com/cron/YOURKEY
  244. Replace the text "http://example.com/cron/YOURKEY" in the example with the
  245. full URL displayed under "Cron maintenance tasks" on the "Status report"
  246. page.
  247. More information about cron maintenance tasks is available at
  248. https://www.drupal.org/docs/administering-a-drupal-site/cron-automated-tasks,
  249. and sample cron shell scripts can be found in the core/scripts/ directory.
  250. (Note that these scripts must be customized like the above example, to add
  251. your site-specific cron key and domain name.)
  252. REINSTALL
  253. ------------
  254. Drupal can be reinstalled without downloading and extracting the Drupal release.
  255. 1. Drop all the tables in your database.
  256. 2. Remove everything in sites/default/files.
  257. 3. Remove sites/default/settings.php.
  258. 4. Follow the Installation Instructions above starting from Step 3 (Run the
  259. install script).
  260. BUILDING AND CUSTOMIZING YOUR SITE
  261. ----------------------------------
  262. A new installation of Drupal defaults to a very basic configuration. To extend
  263. your site, you use "modules" and "themes". A module is a plugin that adds
  264. functionality to Drupal, while a theme changes the look of your site. The core
  265. of Drupal provides several optional modules and themes, and you can download
  266. more at https://www.drupal.org/project/project_module and
  267. https://www.drupal.org/project/project_theme
  268. Do not mix downloaded or custom modules and themes with Drupal's core modules
  269. and themes. Drupal's modules and themes are located in the /core/modules and
  270. /core/themes directories, while the modules and themes you add to Drupal are
  271. normally placed in the /modules and /themes directories. If you run a multisite
  272. installation, you can also place modules and themes in the site-specific
  273. directories -- see the Multisite Configuration section, below.
  274. Never edit Drupal's core modules and themes; instead, use the hooks available in
  275. the Drupal API. To modify the behavior of Drupal, develop a module as described
  276. at https://www.drupal.org/developing/modules. To modify the look of Drupal,
  277. create a subtheme as described at https://www.drupal.org/node/2165673, or a
  278. completely new theme as described at https://www.drupal.org/docs/8/theming
  279. MULTISITE CONFIGURATION
  280. -----------------------
  281. A single Drupal installation can host several Drupal-powered sites, each with
  282. its own individual configuration.
  283. For this to work you need the file sites/sites.php to exist. Make a copy of
  284. the example.sites.php file:
  285. $ cp sites/example.sites.php sites/sites.php
  286. Additional site configurations are created in subdirectories within the 'sites'
  287. directory. Each subdirectory must have a 'settings.php' file, which specifies
  288. the configuration settings. The easiest way to create additional sites is to
  289. copy file 'default.settings.php' from the 'sites/default' directory into the
  290. new site directory with file name 'settings.php' and modify as appropriate.
  291. The new directory name is constructed from the site's URL. The configuration
  292. for www.example.com could be in 'sites/example.com/settings.php' (note that
  293. 'www.' should be omitted if users can access your site at http://example.com/).
  294. $ cp sites/default/default.settings.php sites/example.com/settings.php
  295. Sites do not have to have a different domain. You can also use subdomains and
  296. subdirectories for Drupal sites. For example, example.com, sub.example.com, and
  297. sub.example.com/site3 can all be defined as independent Drupal sites. The setup
  298. for a configuration such as this would look like the following:
  299. sites/default/settings.php
  300. sites/example.com/settings.php
  301. sites/sub.example.com/settings.php
  302. sites/sub.example.com.site3/settings.php
  303. When searching for a site configuration (for example www.sub.example.com/site3),
  304. Drupal will search for configuration files in the following order, using the
  305. first configuration it finds:
  306. sites/www.sub.example.com.site3/settings.php
  307. sites/sub.example.com.site3/settings.php
  308. sites/example.com.site3/settings.php
  309. sites/www.sub.example.com/settings.php
  310. sites/sub.example.com/settings.php
  311. sites/example.com/settings.php
  312. sites/default/settings.php
  313. If you are installing on a non-standard port, the port number is treated as the
  314. deepest subdomain. For example: http://www.example.com:8080/ could be loaded
  315. from sites/8080.www.example.com/. The port number will be removed according to
  316. the pattern above if no port-specific configuration is found, just like a real
  317. subdomain.
  318. Each site configuration can have its own site-specific modules and themes in
  319. addition to those installed in the standard 'modules' and 'themes' directories.
  320. To use site-specific modules or themes, simply create a 'modules' or 'themes'
  321. directory within the site configuration directory. For example, if
  322. sub.example.com has a custom theme and a custom module that should not be
  323. accessible to other sites, the setup would look like this:
  324. sites/sub.example.com/
  325. settings.php
  326. themes/custom_theme
  327. modules/custom_module
  328. For more information about multiple virtual hosts or the configuration
  329. settings, consult https://www.drupal.org/docs/8/multisite
  330. For more information on configuring Drupal's file system path in a multisite
  331. configuration, see step 6 above.
  332. MULTILINGUAL CONFIGURATION
  333. --------------------------
  334. By default, Drupal is installed in one language, and further languages may be
  335. installed later.
  336. For detailed instructions, visit
  337. https://www.drupal.org/docs/8/multilingual