webmaster@1: // $Id: INSTALL.txt,v 1.61.2.2 2008/02/07 20:46:56 goba Exp $ webmaster@1: webmaster@1: CONTENTS OF THIS FILE webmaster@1: --------------------- webmaster@1: webmaster@1: * Requirements webmaster@1: * Optional requirements webmaster@1: * Installation webmaster@1: * Drupal administration webmaster@1: * Customizing your theme(s) webmaster@1: * Multisite Configuration webmaster@1: * More Information webmaster@1: webmaster@1: REQUIREMENTS webmaster@1: ------------ webmaster@1: webmaster@1: Drupal requires a web server, PHP 4 (4.3.5 or greater) or PHP 5 webmaster@1: (http://www.php.net/) and either MySQL (http://www.mysql.com/) or PostgreSQL webmaster@1: (http://www.postgresql.org/). The Apache web server and MySQL database are webmaster@1: recommended; other web server and database combinations such as IIS and webmaster@1: PostgreSQL have been tested to a lesser extent. When using MySQL, version 4.1.1 webmaster@1: or greater is recommended to assure you can safely transfer the database. webmaster@1: webmaster@1: For more detailed information about Drupal requirements, see "Requirements" webmaster@1: (http://drupal.org/requirements) in the Drupal handbook. webmaster@1: webmaster@1: For detailed information on how to configure a test server environment using webmaster@1: a variety of operating systems and web servers, see "Local server setup" webmaster@1: (http://drupal.org/node/157602) in the Drupal handbook. webmaster@1: webmaster@1: OPTIONAL REQUIREMENTS webmaster@1: --------------------- webmaster@1: webmaster@1: - To use XML-based services such as the Blogger API and RSS syndication, webmaster@1: you will need PHP's XML extension. This extension is enabled by default. webmaster@1: webmaster@1: - To use Drupal's "Clean URLs" feature on an Apache web server, you will need webmaster@1: the mod_rewrite module and the ability to use local .htaccess files. For webmaster@1: Clean URLs support on IIS, see "Using Clean URLs with IIS" webmaster@1: (http://drupal.org/node/3854) in the Drupal handbook. webmaster@1: webmaster@1: - Various Drupal features require that the web server process (for webmaster@1: example, httpd) be able to initiate outbound connections. This is usually webmaster@1: possible, but some hosting providers or server configurations forbid such webmaster@1: connections. The features that depend on this functionality include the webmaster@1: integrated "Update status" module (which downloads information about webmaster@1: available updates of Drupal core and any installed contributed modules and webmaster@1: themes), the ability to log in via OpenID, fetching aggregator feeds, or webmaster@1: other network-dependent services. webmaster@1: webmaster@1: webmaster@1: INSTALLATION webmaster@1: ------------ webmaster@1: webmaster@1: 1. DOWNLOAD DRUPAL AND OPTIONALLY A TRANSLATION webmaster@1: webmaster@1: You can obtain the latest Drupal release from http://drupal.org/. The files webmaster@1: are in .tar.gz format and can be extracted using most compression tools. On a webmaster@1: typical Unix command line, use: webmaster@1: webmaster@1: wget http://drupal.org/files/projects/drupal-x.x.tar.gz webmaster@1: tar -zxvf drupal-x.x.tar.gz webmaster@1: webmaster@1: This will create a new directory drupal-x.x/ containing all Drupal files webmaster@1: and directories. Move the contents of that directory into a directory within webmaster@1: your web server's document root or your public HTML directory: webmaster@1: webmaster@1: mv drupal-x.x/* drupal-x.x/.htaccess /var/www/html webmaster@1: webmaster@1: If you would like to have the default English interface translated to a webmaster@1: different language, we have good news. You can install and use Drupal in webmaster@1: other languages from the start. Check whether a released package of the webmaster@1: language desired is available for this Drupal version at webmaster@1: http://drupal.org/project/translations and download the package. Extract webmaster@1: the contents to the same directory where you extracted Drupal into. webmaster@1: webmaster@1: 2. GRANT WRITE PERMISSIONS ON CONFIGURATION FILE webmaster@1: webmaster@1: Drupal comes with a default.settings.php file in the sites/default webmaster@1: directory. The installer will create a copy of this file filled with webmaster@1: the details you provide through the install process, in the same webmaster@1: directory. Give the web server write privileges to the sites/default webmaster@1: directory with the command (from the installation directory): webmaster@1: webmaster@1: chmod o+w sites/default webmaster@1: webmaster@1: 3. CREATE THE DRUPAL DATABASE webmaster@1: webmaster@1: Drupal requires access to a database in order to be installed. Your database webmaster@1: user will need sufficient privileges to run Drupal. Additional information webmaster@1: about privileges, and instructions to create a database using the command webmaster@1: line are available in INSTALL.mysql.txt (for MySQL) or INSTALL.pgsql.txt webmaster@1: (for PostgreSQL). webmaster@1: webmaster@1: To create a database using PHPMyAdmin or a web-based control panel consult webmaster@1: the documentation or ask your webhost service provider. webmaster@1: webmaster@1: Take note of the username, password, database name and hostname as you webmaster@1: create the database. You will enter these items in the install script. webmaster@1: webmaster@1: 4. RUN THE INSTALL SCRIPT webmaster@1: webmaster@1: To run the install script point your browser to the base URL of your website webmaster@1: (e.g., http://www.example.com). webmaster@1: webmaster@1: You will be guided through several screens to set up the database, webmaster@1: create tables, add the first user account and provide basic web webmaster@1: site settings. webmaster@1: webmaster@1: The install script will attempt to create a files storage directory webmaster@1: in the default location at sites/default/files (the location of the webmaster@1: files directory may be changed after Drupal is installed). In some webmaster@1: cases, you may need to create the directory and modify its permissions webmaster@1: manually. Use the following commands (from the installation directory) webmaster@1: to create the files directory and grant the web server write privileges to it: webmaster@1: webmaster@1: mkdir sites/default/files webmaster@1: chmod o+w sites/default/files webmaster@1: webmaster@1: The install script will attempt to write-protect the sites/default webmaster@1: directory after creating the settings.php file. If you make manual webmaster@1: changes to that file later, be sure to protect it again after making webmaster@1: your modifications. Failure to remove write permissions to that file webmaster@1: is a security risk. Although the default location for the settings.php webmaster@1: file is at sites/default/settings.php, it may be in another location webmaster@1: if you use the multi-site setup, as explained below. webmaster@1: webmaster@1: 5. CONFIGURE DRUPAL webmaster@1: webmaster@1: When the install script succeeds, you will be directed to the "Welcome" webmaster@1: page, and you will be logged in as the administrator already. Proceed with webmaster@1: the initial configuration steps suggested on the "Welcome" page. webmaster@1: webmaster@1: If the default Drupal theme is not displaying properly and links on the page webmaster@1: result in "Page Not Found" errors, try manually setting the $base_url variable webmaster@1: in the settings.php file if not already set. It's currently known that servers webmaster@1: running FastCGI can run into problems if the $base_url variable is left webmaster@1: commented out (see http://bugs.php.net/bug.php?id=19656). webmaster@1: webmaster@1: 6. REVIEW FILE SYSTEM STORAGE SETTINGS AND FILE PERMISSIONS webmaster@1: webmaster@1: The files directory created in step 4 is the default file system path used webmaster@1: to store all uploaded files, as well as some temporary files created by Drupal. webmaster@1: After installation, the settings for the file system path may be modified webmaster@1: to store uploaded files in a different location. webmaster@1: webmaster@1: It is not necessary to modify this path, but you may wish to change it if: webmaster@1: webmaster@1: * your site runs multiple Drupal installations from a single codebase webmaster@1: (modify the file system path of each installation to a different webmaster@1: directory so that uploads do not overlap between installations); or, webmaster@1: webmaster@1: * your site runs a number of web server front-ends behind a load webmaster@1: balancer or reverse proxy (modify the file system path on each webmaster@1: server to point to a shared file repository). webmaster@1: webmaster@1: To modify the file system path: webmaster@1: webmaster@1: * Ensure that the new location for the path exists or create it if webmaster@1: necessary. To create a new directory named uploads, for example, webmaster@1: use the following command from a shell or system prompt (while in webmaster@1: the installation directory): webmaster@1: webmaster@1: mkdir uploads webmaster@1: webmaster@1: * Ensure that the new location for the path is writable by the web webmaster@1: server process. To grant write permissions for a directory named webmaster@1: uploads, you may need to use the following command from a shell webmaster@1: or system prompt (while in the installation directory): webmaster@1: webmaster@1: chmod o+w uploads webmaster@1: webmaster@1: * Access the file system path settings in Drupal by selecting these webmaster@1: menu items from the Navigation menu: webmaster@1: webmaster@1: Administer > Site configuration > File system webmaster@1: webmaster@1: Enter the path to the new location (e.g.: uploads) at the File webmaster@1: System Path prompt. webmaster@1: webmaster@1: Changing the file system path after files have been uploaded may cause webmaster@1: unexpected problems on an existing site. If you modify the file system path webmaster@1: on an existing site, remember to copy all files from the original location webmaster@1: to the new location. webmaster@1: webmaster@1: Some administrators suggest making the documentation files, especially webmaster@1: CHANGELOG.txt, non-readable so that the exact version of Drupal you are webmaster@1: running is slightly more difficult to determine. If you wish to implement webmaster@1: this optional security measure, use the following command from a shell or webmaster@1: system prompt (while in the installation directory): webmaster@1: webmaster@1: chmod a-r CHANGELOG.txt webmaster@1: webmaster@1: Note that the example only affects CHANGELOG.txt. To completely hide webmaster@1: all documentation files from public view, repeat this command for each of webmaster@1: the Drupal documentation files in the installation directory, substituting the webmaster@1: name of each file for CHANGELOG.txt in the example. webmaster@1: webmaster@1: For more information on setting file permissions, see "Modifying Linux, Unix, webmaster@1: and Mac file permissions" (http://drupal.org/node/202483) or "Modifying webmaster@1: Windows file permissions" (http://drupal.org/node/202491) in the online webmaster@1: handbook. webmaster@1: webmaster@1: 7. CRON MAINTENANCE TASKS webmaster@1: webmaster@1: Many Drupal modules have periodic tasks that must be triggered by a cron webmaster@1: maintenance task, including search module (to build and update the index webmaster@1: used for keyword searching), aggregator module (to retrieve feeds from other webmaster@1: sites), ping module (to notify other sites about new or updated content), and webmaster@1: system module (to perform routine maintenance and pruning on system tables). webmaster@1: To activate these tasks, call the cron page by visiting webmaster@1: http://www.example.com/cron.php, which, in turn, executes tasks on behalf webmaster@1: of installed modules. webmaster@1: webmaster@1: Most systems support the crontab utility for scheduling tasks like this. The webmaster@1: following example crontab line will activate the cron tasks automatically on webmaster@1: the hour: webmaster@1: webmaster@1: 0 * * * * wget -O - -q -t 1 http://www.example.com/cron.php webmaster@1: webmaster@1: More information about cron maintenance tasks are available in the help pages webmaster@1: and in Drupal's online handbook at http://drupal.org/cron. Example scripts can webmaster@1: be found in the scripts/ directory. webmaster@1: webmaster@1: DRUPAL ADMINISTRATION webmaster@1: --------------------- webmaster@1: webmaster@1: A new installation of Drupal defaults to a very basic configuration with only a webmaster@1: few active modules and minimal user access rights. webmaster@1: webmaster@1: Use your administration panel to enable and configure services. For example: webmaster@1: webmaster@1: General Settings Administer > Site configuration > Site information webmaster@1: Enable Modules Administer > Site building > Modules webmaster@1: Configure Themes Administer > Site building > Themes webmaster@1: Set User Permissions Administer > User management > Permissions webmaster@1: webmaster@1: For more information on configuration options, read the instructions which webmaster@1: accompany the different configuration settings and consult the various help webmaster@1: pages available in the administration panel. webmaster@1: webmaster@1: Community-contributed modules and themes are available at http://drupal.org/. webmaster@1: webmaster@1: CUSTOMIZING YOUR THEME(S) webmaster@1: ------------------------- webmaster@1: webmaster@1: Now that your installation is running, you will want to customize the look of webmaster@1: your site. Several sample themes are included and more can be downloaded from webmaster@1: drupal.org. webmaster@1: webmaster@1: Simple customization of your theme can be done using only CSS. Further changes webmaster@1: require understanding the phptemplate engine that is part of Drupal. See webmaster@1: http://drupal.org/handbook/customization to find out more. webmaster@1: webmaster@1: MULTISITE CONFIGURATION webmaster@1: ----------------------- webmaster@1: webmaster@1: A single Drupal installation can host several Drupal-powered sites, each with webmaster@1: its own individual configuration. webmaster@1: webmaster@1: Additional site configurations are created in subdirectories within the 'sites' webmaster@1: directory. Each subdirectory must have a 'settings.php' file which specifies the webmaster@1: configuration settings. The easiest way to create additional sites is to copy webmaster@1: the 'default' directory and modify the 'settings.php' file as appropriate. The webmaster@1: new directory name is constructed from the site's URL. The configuration for webmaster@1: www.example.com could be in 'sites/example.com/settings.php' (note that 'www.' webmaster@1: should be omitted if users can access your site at http://example.com/). webmaster@1: webmaster@1: Sites do not have to have a different domain. You can also use subdomains and webmaster@1: subdirectories for Drupal sites. For example, example.com, sub.example.com, webmaster@1: and sub.example.com/site3 can all be defined as independent Drupal sites. The webmaster@1: setup for a configuration such as this would look like the following: webmaster@1: webmaster@1: sites/default/settings.php webmaster@1: sites/example.com/settings.php webmaster@1: sites/sub.example.com/settings.php webmaster@1: sites/sub.example.com.site3/settings.php webmaster@1: webmaster@1: When searching for a site configuration (for example www.sub.example.com/site3), webmaster@1: Drupal will search for configuration files in the following order, using the webmaster@1: first configuration it finds: webmaster@1: webmaster@1: sites/www.sub.example.com.site3/settings.php webmaster@1: sites/sub.example.com.site3/settings.php webmaster@1: sites/example.com.site3/settings.php webmaster@1: sites/www.sub.example.com/settings.php webmaster@1: sites/sub.example.com/settings.php webmaster@1: sites/example.com/settings.php webmaster@1: sites/default/settings.php webmaster@1: webmaster@1: If you are installing on a non-standard port, the port number is treated as the webmaster@1: deepest subdomain. For example: http://www.example.com:8080/ could be loaded webmaster@1: from sites/8080.www.example.com/. The port number will be removed according to webmaster@1: the pattern above if no port-specific configuration is found, just like a real webmaster@1: subdomain. webmaster@1: webmaster@1: Each site configuration can have its own site-specific modules and themes in webmaster@1: addition to those installed in the standard 'modules' and 'themes' directories. webmaster@1: To use site-specific modules or themes, simply create a 'modules' or 'themes' webmaster@1: directory within the site configuration directory. For example, if webmaster@1: sub.example.com has a custom theme and a custom module that should not be webmaster@1: accessible to other sites, the setup would look like this: webmaster@1: webmaster@1: sites/sub.example.com/: webmaster@1: settings.php webmaster@1: themes/custom_theme webmaster@1: modules/custom_module webmaster@1: webmaster@1: NOTE: for more information about multiple virtual hosts or the configuration webmaster@1: settings, consult the Drupal handbook at drupal.org. webmaster@1: webmaster@1: For more information on configuring Drupal's file system path in a multi-site webmaster@1: configuration, see step 6 above. webmaster@1: webmaster@1: MORE INFORMATION webmaster@1: ---------------- webmaster@1: webmaster@1: - For additional documentation, see the online Drupal handbook at webmaster@1: http://drupal.org/handbook. webmaster@1: webmaster@1: - For a list of security announcements, see the "Security announcements" page webmaster@1: at http://drupal.org/security (available as an RSS feed). This page also webmaster@1: describes how to subscribe to these announcements via e-mail. webmaster@1: webmaster@1: - For information about the Drupal security process, or to find out how to report webmaster@1: a potential security issue to the Drupal security team, see the "Security team" webmaster@1: page at http://drupal.org/security-team. webmaster@1: webmaster@1: - For information about the wide range of available support options, see the webmaster@1: "Support" page at http://drupal.org/support.