"Fossies" - the Fresh Open Source Software Archive

Member "drupal-9.4.5/core/INSTALL.txt" (3 Aug 2022, 19956 Bytes) of package /linux/www/drupal-9.4.5.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "INSTALL.txt": 9.3.16_vs_9.4.0.

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