Chris@0: 
Chris@0: CONTENTS OF THIS FILE
Chris@0: ---------------------
Chris@0: 
Chris@17:  * Quickstart
Chris@0:  * Requirements and notes
Chris@0:  * Optional server requirements
Chris@0:  * Installation
Chris@0:  * Reinstall
Chris@0:  * Building and customizing your site
Chris@0:  * Multisite configuration
Chris@0:  * Multilingual configuration
Chris@0: 
Chris@17: QUICKSTART
Chris@17: ----------------------
Chris@17: 
Chris@17: Prerequisites:
Chris@17: - PHP 5.5.9 (or greater) (https://php.net).
Chris@17: 
Chris@17: In the instructions below, replace the version x.y.z with the specific version
Chris@17: you wish to download. Example: 8.6.0.zip. You can find the latest stable version
Chris@17: at https://www.drupal.org/project/drupal.
Chris@17: 
Chris@17: Download and extract the Drupal package:
Chris@17: - curl -sS https://ftp.drupal.org/files/projects/drupal-x.y.z.zip --output drupal-x.y.z.zip
Chris@17: - unzip drupal-x.y.z.zip
Chris@17: - cd /path/to/drupal-x.y.z
Chris@17: - php core/scripts/drupal quick-start
Chris@17: 
Chris@17: Wait… installation can take a minute or two. A successful installation will
Chris@17: result in opening the new site in your browser.
Chris@17: 
Chris@17: Run the following command for a list of available options that you may need to
Chris@17: configure quick-start:
Chris@17: - php core/scripts/drupal quick-start --help
Chris@17: 
Chris@17: Follow the instructions in the REINSTALL section below to start over.
Chris@17: 
Chris@17: NOTE: This quick start solution uses PHP's built-in web server and is not
Chris@17: intended for production use. Read more about how to run Drupal in a production
Chris@17: environment below.
Chris@17: 
Chris@0: REQUIREMENTS AND NOTES
Chris@0: ----------------------
Chris@0: 
Chris@0: Drupal requires:
Chris@0: 
Chris@0: - A web server with PHP support, for example:
Chris@0:   - Apache 2.0 (or greater) (http://httpd.apache.org/).
Chris@0:   - Nginx 1.1 (or greater) (http://nginx.com/).
Chris@0: - PHP 5.5.9 (or greater) (http://php.net/). For better security support it is
Chris@0:   recommended to update to at least 5.5.21 or 5.6.5.
Chris@0: - One of the following databases:
Chris@0:   - MySQL 5.5.3 (or greater) (http://www.mysql.com/).
Chris@0:   - MariaDB 5.5.20 (or greater) (https://mariadb.org/). MariaDB is a fully
Chris@0:     compatible drop-in replacement for MySQL.
Chris@0:   - Percona Server 5.5.8 (or greater) (http://www.percona.com/). Percona
Chris@0:     Server is a backwards-compatible replacement for MySQL.
Chris@0:   - PostgreSQL 9.1.2 (or greater) (http://www.postgresql.org/).
Chris@0:   - SQLite 3.7.11 (or greater) (http://www.sqlite.org/).
Chris@0: 
Chris@0: For more detailed information about Drupal requirements, including a list of
Chris@0: PHP extensions and configurations that are required, see "System requirements"
Chris@0: (https://www.drupal.org/requirements) in the Drupal.org online documentation.
Chris@0: 
Chris@0: For detailed information on how to configure a test server environment using a
Chris@0: variety of operating systems and web servers, see "Local server setup"
Chris@0: (https://www.drupal.org/node/157602) in the Drupal.org online documentation.
Chris@0: 
Chris@0: Note that all directories mentioned in this document are always relative to the
Chris@0: directory of your Drupal installation, and commands are meant to be run from
Chris@0: this directory (except for the initial commands that create that directory).
Chris@0: 
Chris@0: OPTIONAL SERVER REQUIREMENTS
Chris@0: ----------------------------
Chris@0: 
Chris@0: - If you want to use Drupal's "Clean URLs" feature on an Apache web server, you
Chris@0:   will need the mod_rewrite module and the ability to use local .htaccess
Chris@0:   files. For Clean URLs support on IIS, see "Clean URLs with IIS"
Chris@0:   (https://www.drupal.org/node/3854) in the Drupal.org online documentation.
Chris@0: 
Chris@0: - If you plan to use XML-based services such as RSS aggregation, you will need
Chris@0:   PHP's XML extension. This extension is enabled by default on most PHP
Chris@0:   installations.
Chris@0: 
Chris@0: - To serve gzip compressed CSS and JS files on an Apache web server, you will
Chris@0:   need the mod_headers module and the ability to use local .htaccess files.
Chris@0: 
Chris@0: - Some Drupal functionality (e.g., checking whether Drupal and contributed
Chris@0:   modules need updates, RSS aggregation, etc.) require that the web server be
Chris@0:   able to go out to the web and download information. If you want to use this
Chris@0:   functionality, you need to verify that your hosting provider or server
Chris@0:   configuration allows the web server to initiate outbound connections. Most web
Chris@0:   hosting setups allow this.
Chris@0: 
Chris@0: - PHP 5.5.21 provides features for improved security when used with MySQL. While
Chris@0:   this is not required, it is highly encouraged to use PHP 5.5.21 or 5.6.5 and
Chris@0:   above.
Chris@0: 
Chris@0: INSTALLATION
Chris@0: ------------
Chris@0: 
Chris@0: 1. Download and extract Drupal.
Chris@0: 
Chris@0:    You can obtain the latest Drupal release from https://www.drupal.org -- the
Chris@0:    files are available in .tar.gz and .zip formats and can be extracted using
Chris@0:    most compression tools.
Chris@0: 
Chris@0:    To download and extract the files, on a typical Unix/Linux command line, use
Chris@0:    the following commands (assuming you want version x.y.z of Drupal in .tar.gz
Chris@0:    format):
Chris@0: 
Chris@0:      wget https://www.drupal.org/files/projects/drupal-x.y.z.tar.gz
Chris@0:      tar -zxvf drupal-x.y.z.tar.gz
Chris@0: 
Chris@0:    This will create a new directory drupal-x.y.z/ containing all Drupal files
Chris@0:    and directories. Then, to move the contents of that directory into a
Chris@0:    directory within your web server's document root or your public HTML
Chris@0:    directory, continue with this command:
Chris@0: 
Chris@0:      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
Chris@0: 
Chris@0:    You can also download the latest version of Drupal using Git on the command
Chris@0:    line and set up a repository by following the instructions at
Chris@0:    https://www.drupal.org/project/drupal/git-instructions for "Setting up
Chris@0:    repository for the first time".
Chris@0: 
Chris@0:    Once you have downloaded Drupal successfully, you may install Composer
Chris@0:    globally using the instructions at
Chris@0:    https://getcomposer.org/doc/00-intro.md#globally
Chris@0: 
Chris@0:    With Composer installed, run the following command from the Drupal web root:
Chris@0: 
Chris@0:      composer install
Chris@0: 
Chris@0: 2. Create the Drupal database.
Chris@0: 
Chris@0:    Because Drupal stores all site information in a database, the Drupal
Chris@0:    installer will attempt to create this database for you. If you create the
Chris@0:    database manually, you must grant Drupal certain database privileges (such as
Chris@0:    the ability to create tables).  For details, consult INSTALL.mysql.txt,
Chris@0:    INSTALL.pgsql.txt, or INSTALL.sqlite.txt. You may also need to consult your
Chris@0:    web hosting provider for instructions specific to your web host.
Chris@0: 
Chris@0:    Take note of the username, password, database name, and hostname as you
Chris@0:    create the database. You will enter this information during the install.
Chris@0: 
Chris@0: 3. Run the install script.
Chris@0: 
Chris@0:    To run the install script, point your browser to the base URL of your
Chris@0:    website (e.g., http://www.example.com).
Chris@0: 
Chris@0:    You will be guided through several screens to set up the database, add the
Chris@0:    site maintenance account (the first user, also known as user/1), and provide
Chris@0:    basic web site settings.
Chris@0: 
Chris@0:    During installation, several files and directories need to be created, which
Chris@0:    the install script will try to do automatically. However, on some hosting
Chris@0:    environments, manual steps are required, and the install script will tell
Chris@0:    you that it cannot proceed until you fix certain issues. This is normal and
Chris@0:    does not indicate a problem with your server.
Chris@0: 
Chris@0:    The most common steps you may need to perform are:
Chris@0: 
Chris@0:    a. Missing files directory.
Chris@0: 
Chris@0:       The install script will attempt to create a public file storage directory
Chris@0:       in the default location at sites/default/files (the location of the files
Chris@0:       directory may be changed after Drupal is installed).
Chris@0: 
Chris@0:       If auto-creation fails, you can create the directory yourself. (If you are
Chris@0:       creating a multisite installation, substitute the correct sites directory
Chris@0:       for sites/default; see the Multisite Configuration section of this file,
Chris@0:       below.) Sample commands from a Unix/Linux command line:
Chris@0: 
Chris@0:         mkdir sites/default/files
Chris@0:         chmod a+w sites/default/files
Chris@0: 
Chris@0:       Alternatively, you can make the install script work by changing
Chris@0:       permissions on the sites/default directory. The web server can then
Chris@0:       create the files directory within it for you.
Chris@0: 
Chris@0:       For example, on a Unix/Linux command line, you can you can grant everyone
Chris@0:       (including the web server) permission to write to the sites/default
Chris@0:       directory with this command:
Chris@0: 
Chris@0:         chmod a+w sites/default
Chris@0: 
Chris@0:       Then re-run install.php (e.g. by clicking "try again" at the bottom of
Chris@0:       the Requirements problem page. Once the files directory is created, you
Chris@0:       will need to grant everyone (including the web server) permission to
Chris@0:       write to it with this command:
Chris@0: 
Chris@0:         chmod a+w sites/default/files
Chris@0: 
Chris@0:       Be sure to set the permissions for the default directory back after the
Chris@0:       installation is finished! (Leave the files directory writeable.)
Chris@0:       Sample command:
Chris@0: 
Chris@0:         chmod go-w sites/default
Chris@0: 
Chris@0:    b. Missing settings file.
Chris@0: 
Chris@0:       Drupal will try to automatically create a settings.php configuration file,
Chris@0:       which is normally in the directory sites/default (to avoid problems when
Chris@0:       upgrading, Drupal is not packaged with this file). If auto-creation fails,
Chris@0:       you will need to create this file yourself, using the file
Chris@0:       sites/default/default.settings.php as a template.
Chris@0: 
Chris@0:       For example, on a Unix/Linux command line, you can make a copy of the
Chris@0:       default.settings.php file with the command:
Chris@0: 
Chris@0:         cp sites/default/default.settings.php sites/default/settings.php
Chris@0: 
Chris@0:       Next, grant write privileges to the file to everyone (including the web
Chris@0:       server) with the command:
Chris@0: 
Chris@0:         chmod a+w sites/default/settings.php
Chris@0: 
Chris@0:       Be sure to set the permissions back after the installation is finished!
Chris@0:       Sample command:
Chris@0: 
Chris@0:         chmod go-w sites/default/settings.php
Chris@0: 
Chris@0:    c. Write permissions after install.
Chris@0: 
Chris@0:       The install script will attempt to write-protect the settings.php file and
Chris@0:       the sites/default directory after saving your configuration. If this
Chris@0:       fails, you will be notified, and you can do it manually. Sample commands
Chris@0:       from a Unix/Linux command line:
Chris@0: 
Chris@0:         chmod go-w sites/default/settings.php
Chris@0:         chmod go-w sites/default
Chris@0: 
Chris@0: 4. Verify that the site is working.
Chris@0: 
Chris@0:    When the install script finishes, you will be logged in with the site
Chris@0:    maintenance account on a "Welcome" page. If the default Drupal theme is not
Chris@0:    displaying properly and links on the page result in "Page Not Found" errors,
Chris@0:    you may be experiencing problems with clean URLs. Visit
Chris@18:    https://www.drupal.org/docs/8/clean-urls-in-drupal-8 to troubleshoot.
Chris@0: 
Chris@0: 5. Change file system storage settings (optional).
Chris@0: 
Chris@0:    The files directory created in step 3 is the default file system path used to
Chris@0:    store all uploaded files, as well as some temporary files created by
Chris@0:    Drupal. After installation, you can modify the file system path to store
Chris@0:    uploaded files in a different location.
Chris@0: 
Chris@0:    It is not necessary to modify this path, but you may wish to change it if:
Chris@0: 
Chris@0:    - Your site runs multiple Drupal installations from a single codebase (modify
Chris@0:      the file system path of each installation to a different directory so that
Chris@0:      uploads do not overlap between installations).
Chris@0: 
Chris@0:    - Your site runs on a number of web servers behind a load balancer or reverse
Chris@0:      proxy (modify the file system path on each server to point to a shared file
Chris@0:      repository).
Chris@0: 
Chris@0:    - You want to restrict access to uploaded files.
Chris@0: 
Chris@0:    To modify the file system path:
Chris@0: 
Chris@0:    a. Ensure that the new location for the path exists and is writable by the
Chris@0:       web server. For example, to create a new directory named uploads and grant
Chris@0:       write permissions, use the following commands on a Unix/Linux command
Chris@0:       line:
Chris@0: 
Chris@0:         mkdir uploads
Chris@0:         chmod a+w uploads
Chris@0: 
Chris@0:    b. Open your settings.php in a plain-text editor, and uncomment (remove the #
Chris@0:       at the start of line) this line:
Chris@0: 
Chris@0:         # $settings['file_public_path'] = 'sites/default/files';
Chris@0: 
Chris@0:       Enter the desired path and save the file.
Chris@0: 
Chris@0:       If you want to use private file storage, you need to uncomment (remove
Chris@0:       the # at the start of line) the following line in settings.php:
Chris@0: 
Chris@0:         # $settings['file_private_path'] = '';
Chris@0: 
Chris@0:       Enter the path for private files and save the file.
Chris@0: 
Chris@0:    Changing the file system path after files have been uploaded may cause
Chris@0:    unexpected problems on an existing site. If you modify the file system path
Chris@0:    on an existing site, remember to copy all files from the original location
Chris@0:    to the new location.
Chris@0: 
Chris@0: 6. Revoke documentation file permissions (optional).
Chris@0: 
Chris@0:    Some administrators suggest making the documentation files, especially
Chris@0:    CHANGELOG.txt, non-readable so that the exact version of Drupal you are
Chris@0:    running is slightly more difficult to determine. If you wish to implement
Chris@0:    this optional security measure, from a Unix/Linux command line you can use
Chris@0:    the following command:
Chris@0: 
Chris@16:      chmod a-r core/CHANGELOG.txt
Chris@0: 
Chris@0:    Note that the example only affects CHANGELOG.txt. To completely hide all
Chris@0:    documentation files from public view, repeat this command for each of the
Chris@0:    Drupal documentation files in the installation directory, substituting the
Chris@0:    name of each file for CHANGELOG.txt in the example.
Chris@0: 
Chris@0:    For more information on setting file permissions, see "Modifying Linux,
Chris@0:    Unix, and Mac file permissions" (https://www.drupal.org/node/202483) or
Chris@0:    "Modifying Windows file permissions" (https://www.drupal.org/node/202491) in
Chris@0:    the Drupal.org online documentation.
Chris@0: 
Chris@0: 7. Set up independent "cron" maintenance jobs.
Chris@0: 
Chris@0:    Many Drupal modules have tasks that must be run periodically, including the
Chris@0:    Search module (building and updating the index used for keyword searching),
Chris@0:    the Aggregator module (retrieving feeds from other sites), and the System
Chris@0:    module (performing routine maintenance and pruning of database tables). These
Chris@0:    tasks are known as "cron maintenance tasks", named after the Unix/Linux
Chris@0:    "cron" utility.
Chris@0: 
Chris@0:    When you install Drupal, its built-in cron feature is enabled, which
Chris@0:    automatically runs the cron tasks periodically, triggered by people visiting
Chris@0:    pages of your site. You can configure the built-in cron feature by navigating
Chris@0:    to Administration > Configuration > System > Cron.
Chris@0: 
Chris@0:    It is also possible to run the cron tasks independent of site visits; this is
Chris@0:    recommended for most sites. To do this, you will need to set up an automated
Chris@0:    process to visit the page /cron on your site, which executes the cron
Chris@0:    tasks.
Chris@0: 
Chris@0:    The URL of the cron page requires a "cron key" to protect against
Chris@0:    unauthorized access. Your site's cron key is automatically generated during
Chris@0:    installation and is specific to your site. The full URL of the page, with the
Chris@0:    cron key, is available in the "Cron maintenance tasks" section of the Status
Chris@0:    report page at Administration > Reports > Status report.
Chris@0: 
Chris@0:    As an example for how to set up this automated process, you can use the
Chris@0:    crontab utility on Unix/Linux systems. The following crontab line uses the
Chris@0:    wget command to visit the cron page, and runs each hour, on the hour:
Chris@0: 
Chris@0:    0 * * * * wget -O - -q -t 1 http://example.com/cron/YOURKEY
Chris@0: 
Chris@0:    Replace the text "http://example.com/cron/YOURKEY" in the example with the
Chris@0:    full URL displayed under "Cron maintenance tasks" on the "Status report"
Chris@0:    page.
Chris@0: 
Chris@0:    More information about cron maintenance tasks is available at
Chris@0:    https://www.drupal.org/cron, and sample cron shell scripts can be found in
Chris@0:    the core/scripts/ directory. (Note that these scripts must be customized like
Chris@0:    the above example, to add your site-specific cron key and domain name.)
Chris@0: 
Chris@0: REINSTALL
Chris@0: ------------
Chris@0: 
Chris@0: Drupal can be reinstalled without downloading and extracting the Drupal release.
Chris@0: 
Chris@0: 1. Drop all the tables in your database.
Chris@0: 
Chris@0: 2. Remove everything in sites/default/files.
Chris@0: 
Chris@0: 3. Remove sites/default/settings.php.
Chris@0: 
Chris@0: 4. Follow the Installation Instructions above starting from Step 3 (Run the
Chris@0:    install script).
Chris@0: 
Chris@0: BUILDING AND CUSTOMIZING YOUR SITE
Chris@0: ----------------------------------
Chris@0: 
Chris@0: A new installation of Drupal defaults to a very basic configuration. To extend
Chris@0: your site, you use "modules" and "themes". A module is a plugin that adds
Chris@0: functionality to Drupal, while a theme changes the look of your site. The core
Chris@0: of Drupal provides several optional modules and themes, and you can download
Chris@0: more at https://www.drupal.org/project/project_module and
Chris@0: https://www.drupal.org/project/project_theme
Chris@0: 
Chris@0: Do not mix downloaded or custom modules and themes with Drupal's core modules
Chris@0: and themes. Drupal's modules and themes are located in the /core/modules and
Chris@0: /core/themes directories, while the modules and themes you add to Drupal are
Chris@0: normally placed in the /modules and /themes directories. If you run a multisite
Chris@0: installation, you can also place modules and themes in the site-specific
Chris@0: directories -- see the Multisite Configuration section, below.
Chris@0: 
Chris@0: Never edit Drupal's core modules and themes; instead, use the hooks available in
Chris@0: the Drupal API. To modify the behavior of Drupal, develop a module as described
Chris@0: at https://www.drupal.org/developing/modules. To modify the look of Drupal,
Chris@0: create a subtheme as described at https://www.drupal.org/node/2165673, or a
Chris@0: completely new theme as described at https://www.drupal.org/docs/8/theming
Chris@0: 
Chris@0: MULTISITE CONFIGURATION
Chris@0: -----------------------
Chris@0: 
Chris@0: A single Drupal installation can host several Drupal-powered sites, each with
Chris@0: its own individual configuration.
Chris@0: 
Chris@0: For this to work you need the file sites/sites.php to exist. Make a copy of
Chris@0: the example.sites.php file:
Chris@0: 
Chris@0:   $ cp sites/example.sites.php sites/sites.php
Chris@0: 
Chris@0: Additional site configurations are created in subdirectories within the 'sites'
Chris@0: directory. Each subdirectory must have a 'settings.php' file, which specifies
Chris@0: the configuration settings. The easiest way to create additional sites is to
Chris@0: copy file 'default.settings.php' from the 'sites/default' directory into the
Chris@0: new site directory with file name 'settings.php' and modify as appropriate.
Chris@0: The new directory name is constructed from the site's URL. The configuration
Chris@0: for www.example.com could be in 'sites/example.com/settings.php' (note that
Chris@0: 'www.' should be omitted if users can access your site at http://example.com/).
Chris@0: 
Chris@18:   $ cp sites/default/default.settings.php sites/example.com/settings.php
Chris@0: 
Chris@0: Sites do not have to have a different domain. You can also use subdomains and
Chris@0: subdirectories for Drupal sites. For example, example.com, sub.example.com, and
Chris@0: sub.example.com/site3 can all be defined as independent Drupal sites. The setup
Chris@0: for a configuration such as this would look like the following:
Chris@0: 
Chris@0:   sites/default/settings.php
Chris@0:   sites/example.com/settings.php
Chris@0:   sites/sub.example.com/settings.php
Chris@0:   sites/sub.example.com.site3/settings.php
Chris@0: 
Chris@0: When searching for a site configuration (for example www.sub.example.com/site3),
Chris@0: Drupal will search for configuration files in the following order, using the
Chris@0: first configuration it finds:
Chris@0: 
Chris@0:   sites/www.sub.example.com.site3/settings.php
Chris@0:   sites/sub.example.com.site3/settings.php
Chris@0:   sites/example.com.site3/settings.php
Chris@0:   sites/www.sub.example.com/settings.php
Chris@0:   sites/sub.example.com/settings.php
Chris@0:   sites/example.com/settings.php
Chris@0:   sites/default/settings.php
Chris@0: 
Chris@0: If you are installing on a non-standard port, the port number is treated as the
Chris@0: deepest subdomain. For example: http://www.example.com:8080/ could be loaded
Chris@0: from sites/8080.www.example.com/. The port number will be removed according to
Chris@0: the pattern above if no port-specific configuration is found, just like a real
Chris@0: subdomain.
Chris@0: 
Chris@0: Each site configuration can have its own site-specific modules and themes in
Chris@0: addition to those installed in the standard 'modules' and 'themes' directories.
Chris@0: To use site-specific modules or themes, simply create a 'modules' or 'themes'
Chris@0: directory within the site configuration directory. For example, if
Chris@0: sub.example.com has a custom theme and a custom module that should not be
Chris@0: accessible to other sites, the setup would look like this:
Chris@0: 
Chris@0:   sites/sub.example.com/
Chris@0:     settings.php
Chris@0:     themes/custom_theme
Chris@0:     modules/custom_module
Chris@0: 
Chris@0: For more information about multiple virtual hosts or the configuration
Chris@18: settings, consult https://www.drupal.org/docs/8/multisite
Chris@0: 
Chris@0: For more information on configuring Drupal's file system path in a multisite
Chris@0: configuration, see step 6 above.
Chris@0: 
Chris@0: MULTILINGUAL CONFIGURATION
Chris@0: --------------------------
Chris@0: 
Chris@0: By default, Drupal is installed in one language, and further languages may be
Chris@0: installed later.
Chris@0: 
Chris@0: For detailed instructions, visit
Chris@18: https://www.drupal.org/docs/8/multilingual