// $Id: INSTALL.txt,v 1.84 2010/10/11 23:49:48 dries Exp $ CONTENTS OF THIS FILE --------------------- * Requirements and notes * Optional tasks * Installation * Building and customizing your site * Multisite configuration * More information REQUIREMENTS AND NOTES ---------------------- Drupal requires: - A web server. Apache (version 2.0 or greater) is recommended. - PHP 5.2.4 (or greater) (http://www.php.net/). - One of the following databases: - MySQL 5.0.15 (or greater) (http://www.mysql.com/). - MariaDB 5.1.44 (or greater) (http://mariadb.org/). MariaDB is a fully compatible drop-in replacement for MySQL. - PostgreSQL 8.3 (or greater) (http://www.postgresql.org/). - SQLite 3.4.2 (or greater) (http://www.sqlite.org/). For more detailed information about Drupal requirements, including a list of PHP extensions and configurations that are required, see "System requirements" (http://drupal.org/requirements) in the Drupal handbook. For detailed information on how to configure a test server environment using a variety of operating systems and web servers, see "Local server setup" (http://drupal.org/node/157602) in the Drupal handbook. 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). OPTIONAL TASKS -------------- - To use XML-based services such as the Blogger API and RSS syndication, you will need PHP's XML extension. This extension is enabled by default. - 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 files. For Clean URLs support on IIS, see "Using Clean URLs with IIS" (http://drupal.org/node/3854) in the Drupal handbook. - 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. - Various Drupal features require that the web server process (for example, httpd) be able to initiate outbound connections. This is usually possible, but some hosting providers or server configurations forbid such connections. The features that depend on this functionality include the integrated "Update manager" module (which downloads information about available updates of Drupal core and any installed contributed modules and themes), the ability to log in via OpenID, fetching aggregator feeds, and other network- dependent services. INSTALLATION ------------ 1. Download and extract Drupal. You can obtain the latest Drupal release from http://drupal.org/. The files are in .tar.gz format and can be extracted using most compression tools. To download, extract, and copy the files, on a typical Unix/Linux command line, use the following commands (assuming you want version x.y of Drupal): wget http://drupal.org/files/projects/drupal-x.y.tar.gz tar -zxvf drupal-x.y.tar.gz This will create a new directory drupal-x.y/ containing all Drupal files and directories. Move the contents of that directory into a directory within your web server's document root or your public HTML directory: mv drupal-x.y/* drupal-x.y/.htaccess /path/to/your/installation 2. Optionally, download a translation. By default, Drupal is installed in English, and further languages may be installed later. If you prefer to install Drupal in another language initially: - Download a translation file for the correct Drupal version and language from the translation server: http://localize.drupal.org/download - Rename the downloaded file to your language's ISO code (e.g., de.po or fr.po) and place it into your installation profile's translations directory. For instance, if you are using the Standard install profile, move the .po file into the directory: profiles/standard/translations/ For detailed instructions, visit http://drupal.org/localize. 3. Create the Drupal database. Because Drupal stores site all information in a database, you must create this database in order to install Drupal, and grant Drupal certain database privileges (such as the ability to create tables). There are separate files describing the needed database privileges and how to create a database: INSTALL.mysql.txt (for MySQL), INSTALL.pgsql.txt (for PostgreSQL), and INSTALL.sqlite.txt (for SQLite). You may also need to consult your web hosting provider for instructions specific to your web host. Take note of the username, password, database name, and hostname as you create the database. You will enter this information during the install. 4. Make the sites/default directory writable. So that the installation script can automatically create files and directories (see below), set the permissions on the sites/default directory so that the web server can create files and directories there. If you are creating a multisite installation, substitute the correct sites directory for sites/default (see the Multisite section of this file below). For example, on a Unix/Linux command line, you can grant everyone (including the web server) permission to write to the sites/default directory with this command: chmod a+w sites/default Be sure to set the permissions back after the installation is finished! Sample command: chmod go-w sites/default 5. Run the install script. 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. The install script may also tell you that it cannot proceed until you fix certain issues with server requirements and files. The most common file system issues are with write permissions on directories and files: a. Missing settings.php file. Drupal will try to automatically create a settings.php configuration file, which is normally in the directory sites/default (to avoid problems when upgrading, Drupal is not packaged with this file). If auto-creation fails, and you followed step 4 above, you can create this file yourself, using the file sites/default/default.settings.php as a template. For example, on a Unix/Linux command line, you can make a copy of the default.settings.php file with the command: cp sites/default/default.settings.php sites/default/settings.php Next, grant write privileges to the file to everyone (including the web server) with the command: chmod a+w sites/default/settings.php Be sure to set the permissions back after the installation is finished! Sample command: chmod go-w sites/default/settings.php b. Files directory. The install script will attempt to create a files storage directory in the default location at sites/default/files (the location of the files directory may be changed after Drupal is installed). If auto-creation fails, and you followed step 4 above, you can create this directory yourself. You will also need to grant the web server write permission on this directory. Sample commands from a Unix/Linux command line: mkdir sites/default/files chmod a+w sites/default/files c. Write permissions after install. 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: chmod go-w sites/default/settings.php chmod go-w sites/default 6. Initial configuration. When the install script finishes, you will be directed to the "Welcome" page, logged in with the site maintenance account. At this time, you can proceed with the initial configuration steps suggested on the "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 http://drupal.org/getting-started/clean-urls to troubleshoot. 7. File system storage settings. The files directory created in step 5 is the default file system path used to 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. It is not necessary to modify this path, but you may wish to change it if: - 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). - Your site runs a number of web server front-ends behind a load balancer or reverse proxy (modify the file system path on each server to point to a shared file repository). - You want to restrict access to uploaded files. 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. 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. 8. Revoke documentation file permissions. 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 this optional security measure, from a Unix/Linux command line you can use the following command: chmod a-r CHANGELOG.txt 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 name of each file for CHANGELOG.txt in the example. For more information on setting file permissions, see "Modifying Linux, Unix, and Mac file permissions" (http://drupal.org/node/202483) or "Modifying Windows file permissions" (http://drupal.org/node/202491) in the online handbook. 9. Running "cron" maintenance tasks. Many Drupal modules have tasks that must be run periodically, including search module (to build and update the index used for keyword searching), aggregator module (to retrieve feeds from other sites), and system module (to perform routine maintenance and pruning on system tables). For most sites, the built-in, automated cron feature should be sufficient. This feature automatically runs the periodic tasks, triggered by people visiting pages of your site. You can configure the built-in cron feature by navigating to Administration > Configuration > System > Cron. Advanced users may want to ensure that cron tasks are executed periodically, independent of site visitors. To do this, you will need to set up an automated ("cron") process to visit the page cron.php on your site, which executes the maintenance tasks on behalf of installed modules. The URL of the cron.php page requires a "cron key" to protect against 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. Most systems support using a crontab utility for automatically executing tasks like visiting the cron.php page. The following example crontab line uses wget to automatically visit the cron.php page each hour, on the hour: 0 * * * * wget -O - -q -t 1 http://example.com/cron.php?cron_key=YOURKEY Replace the text "http://example.com/cron.php?cron_key=YOURKEY" in the example with the full URL displayed under "Cron maintenance tasks" on the "Status report" page. More information about cron maintenance tasks is available at http://drupal.org/cron. Sample cron shell scripts can be found in the scripts/ directory. (Note that these scripts must be customized similar to the above example, to add your site-specific cron key and domain name.) BUILDING AND CUSTOMIZING YOUR SITE ---------------------------------- A new installation of Drupal defaults to a very basic configuration with only a few active modules and minimal user access rights. When extending your site, you use "modules" and "themes". A module is a plugin that adds functionality to Drupal, while a theme changes the front-end look and behavior of your site. It is important to install these correctly and not mix them in with the core Drupal module and theme set (directories modules and themes at the top level). Normally you place them in the following directories: Modules: sites/all/modules/example_module Themes: sites/all/themes/example_theme If you run a multisite installation you will want to do this a bit differently. You can read more about that on the multisite part of this file. Contributed modules can be found at: http://drupal.org/project/Modules Contributed themes can be found at: http://drupal.org/project/Themes Later on you might want to write your own code, but remember to NEVER modify the core modules and themes in Drupal modules and themes directories. Instead use the hooks available in the Drupal API. You can read more about the Drupal API and how to develop modules at http://drupal.org/developing/modules MULTISITE CONFIGURATION ----------------------- A single Drupal installation can host several Drupal-powered sites, each with its own individual configuration. Additional site configurations are created in subdirectories within the 'sites' directory. Each subdirectory must have a 'settings.php' file, which specifies the configuration settings. The easiest way to create additional sites is to copy the 'default' directory and modify the 'settings.php' file 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/). Sites do not have to have a different domain. You can also use subdomains and 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: 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 addition to those installed in the standard 'modules' and 'themes' directories. 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: sites/sub.example.com/ settings.php themes/custom_theme modules/custom_module NOTE: for more information about multiple virtual hosts or the configuration settings, consult the Drupal handbook at drupal.org. For more information on configuring Drupal's file system path in a multisite configuration, see step 7 above. MORE INFORMATION ---------------- - For additional documentation, see the online Drupal handbook at http://drupal.org/handbook. - For a list of security announcements, see the "Security announcements" page at http://drupal.org/security (available as an RSS feed). This page also describes how to subscribe to these announcements via e-mail. - For information about the Drupal security process, or to find out how to report a potential security issue to the Drupal security team, see the "Security team" page at http://drupal.org/security-team. - For information about the wide range of available support options, visit http://drupal.org and click on Community and Support in the top or bottom navigation.