INSTALL.txt 18.2 KB
Newer Older
Dries Buytaert's avatar
   
Dries Buytaert committed
1

Dries Buytaert's avatar
Dries Buytaert committed
2
3
4
CONTENTS OF THIS FILE
---------------------

5
6
 * Requirements and notes
 * Optional server requirements
Dries Buytaert's avatar
Dries Buytaert committed
7
 * Installation
8
 * Reinstall
9
 * Building and customizing your site
10
 * Multisite configuration
11
 * Multilingual configuration
Dries Buytaert's avatar
Dries Buytaert committed
12

13
14
REQUIREMENTS AND NOTES
----------------------
Dries Buytaert's avatar
   
Dries Buytaert committed
15

16
17
Drupal requires:

18
19
- A web server with PHP support, for example:
  - Apache 2.0 (or greater) (http://httpd.apache.org/).
20
  - Nginx 1.1 (or greater) (http://nginx.com/).
21
- PHP 5.5.9 (or greater) (http://php.net/). For better security support it is
22
  recommended to update to at least 5.5.21 or 5.6.5.
23
- One of the following databases:
24
25
  - MySQL 5.5.3 (or greater) (http://www.mysql.com/).
  - MariaDB 5.5.20 (or greater) (https://mariadb.org/). MariaDB is a fully
26
    compatible drop-in replacement for MySQL.
27
  - Percona Server 5.5.8 (or greater) (http://www.percona.com/). Percona
28
    Server is a backwards-compatible replacement for MySQL.
29
30
  - PostgreSQL 8.3 (or greater) (http://www.postgresql.org/).
  - SQLite 3.4.2 (or greater) (http://www.sqlite.org/).
31

32
33
For more detailed information about Drupal requirements, including a list of
PHP extensions and configurations that are required, see "System requirements"
34
(https://www.drupal.org/requirements) in the Drupal.org online documentation.
Dries Buytaert's avatar
   
Dries Buytaert committed
35

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

40
41
42
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).
Dries Buytaert's avatar
   
Dries Buytaert committed
43

44
45
46
47
48
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
49
  files. For Clean URLs support on IIS, see "Clean URLs with IIS"
50
  (https://www.drupal.org/node/3854) in the Drupal.org online documentation.
Dries Buytaert's avatar
   
Dries Buytaert committed
51

52
53
54
55
- 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.

56
57
58
- 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.

59
60
61
62
63
64
- 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.
65

66
67
68
69
- PHP 5.5.21 provides features for improved security when used with MySQL. While
  this is not required, it is highly encouraged to use PHP 5.5.21 or 5.6.5 and
  above.

Dries Buytaert's avatar
   
Dries Buytaert committed
70
71
72
INSTALLATION
------------

73
1. Download and extract Drupal.
Dries Buytaert's avatar
   
Dries Buytaert committed
74

75
76
77
   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.
Dries Buytaert's avatar
   
Dries Buytaert committed
78

79
   To download and extract the files, on a typical Unix/Linux command line, use
80
   the following commands (assuming you want version x.y.z of Drupal in .tar.gz
81
   format):
Dries Buytaert's avatar
   
Dries Buytaert committed
82

83
84
     wget https://www.drupal.org/files/projects/drupal-x.y.z.tar.gz
     tar -zxvf drupal-x.y.z.tar.gz
Dries Buytaert's avatar
   
Dries Buytaert committed
85

86
87
88
89
   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:
90

91
     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 /path/to/your/installation
92

93
2. Create the Drupal database.
94

95
96
97
98
99
100
   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.
101

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

105
3. Run the install script.
106
107
108
109
110
111
112

   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 web site settings.
113

114
   During installation, several files and directories need to be created, which
115
116
117
118
   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.
119

120
   The most common steps you may need to perform are:
121

122
   a. Missing files directory.
123

124
125
      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
126
      directory may be changed after Drupal is installed).
127

128
129
130
131
      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:
132

133
134
135
136
137
138
139
140
        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 you can grant everyone
141
142
      (including the web server) permission to write to the sites/default
      directory with this command:
143

144
        chmod a+w sites/default
145

146
147
148
149
      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:
150

151
        chmod a+w sites/default/files
152

153
154
155
      Be sure to set the permissions for the default directory back after the
      installation is finished! (Leave the files directory writeable.)
      Sample command:
156

157
        chmod go-w sites/default
158

159
   b. Missing settings file.
160

161
162
163
164
165
166
      Drupal will try to automatically create settings.php and services.yml
      files, which are normally in the directory sites/default (to avoid
      problems when upgrading, Drupal is not packaged with this file). If
      auto-creation of either file fails, you will need to create the file
      yourself. Use the template sites/default/default.settings.php or
      sites/default/default.services.yml respectively.
167

168
      For example, on a Unix/Linux command line, you can make a copy of the
169
      default.settings.php and default.services.yml files with the commands:
170

171
        cp sites/default/default.settings.php sites/default/settings.php
172
        cp sites/default/default.services.yml sites/default/services.yml
173

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

177
        chmod a+w sites/default/settings.php
178
        chmod a+w sites/default/services.yml
179

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

183
        chmod go-w sites/default/settings.php
184
        chmod go-w sites/default/services.yml
185

186
   c. Write permissions after install.
187

188
189
190
191
      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:
192

193
        chmod go-w sites/default/settings.php
194
        chmod go-w sites/default/services.yml
195
        chmod go-w sites/default
196

197
4. Verify that the site is working.
198

199
200
201
202
   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
203
   https://www.drupal.org/getting-started/clean-urls to troubleshoot.
204

205
5. Change file system storage settings (optional).
206

207
   The files directory created in step 4 is the default file system path used to
208
209
210
   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.
211

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

214
215
216
   - 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).
217

218
219
220
   - 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).
221

222
   - You want to restrict access to uploaded files.
223

224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
   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. Navigate to Administration > Configuration > Media > File system, and
      enter the desired path. Note that if you want to use private file storage,
      you need to first enter the path for private files and save the
      configuration, and then change the "Default download method" setting and
      save again.
239
240
241
242
243

   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.
244

245
6. Revoke documentation file permissions (optional).
246

247
248
249
   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
250
251
   this optional security measure, from a Unix/Linux command line you can use
   the following command:
252

253
     chmod a-r CHANGELOG.txt
254

255
256
257
   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
258
259
   name of each file for CHANGELOG.txt in the example.

260
   For more information on setting file permissions, see "Modifying Linux,
261
262
263
   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.
264

265
7. Set up independent "cron" maintenance jobs.
266

267
268
269
270
271
272
   Many Drupal modules have tasks that must be run periodically, including the
   Search module (building and updating the index used for keyword searching),
   the Aggregator module (retrieving feeds from other sites), 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.
273

274
275
276
277
   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.
278

279
280
   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
281
   process to visit the page /cron on your site, which executes the cron
282
   tasks.
283

284
   The URL of the cron page requires a "cron key" to protect against
285
286
287
288
   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.
Dries Buytaert's avatar
   
Dries Buytaert committed
289

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

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

296
297
298
   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.
Dries Buytaert's avatar
   
Dries Buytaert committed
299

300
   More information about cron maintenance tasks is available at
301
302
303
   https://www.drupal.org/cron, 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.)
Dries Buytaert's avatar
   
Dries Buytaert committed
304

305
306
307
308
309
310
311
312
313
314
315
316
317
318
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).

319
320
BUILDING AND CUSTOMIZING YOUR SITE
----------------------------------
Dries Buytaert's avatar
   
Dries Buytaert committed
321

322
323
324
325
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
326
327
more at https://www.drupal.org/project/project_module and
https://www.drupal.org/project/project_theme
328

329
Do not mix downloaded or custom modules and themes with Drupal's core modules
330
331
332
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
333
334
installation, you can also place modules and themes in the site-specific
directories -- see the Multisite Configuration section, below.
335

336
Never edit Drupal's core modules and themes; instead, use the hooks available in
337
the Drupal API. To modify the behavior of Drupal, develop a module as described
338
339
340
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/documentation/theme
341
342
343
344
345
346
347

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

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

348
349
350
351
352
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

353
Additional site configurations are created in subdirectories within the 'sites'
354
355
directory. Each subdirectory must have a 'settings.php' file, which specifies
the configuration settings. The easiest way to create additional sites is to
356
357
358
359
360
361
362
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/defaults.settings.php sites/example.com/settings.php
363
364

Sites do not have to have a different domain. You can also use subdomains and
365
366
367
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:
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392

  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
393
addition to those installed in the standard 'modules' and 'themes' directories.
394
395
396
397
398
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:

399
400
401
402
  sites/sub.example.com/
    settings.php
    themes/custom_theme
    modules/custom_module
403

404
405
For more information about multiple virtual hosts or the configuration
settings, consult https://www.drupal.org/documentation/install/multi-site
406
407

For more information on configuring Drupal's file system path in a multisite
408
configuration, see step 6 above.
Dries Buytaert's avatar
   
Dries Buytaert committed
409

410
411
412
413
414
415
MULTILINGUAL CONFIGURATION
--------------------------

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

416
417
For detailed instructions, visit
https://www.drupal.org/documentation/multilingual