Mercurial > defr > drupal > core

annotate INSTALL.txt @ 20:e3d20ebd63d1 tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added tag 6.9 for changeset 3edae6ecd6c6
author Franck Deroche <franck@defr.org>
date Thu, 15 Jan 2009 10:16:10 +0100
parents fff6d4c8c043
children
rev   line source
webmaster@7 1 // $Id: INSTALL.txt,v 1.61.2.4 2008/07/09 19:15:59 goba Exp $
webmaster@1 2
webmaster@1 3 CONTENTS OF THIS FILE
webmaster@1 4 ---------------------
webmaster@1 5
webmaster@1 6 * Requirements
webmaster@1 7 * Optional requirements
webmaster@1 8 * Installation
webmaster@1 9 * Drupal administration
webmaster@1 10 * Customizing your theme(s)
webmaster@1 11 * Multisite Configuration
webmaster@1 12 * More Information
webmaster@1 13
webmaster@1 14 REQUIREMENTS
webmaster@1 15 ------------
webmaster@1 16
webmaster@1 17 Drupal requires a web server, PHP 4 (4.3.5 or greater) or PHP 5
webmaster@1 18 (http://www.php.net/) and either MySQL (http://www.mysql.com/) or PostgreSQL
webmaster@1 19 (http://www.postgresql.org/). The Apache web server and MySQL database are
webmaster@1 20 recommended; other web server and database combinations such as IIS and
webmaster@1 21 PostgreSQL have been tested to a lesser extent. When using MySQL, version 4.1.1
webmaster@1 22 or greater is recommended to assure you can safely transfer the database.
webmaster@1 23
webmaster@1 24 For more detailed information about Drupal requirements, see "Requirements"
webmaster@1 25 (http://drupal.org/requirements) in the Drupal handbook.
webmaster@1 26
webmaster@1 27 For detailed information on how to configure a test server environment using
webmaster@1 28 a variety of operating systems and web servers, see "Local server setup"
webmaster@1 29 (http://drupal.org/node/157602) in the Drupal handbook.
webmaster@1 30
webmaster@7 31 OPTIONAL TASKS
webmaster@7 32 --------------
webmaster@1 33
webmaster@1 34 - To use XML-based services such as the Blogger API and RSS syndication,
webmaster@1 35 you will need PHP's XML extension. This extension is enabled by default.
webmaster@1 36
webmaster@1 37 - To use Drupal's "Clean URLs" feature on an Apache web server, you will need
webmaster@1 38 the mod_rewrite module and the ability to use local .htaccess files. For
webmaster@1 39 Clean URLs support on IIS, see "Using Clean URLs with IIS"
webmaster@1 40 (http://drupal.org/node/3854) in the Drupal handbook.
webmaster@1 41
webmaster@1 42 - Various Drupal features require that the web server process (for
webmaster@1 43 example, httpd) be able to initiate outbound connections. This is usually
webmaster@1 44 possible, but some hosting providers or server configurations forbid such
webmaster@1 45 connections. The features that depend on this functionality include the
webmaster@1 46 integrated "Update status" module (which downloads information about
webmaster@1 47 available updates of Drupal core and any installed contributed modules and
webmaster@1 48 themes), the ability to log in via OpenID, fetching aggregator feeds, or
webmaster@1 49 other network-dependent services.
webmaster@1 50
webmaster@1 51
webmaster@1 52 INSTALLATION
webmaster@1 53 ------------
webmaster@1 54
webmaster@1 55 1. DOWNLOAD DRUPAL AND OPTIONALLY A TRANSLATION
webmaster@1 56
webmaster@1 57 You can obtain the latest Drupal release from http://drupal.org/. The files
webmaster@1 58 are in .tar.gz format and can be extracted using most compression tools. On a
webmaster@1 59 typical Unix command line, use:
webmaster@1 60
webmaster@1 61 wget http://drupal.org/files/projects/drupal-x.x.tar.gz
webmaster@1 62 tar -zxvf drupal-x.x.tar.gz
webmaster@1 63
webmaster@1 64 This will create a new directory drupal-x.x/ containing all Drupal files
webmaster@1 65 and directories. Move the contents of that directory into a directory within
webmaster@1 66 your web server's document root or your public HTML directory:
webmaster@1 67
webmaster@1 68 mv drupal-x.x/* drupal-x.x/.htaccess /var/www/html
webmaster@1 69
webmaster@1 70 If you would like to have the default English interface translated to a
webmaster@1 71 different language, we have good news. You can install and use Drupal in
webmaster@1 72 other languages from the start. Check whether a released package of the
webmaster@1 73 language desired is available for this Drupal version at
webmaster@1 74 http://drupal.org/project/translations and download the package. Extract
webmaster@1 75 the contents to the same directory where you extracted Drupal into.
webmaster@1 76
webmaster@7 77 2. CREATE THE CONFIGURATION FILE AND GRANT WRITE PERMISSIONS
webmaster@1 78
webmaster@1 79 Drupal comes with a default.settings.php file in the sites/default
webmaster@7 80 directory. The installer uses this file as a template to create your
webmaster@7 81 settings file using the details you provide through the install process.
webmaster@7 82 To avoid problems when upgrading, Drupal is not packaged with an actual
webmaster@7 83 settings file. You must create a file named settings.php. You may do so
webmaster@7 84 by making a copy of default.settings.php (or create an empty file with
webmaster@7 85 this name in the same directory). For example, (from the installation
webmaster@7 86 directory) make a copy of the default.settings.php file with the command:
webmaster@7 87
webmaster@7 88 cp sites/default/default.settings.php sites/default/settings.php
webmaster@7 89
webmaster@7 90 Next, give the web server write privileges to the sites/default/settings.php
webmaster@7 91 file with the command (from the installation directory):
webmaster@7 92
webmaster@7 93 chmod o+w sites/default/settings.php
webmaster@7 94
webmaster@7 95 So that the files directory can be created automatically, give the web server
webmaster@7 96 write privileges to the sites/default directory with the command (from the
webmaster@7 97 installation directory):
webmaster@1 98
webmaster@1 99 chmod o+w sites/default
webmaster@1 100
webmaster@1 101 3. CREATE THE DRUPAL DATABASE
webmaster@1 102
webmaster@1 103 Drupal requires access to a database in order to be installed. Your database
webmaster@1 104 user will need sufficient privileges to run Drupal. Additional information
webmaster@1 105 about privileges, and instructions to create a database using the command
webmaster@1 106 line are available in INSTALL.mysql.txt (for MySQL) or INSTALL.pgsql.txt
webmaster@1 107 (for PostgreSQL).
webmaster@1 108
webmaster@1 109 To create a database using PHPMyAdmin or a web-based control panel consult
webmaster@1 110 the documentation or ask your webhost service provider.
webmaster@1 111
webmaster@1 112 Take note of the username, password, database name and hostname as you
webmaster@1 113 create the database. You will enter these items in the install script.
webmaster@1 114
webmaster@1 115 4. RUN THE INSTALL SCRIPT
webmaster@1 116
webmaster@1 117 To run the install script point your browser to the base URL of your website
webmaster@1 118 (e.g., http://www.example.com).
webmaster@1 119
webmaster@1 120 You will be guided through several screens to set up the database,
webmaster@1 121 create tables, add the first user account and provide basic web
webmaster@1 122 site settings.
webmaster@1 123
webmaster@1 124 The install script will attempt to create a files storage directory
webmaster@1 125 in the default location at sites/default/files (the location of the
webmaster@1 126 files directory may be changed after Drupal is installed). In some
webmaster@1 127 cases, you may need to create the directory and modify its permissions
webmaster@1 128 manually. Use the following commands (from the installation directory)
webmaster@1 129 to create the files directory and grant the web server write privileges to it:
webmaster@1 130
webmaster@1 131 mkdir sites/default/files
webmaster@1 132 chmod o+w sites/default/files
webmaster@1 133
webmaster@7 134 The install script will attempt to write-protect the settings.php file and
webmaster@7 135 the sites/default directory after saving your configuration. However, you
webmaster@7 136 may need to manually write-protect them using the commands (from the
webmaster@7 137 installation directory):
webmaster@7 138
webmaster@7 139 chmod a-w sites/default/settings.php
webmaster@7 140 chmod a-w sites/default
webmaster@7 141
webmaster@7 142 If you make manual changes to the file later, be sure to protect it again
webmaster@7 143 after making your modifications. Failure to remove write permissions to that
webmaster@7 144 file is a security risk. Although the default location for the settings.php
webmaster@1 145 file is at sites/default/settings.php, it may be in another location
webmaster@1 146 if you use the multi-site setup, as explained below.
webmaster@1 147
webmaster@1 148 5. CONFIGURE DRUPAL
webmaster@1 149
webmaster@1 150 When the install script succeeds, you will be directed to the "Welcome"
webmaster@1 151 page, and you will be logged in as the administrator already. Proceed with
webmaster@1 152 the initial configuration steps suggested on the "Welcome" page.
webmaster@1 153
webmaster@1 154 If the default Drupal theme is not displaying properly and links on the page
webmaster@1 155 result in "Page Not Found" errors, try manually setting the $base_url variable
webmaster@1 156 in the settings.php file if not already set. It's currently known that servers
webmaster@1 157 running FastCGI can run into problems if the $base_url variable is left
webmaster@1 158 commented out (see http://bugs.php.net/bug.php?id=19656).
webmaster@1 159
webmaster@1 160 6. REVIEW FILE SYSTEM STORAGE SETTINGS AND FILE PERMISSIONS
webmaster@1 161
webmaster@1 162 The files directory created in step 4 is the default file system path used
webmaster@1 163 to store all uploaded files, as well as some temporary files created by Drupal.
webmaster@1 164 After installation, the settings for the file system path may be modified
webmaster@1 165 to store uploaded files in a different location.
webmaster@1 166
webmaster@1 167 It is not necessary to modify this path, but you may wish to change it if:
webmaster@1 168
webmaster@1 169 * your site runs multiple Drupal installations from a single codebase
webmaster@1 170 (modify the file system path of each installation to a different
webmaster@1 171 directory so that uploads do not overlap between installations); or,
webmaster@1 172
webmaster@1 173 * your site runs a number of web server front-ends behind a load
webmaster@1 174 balancer or reverse proxy (modify the file system path on each
webmaster@1 175 server to point to a shared file repository).
webmaster@1 176
webmaster@1 177 To modify the file system path:
webmaster@1 178
webmaster@1 179 * Ensure that the new location for the path exists or create it if
webmaster@1 180 necessary. To create a new directory named uploads, for example,
webmaster@1 181 use the following command from a shell or system prompt (while in
webmaster@1 182 the installation directory):
webmaster@1 183
webmaster@1 184 mkdir uploads
webmaster@1 185
webmaster@1 186 * Ensure that the new location for the path is writable by the web
webmaster@1 187 server process. To grant write permissions for a directory named
webmaster@1 188 uploads, you may need to use the following command from a shell
webmaster@1 189 or system prompt (while in the installation directory):
webmaster@1 190
webmaster@1 191 chmod o+w uploads
webmaster@1 192
webmaster@1 193 * Access the file system path settings in Drupal by selecting these
webmaster@1 194 menu items from the Navigation menu:
webmaster@1 195
webmaster@1 196 Administer > Site configuration > File system
webmaster@1 197
webmaster@1 198 Enter the path to the new location (e.g.: uploads) at the File
webmaster@1 199 System Path prompt.
webmaster@1 200
webmaster@1 201 Changing the file system path after files have been uploaded may cause
webmaster@1 202 unexpected problems on an existing site. If you modify the file system path
webmaster@1 203 on an existing site, remember to copy all files from the original location
webmaster@1 204 to the new location.
webmaster@7 205
webmaster@1 206 Some administrators suggest making the documentation files, especially
webmaster@1 207 CHANGELOG.txt, non-readable so that the exact version of Drupal you are
webmaster@1 208 running is slightly more difficult to determine. If you wish to implement
webmaster@1 209 this optional security measure, use the following command from a shell or
webmaster@1 210 system prompt (while in the installation directory):
webmaster@1 211
webmaster@1 212 chmod a-r CHANGELOG.txt
webmaster@1 213
webmaster@1 214 Note that the example only affects CHANGELOG.txt. To completely hide
webmaster@1 215 all documentation files from public view, repeat this command for each of
webmaster@1 216 the Drupal documentation files in the installation directory, substituting the
webmaster@1 217 name of each file for CHANGELOG.txt in the example.
webmaster@1 218
webmaster@1 219 For more information on setting file permissions, see "Modifying Linux, Unix,
webmaster@1 220 and Mac file permissions" (http://drupal.org/node/202483) or "Modifying
webmaster@1 221 Windows file permissions" (http://drupal.org/node/202491) in the online
webmaster@1 222 handbook.
webmaster@1 223
webmaster@1 224 7. CRON MAINTENANCE TASKS
webmaster@1 225
webmaster@1 226 Many Drupal modules have periodic tasks that must be triggered by a cron
webmaster@1 227 maintenance task, including search module (to build and update the index
webmaster@1 228 used for keyword searching), aggregator module (to retrieve feeds from other
webmaster@1 229 sites), ping module (to notify other sites about new or updated content), and
webmaster@1 230 system module (to perform routine maintenance and pruning on system tables).
webmaster@1 231 To activate these tasks, call the cron page by visiting
webmaster@1 232 http://www.example.com/cron.php, which, in turn, executes tasks on behalf
webmaster@1 233 of installed modules.
webmaster@1 234
webmaster@1 235 Most systems support the crontab utility for scheduling tasks like this. The
webmaster@1 236 following example crontab line will activate the cron tasks automatically on
webmaster@1 237 the hour:
webmaster@1 238
webmaster@1 239 0 * * * * wget -O - -q -t 1 http://www.example.com/cron.php
webmaster@1 240
webmaster@1 241 More information about cron maintenance tasks are available in the help pages
webmaster@1 242 and in Drupal's online handbook at http://drupal.org/cron. Example scripts can
webmaster@1 243 be found in the scripts/ directory.
webmaster@1 244
webmaster@1 245 DRUPAL ADMINISTRATION
webmaster@1 246 ---------------------
webmaster@1 247
webmaster@1 248 A new installation of Drupal defaults to a very basic configuration with only a
webmaster@1 249 few active modules and minimal user access rights.
webmaster@1 250
webmaster@1 251 Use your administration panel to enable and configure services. For example:
webmaster@1 252
webmaster@1 253 General Settings Administer > Site configuration > Site information
webmaster@1 254 Enable Modules Administer > Site building > Modules
webmaster@1 255 Configure Themes Administer > Site building > Themes
webmaster@1 256 Set User Permissions Administer > User management > Permissions
webmaster@1 257
webmaster@1 258 For more information on configuration options, read the instructions which
webmaster@1 259 accompany the different configuration settings and consult the various help
webmaster@1 260 pages available in the administration panel.
webmaster@1 261
webmaster@1 262 Community-contributed modules and themes are available at http://drupal.org/.
webmaster@1 263
webmaster@1 264 CUSTOMIZING YOUR THEME(S)
webmaster@1 265 -------------------------
webmaster@1 266
webmaster@1 267 Now that your installation is running, you will want to customize the look of
webmaster@1 268 your site. Several sample themes are included and more can be downloaded from
webmaster@1 269 drupal.org.
webmaster@1 270
webmaster@1 271 Simple customization of your theme can be done using only CSS. Further changes
webmaster@1 272 require understanding the phptemplate engine that is part of Drupal. See
webmaster@1 273 http://drupal.org/handbook/customization to find out more.
webmaster@1 274
webmaster@1 275 MULTISITE CONFIGURATION
webmaster@1 276 -----------------------
webmaster@1 277
webmaster@1 278 A single Drupal installation can host several Drupal-powered sites, each with
webmaster@1 279 its own individual configuration.
webmaster@1 280
webmaster@1 281 Additional site configurations are created in subdirectories within the 'sites'
webmaster@1 282 directory. Each subdirectory must have a 'settings.php' file which specifies the
webmaster@1 283 configuration settings. The easiest way to create additional sites is to copy
webmaster@1 284 the 'default' directory and modify the 'settings.php' file as appropriate. The
webmaster@1 285 new directory name is constructed from the site's URL. The configuration for
webmaster@1 286 www.example.com could be in 'sites/example.com/settings.php' (note that 'www.'
webmaster@1 287 should be omitted if users can access your site at http://example.com/).
webmaster@1 288
webmaster@1 289 Sites do not have to have a different domain. You can also use subdomains and
webmaster@1 290 subdirectories for Drupal sites. For example, example.com, sub.example.com,
webmaster@1 291 and sub.example.com/site3 can all be defined as independent Drupal sites. The
webmaster@1 292 setup for a configuration such as this would look like the following:
webmaster@1 293
webmaster@1 294 sites/default/settings.php
webmaster@1 295 sites/example.com/settings.php
webmaster@1 296 sites/sub.example.com/settings.php
webmaster@1 297 sites/sub.example.com.site3/settings.php
webmaster@1 298
webmaster@1 299 When searching for a site configuration (for example www.sub.example.com/site3),
webmaster@1 300 Drupal will search for configuration files in the following order, using the
webmaster@1 301 first configuration it finds:
webmaster@1 302
webmaster@1 303 sites/www.sub.example.com.site3/settings.php
webmaster@1 304 sites/sub.example.com.site3/settings.php
webmaster@1 305 sites/example.com.site3/settings.php
webmaster@1 306 sites/www.sub.example.com/settings.php
webmaster@1 307 sites/sub.example.com/settings.php
webmaster@1 308 sites/example.com/settings.php
webmaster@1 309 sites/default/settings.php
webmaster@1 310
webmaster@1 311 If you are installing on a non-standard port, the port number is treated as the
webmaster@1 312 deepest subdomain. For example: http://www.example.com:8080/ could be loaded
webmaster@1 313 from sites/8080.www.example.com/. The port number will be removed according to
webmaster@1 314 the pattern above if no port-specific configuration is found, just like a real
webmaster@1 315 subdomain.
webmaster@1 316
webmaster@1 317 Each site configuration can have its own site-specific modules and themes in
webmaster@1 318 addition to those installed in the standard 'modules' and 'themes' directories.
webmaster@1 319 To use site-specific modules or themes, simply create a 'modules' or 'themes'
webmaster@1 320 directory within the site configuration directory. For example, if
webmaster@1 321 sub.example.com has a custom theme and a custom module that should not be
webmaster@1 322 accessible to other sites, the setup would look like this:
webmaster@1 323
webmaster@1 324 sites/sub.example.com/:
webmaster@1 325 settings.php
webmaster@1 326 themes/custom_theme
webmaster@1 327 modules/custom_module
webmaster@1 328
webmaster@1 329 NOTE: for more information about multiple virtual hosts or the configuration
webmaster@1 330 settings, consult the Drupal handbook at drupal.org.
webmaster@1 331
webmaster@1 332 For more information on configuring Drupal's file system path in a multi-site
webmaster@1 333 configuration, see step 6 above.
webmaster@1 334
webmaster@1 335 MORE INFORMATION
webmaster@1 336 ----------------
webmaster@1 337
webmaster@1 338 - For additional documentation, see the online Drupal handbook at
webmaster@1 339 http://drupal.org/handbook.
webmaster@1 340
webmaster@1 341 - For a list of security announcements, see the "Security announcements" page
webmaster@1 342 at http://drupal.org/security (available as an RSS feed). This page also
webmaster@1 343 describes how to subscribe to these announcements via e-mail.
webmaster@1 344
webmaster@1 345 - For information about the Drupal security process, or to find out how to report
webmaster@1 346 a potential security issue to the Drupal security team, see the "Security team"
webmaster@1 347 page at http://drupal.org/security-team.
webmaster@1 348
webmaster@1 349 - For information about the wide range of available support options, see the
webmaster@1 350 "Support" page at http://drupal.org/support.