Drupal: core/INSTALL.txt

"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