txt

By wentm, 22 September, 2024


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.3.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.3.0 (or greater) (http://php.net/). - One of the following databases:  - MySQL 8.0.0 (or greater) (http://www.mysql.com/).  - MariaDB 10.6.0 (or greater) (https://mariadb.org/). MariaDB is a fully    compatible drop-in replacement for MySQL.  - Percona Server 8.0.0 (or greater) (http://www.percona.com/). Percona    Server is a backwards-compatible replacement for MySQL.  - PostgreSQL 16 (or greater) (http://www.postgresql.org/).  - SQLite 3.45 (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

Comments