Issue #1371484 by catch, langworthy, makara, ArtistConk: Fixed Private properties...
[project/drupal.git] / INSTALL.txt
CommitLineData
25ebb5e9 1
a666c7da
DB
2CONTENTS OF THIS FILE
3---------------------
4
a956c407
DB
5 * Requirements and notes
6 * Optional server requirements
a666c7da 7 * Installation
a956c407 8 * Building and customizing your site
f0979758
AB
9 * Multisite configuration
10 * More information
a666c7da 11
a956c407
DB
12REQUIREMENTS AND NOTES
13----------------------
2cd22cfe 14
67502395
DB
15Drupal requires:
16
4f2d6969 17- A web server. Apache (version 2.0 or greater) is recommended.
a956c407 18- PHP 5.2.4 (or greater) (http://www.php.net/).
4f2d6969
DB
19- One of the following databases:
20 - MySQL 5.0.15 (or greater) (http://www.mysql.com/).
21 - MariaDB 5.1.44 (or greater) (http://mariadb.org/). MariaDB is a fully
22 compatible drop-in replacement for MySQL.
23 - PostgreSQL 8.3 (or greater) (http://www.postgresql.org/).
24 - SQLite 3.4.2 (or greater) (http://www.sqlite.org/).
6ce212e4 25
2fc31c1f
DB
26For more detailed information about Drupal requirements, including a list of
27PHP extensions and configurations that are required, see "System requirements"
7c45d5b2 28(http://drupal.org/requirements) in the Drupal.org online documentation.
2cd22cfe 29
a956c407
DB
30For detailed information on how to configure a test server environment using a
31variety of operating systems and web servers, see "Local server setup"
7c45d5b2 32(http://drupal.org/node/157602) in the Drupal.org online documentation.
2cd22cfe 33
a956c407
DB
34Note that all directories mentioned in this document are always relative to the
35directory of your Drupal installation, and commands are meant to be run from
36this directory (except for the initial commands that create that directory).
2cd22cfe 37
a956c407
DB
38OPTIONAL SERVER REQUIREMENTS
39----------------------------
40
41- If you want to use Drupal's "Clean URLs" feature on an Apache web server, you
42 will need the mod_rewrite module and the ability to use local .htaccess
7c45d5b2
DB
43 files. For Clean URLs support on IIS, see "Clean URLs with IIS"
44 (http://drupal.org/node/3854) in the Drupal.org online documentation.
2cd22cfe 45
a956c407
DB
46- If you plan to use XML-based services such as RSS aggregation, you will need
47 PHP's XML extension. This extension is enabled by default on most PHP
48 installations.
49
563c673e
DB
50- To serve gzip compressed CSS and JS files on an Apache web server, you will
51 need the mod_headers module and the ability to use local .htaccess files.
52
a956c407
DB
53- Some Drupal functionality (e.g., checking whether Drupal and contributed
54 modules need updates, RSS aggregation, etc.) require that the web server be
55 able to go out to the web and download information. If you want to use this
56 functionality, you need to verify that your hosting provider or server
57 configuration allows the web server to initiate outbound connections. Most web
58 hosting setups allow this.
e6a4b82e 59
2cd22cfe
DB
60INSTALLATION
61------------
62
a956c407 631. Download and extract Drupal.
2cd22cfe 64
a956c407 65 You can obtain the latest Drupal release from http://drupal.org -- the files
6a69b824
DB
66 are available in .tar.gz and .zip formats and can be extracted using most
67 compression tools.
2cd22cfe 68
a956c407 69 To download and extract the files, on a typical Unix/Linux command line, use
7c45d5b2
DB
70 the following commands (assuming you want version x.y of Drupal in .tar.gz
71 format):
2cd22cfe 72
a956c407
DB
73 wget http://drupal.org/files/projects/drupal-x.y.tar.gz
74 tar -zxvf drupal-x.y.tar.gz
2cd22cfe 75
a956c407
DB
76 This will create a new directory drupal-x.y/ containing all Drupal files and
77 directories. Then, to move the contents of that directory into a directory
78 within your web server's document root or your public HTML directory,
79 continue with this command:
80
81 mv drupal-x.y/* drupal-x.y/.htaccess /path/to/your/installation
82
832. Optionally, download a translation.
c389c905 84
18a68728 85 By default, Drupal is installed in English, and further languages may be
a956c407
DB
86 installed later. If you prefer to install Drupal in another language
87 initially:
18a68728 88
a956c407 89 - Download a translation file for the correct Drupal version and language
7c45d5b2 90 from the translation server: http://localize.drupal.org/translate/downloads
18a68728 91
52ba5cc8 92 - Place the file into your installation profile's translations
a956c407
DB
93 directory. For instance, if you are using the Standard install profile,
94 move the .po file into the directory:
18a68728 95
a956c407 96 profiles/standard/translations/
18a68728 97
a956c407 98 For detailed instructions, visit http://drupal.org/localize
18a68728 99
a956c407 1003. Create the Drupal database.
19c9d7f5 101
a956c407
DB
102 Because Drupal stores all site information in a database, you must create
103 this database in order to install Drupal, and grant Drupal certain database
104 privileges (such as the ability to create tables). For details, consult
105 INSTALL.mysql.txt, INSTALL.pgsql.txt, or INSTALL.sqlite.txt. You may also
106 need to consult your web hosting provider for instructions specific to your
107 web host.
19c9d7f5 108
a956c407
DB
109 Take note of the username, password, database name, and hostname as you
110 create the database. You will enter this information during the install.
d8aacc5d 111
577fdd21
AB
1124. Run the install script.
113
114 To run the install script, point your browser to the base URL of your
115 website (e.g., http://www.example.com).
116
117 You will be guided through several screens to set up the database, add the
118 site maintenance account (the first user, also known as user/1), and provide
119 basic web site settings.
d8aacc5d 120
a956c407 121 During installation, several files and directories need to be created, which
577fdd21
AB
122 the install script will try to do automatically. However, on some hosting
123 environments, manual steps are required, and the install script will tell
124 you that it cannot proceed until you fix certain issues. This is normal and
125 does not indicate a problem with your server.
d8aacc5d 126
577fdd21 127 The most common steps you may need to perform are:
d8aacc5d 128
577fdd21 129 a. Missing files directory.
c389c905 130
577fdd21
AB
131 The install script will attempt to create a file storage directory in
132 the default location at sites/default/files (the location of the files
133 directory may be changed after Drupal is installed).
2934e783 134
577fdd21
AB
135 If auto-creation fails, you can make it work by changing permissions on
136 the sites/default directory so that the web server can create the files
137 directory within it for you. (If you are creating a multisite
138 installation, substitute the correct sites directory for sites/default;
139 see the Multisite Configuration section of this file, below.)
6ce212e4 140
577fdd21
AB
141 For example, on a Unix/Linux command line, you can grant everyone
142 (including the web server) permission to write to the sites/default
143 directory with this command:
6ce212e4 144
577fdd21 145 chmod a+w sites/default
6ce212e4 146
577fdd21
AB
147 Be sure to set the permissions back after the installation is finished!
148 Sample command:
6ce212e4 149
577fdd21
AB
150 chmod go-w sites/default
151
152 Alternatively, instead of allowing the web server to create the files
153 directory for you as described above, you can create it yourself. Sample
154 commands from a Unix/Linux command line:
155
156 mkdir sites/default/files
157 chmod a+w sites/default/files
6ce212e4 158
577fdd21 159 b. Missing settings file.
c389c905 160
a956c407
DB
161 Drupal will try to automatically create a settings.php configuration file,
162 which is normally in the directory sites/default (to avoid problems when
163 upgrading, Drupal is not packaged with this file). If auto-creation fails,
577fdd21
AB
164 you will need to create this file yourself, using the file
165 sites/default/default.settings.php as a template.
19c9d7f5 166
a956c407
DB
167 For example, on a Unix/Linux command line, you can make a copy of the
168 default.settings.php file with the command:
9b2bf38e 169
a956c407 170 cp sites/default/default.settings.php sites/default/settings.php
9b2bf38e 171
a956c407
DB
172 Next, grant write privileges to the file to everyone (including the web
173 server) with the command:
d8aacc5d 174
a956c407 175 chmod a+w sites/default/settings.php
d8aacc5d 176
a956c407
DB
177 Be sure to set the permissions back after the installation is finished!
178 Sample command:
3942da75 179
a956c407 180 chmod go-w sites/default/settings.php
6ce212e4 181
a956c407 182 c. Write permissions after install.
8a364836 183
a956c407
DB
184 The install script will attempt to write-protect the settings.php file and
185 the sites/default directory after saving your configuration. If this
186 fails, you will be notified, and you can do it manually. Sample commands
187 from a Unix/Linux command line:
8a364836 188
a956c407
DB
189 chmod go-w sites/default/settings.php
190 chmod go-w sites/default
8a364836 191
577fdd21 1925. Verify that the site is working.
8a364836 193
a956c407
DB
194 When the install script finishes, you will be logged in with the site
195 maintenance account on a "Welcome" page. If the default Drupal theme is not
196 displaying properly and links on the page result in "Page Not Found" errors,
197 you may be experiencing problems with clean URLs. Visit
198 http://drupal.org/getting-started/clean-urls to troubleshoot.
8a364836 199
577fdd21 2006. Change file system storage settings (optional).
8ebc345b 201
577fdd21 202 The files directory created in step 4 is the default file system path used to
a956c407
DB
203 store all uploaded files, as well as some temporary files created by
204 Drupal. After installation, you can modify the file system path to store
205 uploaded files in a different location.
8a364836 206
a956c407 207 It is not necessary to modify this path, but you may wish to change it if:
8a364836 208
a956c407
DB
209 - Your site runs multiple Drupal installations from a single codebase (modify
210 the file system path of each installation to a different directory so that
211 uploads do not overlap between installations).
8a364836 212
a956c407
DB
213 - Your site runs on a number of web servers behind a load balancer or reverse
214 proxy (modify the file system path on each server to point to a shared file
215 repository).
8a364836 216
a956c407 217 - You want to restrict access to uploaded files.
8a364836 218
a956c407
DB
219 To modify the file system path:
220
221 a. Ensure that the new location for the path exists and is writable by the
222 web server. For example, to create a new directory named uploads and grant
223 write permissions, use the following commands on a Unix/Linux command
224 line:
225
226 mkdir uploads
227 chmod a+w uploads
228
229 b. Navigate to Administration > Configuration > Media > File system, and
230 enter the desired path. Note that if you want to use private file storage,
231 you need to first enter the path for private files and save the
232 configuration, and then change the "Default download method" setting and
233 save again.
8a364836
H
234
235 Changing the file system path after files have been uploaded may cause
236 unexpected problems on an existing site. If you modify the file system path
237 on an existing site, remember to copy all files from the original location
238 to the new location.
b8a1eab1 239
577fdd21 2407. Revoke documentation file permissions (optional).
a956c407 241
cdbcbac8
H
242 Some administrators suggest making the documentation files, especially
243 CHANGELOG.txt, non-readable so that the exact version of Drupal you are
244 running is slightly more difficult to determine. If you wish to implement
a956c407
DB
245 this optional security measure, from a Unix/Linux command line you can use
246 the following command:
cdbcbac8 247
a956c407 248 chmod a-r CHANGELOG.txt
cdbcbac8 249
a956c407
DB
250 Note that the example only affects CHANGELOG.txt. To completely hide all
251 documentation files from public view, repeat this command for each of the
252 Drupal documentation files in the installation directory, substituting the
cdbcbac8
H
253 name of each file for CHANGELOG.txt in the example.
254
a956c407
DB
255 For more information on setting file permissions, see "Modifying Linux,
256 Unix, and Mac file permissions" (http://drupal.org/node/202483) or
257 "Modifying Windows file permissions" (http://drupal.org/node/202491) in the
7c45d5b2 258 Drupal.org online documentation.
6ce212e4 259
577fdd21 2608. Set up independent "cron" maintenance jobs.
4c028a19 261
a956c407
DB
262 Many Drupal modules have tasks that must be run periodically, including the
263 Search module (building and updating the index used for keyword searching),
264 the Aggregator module (retrieving feeds from other sites), and the System
265 module (performing routine maintenance and pruning of database tables). These
266 tasks are known as "cron maintenance tasks", named after the Unix/Linux
267 "cron" utility.
4c028a19 268
a956c407
DB
269 When you install Drupal, its built-in cron feature is enabled, which
270 automatically runs the cron tasks periodically, triggered by people visiting
271 pages of your site. You can configure the built-in cron feature by navigating
272 to Administration > Configuration > System > Cron.
4c028a19 273
a956c407
DB
274 It is also possible to run the cron tasks independent of site visits; this is
275 recommended for most sites. To do this, you will need to set up an automated
276 process to visit the page cron.php on your site, which executes the cron
277 tasks.
6ce212e4 278
a956c407
DB
279 The URL of the cron.php page requires a "cron key" to protect against
280 unauthorized access. Your site's cron key is automatically generated during
281 installation and is specific to your site. The full URL of the page, with the
282 cron key, is available in the "Cron maintenance tasks" section of the Status
283 report page at Administration > Reports > Status report.
2cd22cfe 284
a956c407
DB
285 As an example for how to set up this automated process, you can use the
286 crontab utility on Unix/Linux systems. The following crontab line uses the
287 wget command to visit the cron.php page, and runs each hour, on the hour:
45097b78 288
a956c407 289 0 * * * * wget -O - -q -t 1 http://example.com/cron.php?cron_key=YOURKEY
45097b78 290
a956c407 291 Replace the text "http://example.com/cron.php?cron_key=YOURKEY" in the
45097b78
DB
292 example with the full URL displayed under "Cron maintenance tasks" on the
293 "Status report" page.
2cd22cfe 294
a956c407
DB
295 More information about cron maintenance tasks is available at
296 http://drupal.org/cron, and sample cron shell scripts can be found in the
297 scripts/ directory. (Note that these scripts must be customized like the
298 above example, to add your site-specific cron key and domain name.)
2cd22cfe 299
31f16e74
DB
300BUILDING AND CUSTOMIZING YOUR SITE
301----------------------------------
2cd22cfe 302
a956c407
DB
303A new installation of Drupal defaults to a very basic configuration. To extend
304your site, you use "modules" and "themes". A module is a plugin that adds
305functionality to Drupal, while a theme changes the look of your site. The core
306of Drupal provides several optional modules and themes, and you can download
307more at http://drupal.org/project/modules and http://drupal.org/project/themes
31f16e74 308
a956c407
DB
309Do not mix downloaded or custom modules and themes with Drupal's core modules
310and themes. Drupal's modules and themes are located in the top-level modules and
311themes directories, while the modules and themes you add to Drupal are normally
312placed in the sites/all/modules and sites/all/themes directories. If you run a
313multisite installation, you can also place modules and themes in the
314site-specific directories -- see the Multisite Configuration section, below.
6ce212e4 315
a956c407 316Never edit Drupal's core modules and themes; instead, use the hooks available in
7c45d5b2 317the Drupal API. To modify the behavior of Drupal, develop a module as described
a956c407
DB
318at http://drupal.org/developing/modules. To modify the look of Drupal, create a
319subtheme as described at http://drupal.org/node/225125, or a completely new
320theme as described at http://drupal.org/documentation/theme
6ce212e4 321
6ce212e4
DB
322MULTISITE CONFIGURATION
323-----------------------
324
325A single Drupal installation can host several Drupal-powered sites, each with
326its own individual configuration.
327
328Additional site configurations are created in subdirectories within the 'sites'
a956c407
DB
329directory. Each subdirectory must have a 'settings.php' file, which specifies
330the configuration settings. The easiest way to create additional sites is to
7c45d5b2
DB
331copy the 'default' directory and modify the 'settings.php' file as appropriate.
332The new directory name is constructed from the site's URL. The configuration for
333www.example.com could be in 'sites/example.com/settings.php' (note that 'www.'
334should be omitted if users can access your site at http://example.com/).
6ce212e4
DB
335
336Sites do not have to have a different domain. You can also use subdomains and
7c45d5b2
DB
337subdirectories for Drupal sites. For example, example.com, sub.example.com, and
338sub.example.com/site3 can all be defined as independent Drupal sites. The setup
339for a configuration such as this would look like the following:
6ce212e4
DB
340
341 sites/default/settings.php
342 sites/example.com/settings.php
343 sites/sub.example.com/settings.php
344 sites/sub.example.com.site3/settings.php
345
346When searching for a site configuration (for example www.sub.example.com/site3),
347Drupal will search for configuration files in the following order, using the
348first configuration it finds:
349
350 sites/www.sub.example.com.site3/settings.php
351 sites/sub.example.com.site3/settings.php
352 sites/example.com.site3/settings.php
353 sites/www.sub.example.com/settings.php
354 sites/sub.example.com/settings.php
355 sites/example.com/settings.php
356 sites/default/settings.php
357
358If you are installing on a non-standard port, the port number is treated as the
359deepest subdomain. For example: http://www.example.com:8080/ could be loaded
360from sites/8080.www.example.com/. The port number will be removed according to
361the pattern above if no port-specific configuration is found, just like a real
362subdomain.
363
364Each site configuration can have its own site-specific modules and themes in
19c9d7f5 365addition to those installed in the standard 'modules' and 'themes' directories.
6ce212e4
DB
366To use site-specific modules or themes, simply create a 'modules' or 'themes'
367directory within the site configuration directory. For example, if
368sub.example.com has a custom theme and a custom module that should not be
369accessible to other sites, the setup would look like this:
370
a956c407
DB
371 sites/sub.example.com/
372 settings.php
373 themes/custom_theme
374 modules/custom_module
6ce212e4
DB
375
376NOTE: for more information about multiple virtual hosts or the configuration
a956c407
DB
377settings, consult http://drupal.org/getting-started/6/install/multi-site
378
379For more information on configuring Drupal's file system path in a multisite
577fdd21 380configuration, see step 6 above.
2cd22cfe
DB
381
382MORE INFORMATION
383----------------
384
7c45d5b2
DB
385- See the Drupal.org online documentation:
386 http://drupal.org/documentation
8a364836 387
7c45d5b2
DB
388- For a list of security announcements, see the "Security advisories" page at
389 http://drupal.org/security (available as an RSS feed). This page also
aea7c252 390 describes how to subscribe to these announcements via e-mail.
7589d344 391
a956c407
DB
392- For information about the Drupal security process, or to find out how to
393 report a potential security issue to the Drupal security team, see the
394 "Security team" page at http://drupal.org/security-team
aea7c252 395
a956c407
DB
396- For information about the wide range of available support options, visit
397 http://drupal.org and click on Community and Support in the top or bottom
398 navigation.