123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400 |
- CONTENTS OF THIS FILE
- ---------------------
- * Requirements and notes
- * Optional server requirements
- * 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.
- - Percona Server 5.1.70 (or greater) (http://www.percona.com/). Percona
- Server is a backwards-compatible replacement for MySQL.
- - PostgreSQL 8.3 (or greater) (http://www.postgresql.org/).
- - SQLite 3.3.7 (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.org online documentation.
- 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.org online documentation.
- 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 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
- files. For Clean URLs support on IIS, see "Clean URLs with IIS"
- (http://drupal.org/node/3854) in the Drupal.org online documentation.
- - 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.
- - 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.
- - 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.
- INSTALLATION
- ------------
- 1. Download and extract Drupal.
- You can obtain the latest Drupal release from http://drupal.org -- the files
- are available in .tar.gz and .zip formats and can be extracted using most
- compression tools.
- To download and extract the files, on a typical Unix/Linux command line, use
- the following commands (assuming you want version x.y of Drupal in .tar.gz
- format):
- 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. 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:
- 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/translate/downloads
- - Place the file into your installation profile's translations directory.
- For instance, if you are using the Standard installation 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 all site 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). 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.
- Take note of the username, password, database name, and hostname as you
- create the database. You will enter this information during the install.
- 4. 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.
- During installation, several files and directories need to be created, which
- 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.
- The most common steps you may need to perform are:
- a. Missing files directory.
- The install script will attempt to create a file 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, you can make it work by changing permissions on
- the sites/default directory so that the web server can create the files
- directory within it for you. (If you are creating a multisite
- installation, substitute the correct sites directory for sites/default;
- see the Multisite Configuration 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
- Alternatively, instead of allowing the web server to create the files
- directory for you as described above, you can create it yourself. Sample
- commands from a Unix/Linux command line:
- mkdir sites/default/files
- chmod a+w sites/default/files
- b. Missing settings 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,
- you will need to 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
- 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
- 5. Verify that the site is working.
- 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
- http://drupal.org/getting-started/clean-urls to troubleshoot.
- 6. Change file system storage settings (optional).
- The files directory created in step 4 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 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).
- - 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.
- 7. Revoke documentation file permissions (optional).
- 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
- Drupal.org online documentation.
- 8. Set up independent "cron" maintenance jobs.
- 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.
- 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.
- 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
- process to visit the page cron.php on your site, which executes the cron
- tasks.
- 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.
- 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
- wget command to visit the cron.php page, and runs 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, and sample cron shell scripts can be found in the
- scripts/ directory. (Note that these scripts must be customized like 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. 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
- more at http://drupal.org/project/modules and http://drupal.org/project/themes
- Do not mix downloaded or custom modules and themes with Drupal's core modules
- and themes. Drupal's modules and themes are located in the top-level modules and
- themes directories, while the modules and themes you add to Drupal are normally
- placed in the sites/all/modules and sites/all/themes directories. If you run a
- multisite installation, you can also place modules and themes in the
- site-specific directories -- see the Multisite Configuration section, below.
- Never edit Drupal's core modules and themes; instead, use the hooks available in
- the Drupal API. To modify the behavior of Drupal, develop a module as described
- at http://drupal.org/developing/modules. To modify the look of Drupal, create a
- subtheme as described at http://drupal.org/node/225125, or a completely new
- theme as described at http://drupal.org/documentation/theme
- 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 http://drupal.org/getting-started/6/install/multi-site
- For more information on configuring Drupal's file system path in a multisite
- configuration, see step 6 above.
- MORE INFORMATION
- ----------------
- - See the Drupal.org online documentation:
- http://drupal.org/documentation
- - For a list of security announcements, see the "Security advisories" 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.
|