Installation and Upgrading

3 Aug 2007

Drupal Handbook

Table of ContentsInstallation and configuration . . . . . . . . . . . . System requirements . . . . . . . . . . . . . . Client System Requirements . . . . . . . . . . . Javascript . . . . . . . . . . . . . . . CSS . . . . . . . . . . . . . . . . . RSS . . . . . . . . . . . . . . . . . Browser Specifics . . . . . . . . . . . . . Browser Popularity . . . . . . . . . . . . . Known Problems . . . . . . . . . . . . . Validation . . . . . . . . . . . . . . . Caveats . . . . . . . . . . . . . . . . HOWTO: Server requirement recommendations for your consulting clients Message to the Client . . . . . . . . . . . . Benchmark . . . . . . . . . . . . . . . What Drupal.org runs on . . . . . . . . . . . Requirements - older versions . . . . . . . . . . . Installing Drupal, modules and themes . . . . . . . . . Installing Drupal . . . . . . . . . . . . . . Formatted Drupal 5.x Installation instructions for better readability . Installation . . . . . . . . . . . . . . Changes . . . . . . . . . . . . . . . Requirements . . . . . . . . . . . . . . Optional Requirements . . . . . . . . . . . Installation . . . . . . . . . . . . . . Drupal Administration . . . . . . . . . . . Customizing your theme(s) . . . . . . . . . . Multi-site configuration . . . . . . . . . . . More Information . . . . . . . . . . . . . Formatted Drupal 4.7.x Installation instructions for better readability . Installation . . . . . . . . . . . . . . REQUIREMENTS . . . . . . . . . . . . . SERVER CONFIGURATION . . . . . . . . . . . OPTIONAL COMPONENTS . . . . . . . . . . . INSTALLATION . . . . . . . . . . . . . 1. DOWNLOAD DRUPAL . . . . . . . . . . . 2. CREATE THE DRUPAL DATABASE . . . . . . . 3. LOAD THE DRUPAL DATABASE SCHEME . . . . . . 4. CONNECTING DRUPAL . . . . . . . . . . 5. CONFIGURE DRUPAL . . . . . . . . . . . 6. CRON TASKS . . . . . . . . . . . . . DRUPAL ADMINISTRATION . . . . . . . . . . CUSTOMIZING YOUR THEME(S) . . . . . . . . . UPGRADING . . . . . . . . . . . . . . MORE INFORMATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2 3 3 4 4 4 4 4 4 4 5 5 6 6 6 8 8 13 13 14 14 14 14 16 16 16 17 17 17 18 18 18 19 19 19 20 20 21 22 22 22 23 23

i

Drupal Handbook

3 Aug 2007

10 minute install using PuTTY SSH/Telnet client . . . . . . . . . How I installed Drupal: The Eightfold Way . . . . . . . . . . Installing virtual hosts for Drupal sites and subsites . . . . . . . . Mac OS X-specific guidelines . . . . . . . . . . . . . . Important notes for MySQL install: . . . . . . . . . . . . HOWTO: Create a local server environment for drupal using MAMP . . . . HOWTO: Installing PostgreSQL and MySQL on the same Mac OS X machine . . Installing Drupal on Mac OS X 10.4 Tiger . . . . . . . . . . Installing and Configuring MySQL . . . . . . . . . . . Sending mail . . . . . . . . . . . . . . . . . Creating the Drupal Database and Database User . . . . . . . . Installing using CVS repository . . . . . . . . . . . . Prefixed database.mysql for search and replace . . . . . . . . . . Setup Drupal on Windows XP Pro using IIS . . . . . . . . . . Basic /sites directory setup . . . . . . . . . . . . . . Special cases . . . . . . . . . . . . . . . . . . Compilation failed: this version of PCRE is not compiled with PCRE_UTF8 support Configure .htaccess to allow awstats to work with clean URLs . . . . . Configuring .htaccess to ignore specific subfolders . . . . . . . . Ignoring Subfolders that exist in the DocumentRoot . . . . . . . Ignoring subfolders that are included via Apache Alias directives . . . . Create a custom php.ini . . . . . . . . . . . . . . . How to create a custom php.ini file when nothing else works . . . . . 1. Get and modify your custom php.ini file . . . . . . . . . 2. Creating your CGI script . . . . . . . . . . . . . 3. Modifying your .htaccess file . . . . . . . . . . . . 4. Test your site . . . . . . . . . . . . . . . . Create Drupal database using Plesk . . . . . . . . . . . . Drupal with safe mode enabled and open basedir . . . . . . . . Generic Mass SQL Import into Drupal . . . . . . . . . . . DrupalCon site . . . . . . . . . . . . . . . . How to degrade your Drupal db from MySQL 4.1.X/5.0.X to MySQL 4.0.X . . How-To: Virtual Hosting with Drupal . . . . . . . . . . . Introduction . . . . . . . . . . . . . . . . . Environment . . . . . . . . . . . . . . . . . Requirements . . . . . . . . . . . . . . . . . Next pages . . . . . . . . . . . . . . . . . How-To: Virtual Hosting with Drupal :: Prepare environment . . . . . Introduction . . . . . . . . . . . . . . . . . The drupal group . . . . . . . . . . . . . . . . The temp directory . . . . . . . . . . . . . . . The reference location . . . . . . . . . . . . . . . Navigation . . . . . . . . . . . . . . . . . How-To: Virtual Hosting with Drupal :: Solution Overview . . . . . Introduction . . . . . . . . . . . . . . . . . Safe mode . . . . . . . . . . . . . . . . . Open Basedir . . . . . . . . . . . . . . . . .

23 . 24 . 25 . 26 . 27 . 28 . 29 . 30 . 30 . 32 . 32 . 33 . 36 . 51 . 52 . 53 . 53 . 54 . 55 . 55 . 55 . 56 . 60 . 60 . 60 . 61 . 61 . 61 . 62 . 65 . 67 . 67 . 68 . 68 . 68 . 69 . 69 . 69 . 69 . 70 . 70 . 70 . 70 . 71 . 71 . 71 . 71 .

ii

3 Aug 2007

Drupal Handbook

Plesk integration . . . . . . . . . . . . . . Managed application . . . . . . . . . . . . . eAccelerator . . . . . . . . . . . . . . . Each individual vhost requirements . . . . . . . . . Navigation . . . . . . . . . . . . . . . HOWTO: copy a site to a local computer using XAMPP . . . . . HOWTO: Copy site to another directory for testing . . . . . . HOWTO: Install Drupal 5.x using cPanel . . . . . . . . HOWTO: Install Drupal using cPanel . . . . . . . . . HOWTO: Site to site transfer with phpMyAdmin and a FTP Client . . Import a MySQL data dump with BigDump . . . . . . . . What is BigDump? . . . . . . . . . . . . . Setting up BigDump . . . . . . . . . . . . . Uploading the sql file and bigdump.php to the webserver . . . . Running BigDump . . . . . . . . . . . . . Installing Drupal behind an Actiontec GT701-WG router . . . . . Installing Drupal in a subdirectory in 4.6 . . . . . . . . . More than one Drupal site on one machine . . . . . . . . General rules for multiple Drupal deployments . . . . . . Moving your Drupal installation to a new directory . . . . . . PCRE_UTF8 solution for VPS servers | FreeBSD . . . . . . . Known causes of PCRE server errors . . . . . . . . . Redirecting specific pages to new URLs (301 redirects in Drupal) . . . How to create 301 redirects in Drupal Apache mod_rewrite . . . The tolerant base URL . . . . . . . . . . . . . Using .htaccess to stop page caching . . . . . . . . . . Linux specific guidelines . . . . . . . . . . . . . Installing PHP, MySQL and Apache under Linux . . . . . . XAMPP for Linux Packages . . . . . . . . . . . . Installing XAMPP in Debian . . . . . . . . . . . Download XAMPP Latest version from the following link . . . . Start XAMPP Server . . . . . . . . . . . . . Windows-specific guidelines . . . . . . . . . . . . How to install Drupal for newbies using FTP and phpMyAdmin . . . Change "/tmp" on your drupal site. . . . . . . . . . Get Drupal ready . . . . . . . . . . . . . . Upload the database . . . . . . . . . . . . . HOWTO: Create an apache sandbox using Windows and Apache2Triad . Before you begin . . . . . . . . . . . . . . Installing Apache2Triad . . . . . . . . . . . . Installing Drupal . . . . . . . . . . . . . . Importing and exporting Drupal databases updated with PHPMyAdmin To export a database with PHPMyAdmin . . . . . . . . To import a database with PHPMyAdmin . . . . . . . . Using bigdump.php to deal with large databases . . . . . . Installing Apache (with PHP) on Windows . . . . . . . . Installing MySQL on Windows . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

72 . 72 . 72 . 73 . 73 . 73 . 74 . 75 . 77 . 80 . 82 . 82 . 83 . 83 . 84 . 84 . 85 . 85 . 86 . 86 . 87 . 88 . 88 . 89 . 89 . 90 . 90 . 90 . 91 . 91 . 91 . 91 . 94 . 95 . 95 . 95 . 96 . 96 . 97 . 97 . 98 . 100 . 100 . 101 . 102 . 102 . 104 .

iii

Drupal Handbook

3 Aug 2007

Installing PHP4 on Windows . . . . . . . . . . . . . 105 . Drupal 4.7 on Windows/IIS Requires PHP in ISAPI mode . . . . . . 105 . Installing PostgreSQL on Windows . . . . . . . . . . . . 105 . Multiple Drupal Sites under Windows . . . . . . . . . . . 106 . Running multiple sites on a local PC (localhost) from a single codebase, using Windows 106 Untar . . . . . . . . . . . . . . . . . . . 108 . Installing Drupal on Windows . . . . . . . . . . . . . 109 . PostgreSQL specific guidelines . . . . . . . . . . . . . 109 . ERROR: DB connect failed . . . . . . . . . . . . . . . 109 . ERROR: language "plpgsql" does not exist . . . . . . . . . . 110 . ERROR: null value in column "uid" violates not-null constraint . . . . . 110 . PostgreSQL support in Drupal 4.7.x . . . . . . . . . . . . 110 . Drupal 4.5 and PGSQL 8 configuration . . . . . . . . . . . 110 . Installing contributed modules . . . . . . . . . . . . . . 111 . HOWTO: Install glossary module . . . . . . . . . . . . . 113 . Where is the Glossary? . . . . . . . . . . . . . . . 113 . What is the purpose of the Glossary Module, and what does it do? . . . . 113 . Installing the Glossary Module . . . . . . . . . . . . . 114 . Configuring the Glossary . . . . . . . . . . . . . . 114 . Adding Full Page Definitions . . . . . . . . . . . . . 115 . Adding Glossary To Menus . . . . . . . . . . . . . . 115 . Leech - automating content addition . . . . . . . . . . . . 116 . Relationships between modules . . . . . . . . . . . . . 116 . Installing new modules (Drupal 4.6 or older) . . . . . . . . . . 117 . Multi-site installation and set-up . . . . . . . . . . . . . . 118 . 10 Minute Multisite Install & Configuration . . . . . . . . . . 119 . Access all multisites with www. only [.htaccess] . . . . . . . . . 121 . Drupal as a library . . . . . . . . . . . . . . . . 121 . Multi-site setup in 5.x using CPanel . . . . . . . . . . . . 123 . Multi-Site, Single Codebase, Shared Database, Shared Sign-on 4.6 . . . . . 124 . Apache (http) Configuration . . . . . . . . . . . . . 124 . Download and Placement . . . . . . . . . . . . . . 124 . SQL Setup . . . . . . . . . . . . . . . . . . 125 . Individual Site Configuration & Theming . . . . . . . . . . 126 . Some things which can be improved: . . . . . . . . . . . 127 . Multi-Site, Single Codebase, Shared Database, Shared Sign-on 5.x . . . . . 127 . 1. Prepare database and database user . . . . . . . . . . . 128 . 1.1. create a database and user . . . . . . . . . . . . . 128 . 2. create and modify site configuration . . . . . . . . . . . 128 . 2.1. duplicate settings folder . . . . . . . . . . . . . . 128 . 2.2. Modify config files . . . . . . . . . . . . . . . 128 . 2.2.1. provide DB connection detail . . . . . . . . . . . . 128 . 2.2.2. set prefixes for table names . . . . . . . . . . . . 128 . 3. create static links . . . . . . . . . . . . . . . . 129 . 4. install drupal . . . . . . . . . . . . . . . . . 130 . Multiple domains or vhosts using different databases . . . . . . . . 130 . Sharing Drupal tables between databases using MySQL5 Views . . . . . 131 .

iv

3 Aug 2007

Drupal Handbook

Multiple domains using the same database . . . . . . . . . Same codebase, completely different content and users . . . . . . Setup of /sites directory for multi-site . . . . . . . . . . Installing new themes . . . . . . . . . . . . . . Basic site configuration . . . . . . . . . . . . . . Settings . . . . . . . . . . . . . . . . . . General settings . . . . . . . . . . . . . . . Default front page . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . Clean URLs . . . . . . . . . . . . . . . . .htaccess for clean urls on specific shared hosts . . . . . . . 403 Permission denied error . . . . . . . . . . . . A mod_rewrite bug causing occasional corruption of the query string . . Apache 2 configuration of clean URLs on Debian . . . . . . . Apache 2 on Ubuntu . . . . . . . . . . . . . Editing apache2.conf . . . . . . . . . . . . . Editing apache2/sites-available . . . . . . . . . . Clean URL Support in Abyss . . . . . . . . . . . Clean URL support in XAMPP . . . . . . . . . . . Clean URLs in Mac OS X Server . . . . . . . . . . . Clean URLs with different webservers . . . . . . . . . Microsoft Internet Services Server . . . . . . . . . . Lighttpd . . . . . . . . . . . . . . . . Clean URLs with Easyphp. . . . . . . . . . . . . Example Clean URL configuration of httpd.conf for performance . . . Existing URLs for server overwrite Drupal paths . . . . . . . IIS CleanURLs using some of the available ISAPI filters. . . . . . Translating Apaches rewrite rules . . . . . . . . . Pathauto and Localizer . . . . . . . . . . . . . Setting up clean URLs above web document root on virtual private servers reboot vps after making change . . . . . . . . . . Using Clean URLs with IIS . . . . . . . . . . . . Alternate method . . . . . . . . . . . . . . set your sites 403 and 404 Error pages . . . . . . . . . . Configure your sites error reporting . . . . . . . . . . Cache support . . . . . . . . . . . . . . . Primary and secondary links . . . . . . . . . . . . General Information: . . . . . . . . . . . . . Setting Up Your Primary and Secondary Links: . . . . . . . Theming Your Link Menus . . . . . . . . . . . . Set length of trimmed posts and # of posts on front page . . . . . URL Alias Optimization . . . . . . . . . . . . . File system settings . . . . . . . . . . . . . . Download method . . . . . . . . . . . . . . Path settings . . . . . . . . . . . . . . . Date and time settings . . . . . . . . . . . . . . Customizing the interface . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

132 . 132 . 135 . 137 . 139 . 139 . 140 . 140 . 141 . 141 . 143 . 146 . 147 . 147 . 149 . 149 . 150 . 151 . 153 . 153 . 154 . 154 . 154 . 154 . 155 . 156 . 156 . 156 . 157 . 158 . 159 . 159 . 160 . 160 . 161 . 161 . 161 . 161 . 162 . 162 . 162 . 162 . 163 . 163 . 164 . 164 . 164 .

v

Drupal Handbook

3 Aug 2007

Customizing user login . . . . . . . . . . . . Beginners guide for Cron on a shared hosting provider . . . . Check your filters . . . . . . . . . . . . . Configure user registration . . . . . . . . . . . Creating a menu structure . . . . . . . . . . . Creating a menu . . . . . . . . . . . . . Simplifying the workflow . . . . . . . . . . . Helping search engines and robots.txt . . . . . . . . Controlling what gets indexed -- the robots.txt file . . . . . Add Disallow: /node/ if your setup has aliases for all nodes . Selective Bot Crawling . . . . . . . . . . . Increase upload size in your php.ini . . . . . . . . . Need images etc? - check Filtered HTML . . . . . . . . Set default content options - Stop automatic promotion to the front page Show/hide Submitted by on posts . . . . . . . . . Blocks . . . . . . . . . . . . . . . . Block configuration . . . . . . . . . . . . Restricting blocks to certain pages . . . . . . . . Preventing a block from appearing in Drupal 4.5 . . . . . Custom blocks . . . . . . . . . . . . . Increase memory in your php.ini . . . . . . . . . . Database table prefix (and sharing tables across instances) . . . Share tables across instances . . . . . . . . . . Setup tip for Drupal 5 . . . . . . . . . . . Using schema prefixes with PostgreSQL . . . . . . . Define shared variables for all sites . . . . . . . . Drupal Cookbook (for New Drupallers) . . . . . . . . Purpose . . . . . . . . . . . . . . . . Background . . . . . . . . . . . . . . . Myths . . . . . . . . . . . . . . . . Using the Drupal Web Site . . . . . . . . . . . Typing Convention . . . . . . . . . . . . . Some Preliminary Advice . . . . . . . . . . . Drupal Is Supposed to be Easy? . . . . . . . . . . A. Getting Started . . . . . . . . . . . . . B. Basic Configuration . . . . . . . . . . . . C. Creating Multiple Sites On Your Local Computer . . . . . D. Error Pages . . . . . . . . . . . . . . Page Not Found . . . . . . . . . . . . . Access Denied . . . . . . . . . . . . . E. Accessing Your Test Site(s) . . . . . . . . . . F. Adding Modules and Themes . . . . . . . . . . Installation . . . . . . . . . . . . . . Modules . . . . . . . . . . . . . . . Modules . . . . . . . . . . . . . . This Site . . . . . . . . . . . . . . Themes . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

165 . 166 . 167 . 168 . 168 . 169 . 169 . 169 . 170 . 171 . 171 . 175 . 176 . 177 . 178 . 178 . 178 . 179 . 180 . 182 . 182 . 183 . 184 . 185 . 185 . 187 . 189 . 189 . 189 . 189 . 190 . 190 . 190 . 191 . 192 . 193 . 194 . 197 . 197 . 197 . 198 . 198 . 199 . 199 . 199 . 200 . 200 .

vi

3 Aug 2007

Drupal Handbook

Themes . . . . . . . . . . . . . . . . Logo and Favorite Icon . . . . . . . . . . . . G. Creating Content . . . . . . . . . . . . . . Content Types . . . . . . . . . . . . . . Page . . . . . . . . . . . . . . . . . Story . . . . . . . . . . . . . . . . . Book Page . . . . . . . . . . . . . . . Blog Entry . . . . . . . . . . . . . . . G1. Creating a Page . . . . . . . . . . . . . G2. Creating a Story . . . . . . . . . . . . . Whats a Teaser? . . . . . . . . . . . . . G3. Creating a Book Page . . . . . . . . . . . . G4. Creating a Blog entry . . . . . . . . . . . . H. Custom Blocks . . . . . . . . . . . . . . Address . . . . . . . . . . . . . . . . Last Updated . . . . . . . . . . . . . . . I. Working with the Menu . . . . . . . . . . . . Introduction . . . . . . . . . . . . . . . How To Menu . . . . . . . . . . . . . . Textual Menu . . . . . . . . . . . . . . . Tabbed Menu . . . . . . . . . . . . . . . Books . . . . . . . . . . . . . . . . . More . . . . . . . . . . . . . . . . . I2. The Contact Form . . . . . . . . . . . . . Set Up . . . . . . . . . . . . . . . . Make It Accessible . . . . . . . . . . . . . Add "Contact" to the Menu . . . . . . . . . . . Using It In Content . . . . . . . . . . . . . J. URL Aliases . . . . . . . . . . . . . . . K. Moving Entire Drupal Site with Databases . . . . . . . . Backup Process with phpMyAdmin . . . . . . . . . Backup Process with phpMyAdmin . . . . . . . . . . L. Moving Stuff to Your Web Site . . . . . . . . . . M. Setting Up Cron . . . . . . . . . . . . . . N. Categories (Taxonomy) . . . . . . . . . . . . O. Common Problems . . . . . . . . . . . . . P. Links and IMG . . . . . . . . . . . . . . Q. Additional Tips and Tricks . . . . . . . . . . . Q1. Tracking Module Status . . . . . . . . . . . Q2. Making Multiple Site Maintenance a Bit Easier . . . . . . Q3. Controlling User Log In . . . . . . . . . . . How do I disable "Create New Account?" . . . . . . . How do I disable User Log In entirely, and how would I get in if I do? R. Keeping Your Local and Remote Sites Synchronized . . . . . S. More Reading . . . . . . . . . . . . . . . T. Glossary . . . . . . . . . . . . . . . . Taking your site live . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

200 . 200 . 201 . 202 . 202 . 202 . 202 . 203 . 203 . 204 . 204 . 205 . 205 . 206 . 206 . 206 . 207 . 207 . 207 . 208 . 208 . 208 . 209 . 209 . 209 . 209 . 210 . 210 . 210 . 211 . 213 . 213 . 216 . 216 . 217 . 219 . 219 . 220 . 220 . 220 . 221 . 221 . 221 . 222 . 222 . 223 . 226 .

vii

Drupal Handbook

3 Aug 2007

Moving from a temporary location . . . . . . . . Moving Drupal . . . . . . . . . . . . . Redirecting your server . . . . . . . . . . . Excluding paths from Drupal . . . . . . . . . Core modules . . . . . . . . . . . . . . Aggregator: publishing syndicated content . . . . . . Old page . . . . . . . . . . . . . . Open aggregator links in new browser window . . . . User Aggregator:user submitted feeds . . . . . . . What do I need to subscribe to a feed? . . . . . . . Configuring news feeds . . . . . . . . . . Filter feeds by keyword, time, by summary . . . . . Creating categories in the aggregator . . . . . . . Tagging individual items in the aggregator . . . . . . Using the news aggregator . . . . . . . . . RSS feed blocks . . . . . . . . . . . . Block: controlling content in the sidebars . . . . . . . Module blocks . . . . . . . . . . . . Administrator defined blocks . . . . . . . . . Blog: a blog for every user . . . . . . . . . . HOWTO: Configure user blogs . . . . . . . . Most recent blog post block . . . . . . . . . Navigate throught categories inside a blog . . . . . . What is a blog or weblog? . . . . . . . . . . Making user blogs more accessible . . . . . . . . Additional features . . . . . . . . . . . BlogApi: post from blog tools . . . . . . . . . Book: structured document publishing . . . . . . . Customising the book navigation menu . . . . . . Maintaining a FAQ using a collaborative book . . . . . Categories (taxonomy): A way to organize your content . . . Modules that do more with categories . . . . . . . Content Management System comparison focused on Taxonomy Taxonomy - some guidelines for effective design of taxonomies . Taxonomy Garden: Managing Categories . . . . . . Taxonomy Garden: Navigation by category . . . . . Taxonomy Garden: Organize content by category . . . . The taxonomy module for Drupal 4.x . . . . . . . Understanding categories for new users . . . . . . Using taxonomy to organize content . . . . . . . Using vocabularies for navigation . . . . . . . . Vocabularies and terms . . . . . . . . . . Creating a vocabulary . . . . . . . . . . Creating terms . . . . . . . . . . . . Advanced taxonomies: using hierarchies . . . . . . More about Taxonomy . . . . . . . . . . Creating a Block with links belonging to certain taxonomy terms

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

226 . 226 . 226 . 227 . 228 . 228 . 229 . 229 . 229 . 230 . 230 . 231 . 231 . 231 . 231 . 232 . 232 . 232 . 233 . 233 . 233 . 234 . 234 . 234 . 235 . 235 . 236 . 236 . 237 . 238 . 239 . 242 . 244 . 244 . 246 . 247 . 254 . 260 . 261 . 262 . 265 . 266 . 267 . 267 . 268 . 268 . 270 .

viii

3 Aug 2007

Drupal Handbook

Taxonomy terms on a page . . . . . . . . . . . . . Comment: allow comments on content . . . . . . . . . . . Detailed comment documentation . . . . . . . . . . . . User control of comment display . . . . . . . . . . . Additional comment configurations . . . . . . . . . . . Notification of new comments . . . . . . . . . . . . Comment moderation . . . . . . . . . . . . . . Moderation votes . . . . . . . . . . . . . . . Moderator vote/values matrix . . . . . . . . . . . . Creating comment thresholds . . . . . . . . . . . . Initial comment scores . . . . . . . . . . . . . . Aggregator comments . . . . . . . . . . . . . . Contact: a way for users to get in touch . . . . . . . . . . . Make your site wide contact form look prettier . . . . . . . . . Drupal: Drupal sites directory server . . . . . . . . . . . . Old page . . . . . . . . . . . . . . . . . . Filter: Input formats for user content . . . . . . . . . . . . Forum: create threaded discussions . . . . . . . . . . . . HOWTO: Create a forum . . . . . . . . . . . . . . HOWTO: Create forum containers . . . . . . . . . . . . Help: context-sensitive guidance . . . . . . . . . . . . . More about the help module . . . . . . . . . . . . . Legacy: remapping of old-style URLs . . . . . . . . . . . Locale: multi-language support . . . . . . . . . . . . . Adjusting your php.ini settings for importing .po files . . . . . . . Editing text for translation . . . . . . . . . . . . . . How to create Drupal site in Marathi (Devnagari) . . . . . . . . How to install a different language . . . . . . . . . . . HOWTO: Creating a customized language set to replace Drupal terminology . HOWTO: Use a customized language set to change Drupal text and terminology Note for the curious . . . . . . . . . . . . . . . Menu: customize site navigation . . . . . . . . . . . . . Using named anchors with menus . . . . . . . . . . . . Node: the content . . . . . . . . . . . . . . . . Page: post static pages . . . . . . . . . . . . . . . Difference between page and story . . . . . . . . . . . . Specify page by title . . . . . . . . . . . . . . . Path: readable URLs . . . . . . . . . . . . . . . . Mass URL aliasing . . . . . . . . . . . . . . . Ping: notify services of changes . . . . . . . . . . . . . Write a custom module to ping a set of sites . . . . . . . . . Poll: community voting . . . . . . . . . . . . . . . Profile: extending user account information . . . . . . . . . . Enabling user pictures (avatars) . . . . . . . . . . . . HOWTO: Create new profile fields . . . . . . . . . . . . HOWTO: Make a field part of the registration process . . . . . . . Form Validation in plugin . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

271 . 272 . 272 . 272 . 273 . 273 . 274 . 274 . 274 . 274 . 275 . 275 . 275 . 276 . 276 . 277 . 277 . 278 . 279 . 279 . 279 . 280 . 280 . 280 . 281 . 282 . 282 . 283 . 283 . 284 . 286 . 286 . 286 . 287 . 288 . 288 . 289 . 289 . 290 . 291 . 291 . 292 . 293 . 294 . 295 . 295 . 295 .

ix

Drupal Handbook

3 Aug 2007

HOWTO: Create a country profile field . . . . . . . . . CiviCRM: Tags, Profiles, Groups, advanced community member management Search: an internal site search system . . . . . . . . . . . Add searching to your custom module . . . . . . . . . . Statistics: tracking referrers, page hits, etc. . . . . . . . . . Story: post static pages . . . . . . . . . . . . . . System: cron and caching . . . . . . . . . . . . . Configuring cron jobs . . . . . . . . . . . . . . Configuring cron jobs on DreamHost . . . . . . . . . Cron Job configuration line by line . . . . . . . . . . Cronjobs without wget/lynx or curl . . . . . . . . . . Configuring cron jobs on Windows . . . . . . . . . . Throttle: congestion control . . . . . . . . . . . . . When to use the throttle module? . . . . . . . . . . . Tracker: viewing new and updated content . . . . . . . . . Upload: collaborate with files . . . . . . . . . . . . User: access and management settings . . . . . . . . . . Access Permissions reference . . . . . . . . . . . . block module . . . . . . . . . . . . . . . filter module . . . . . . . . . . . . . . . menu module . . . . . . . . . . . . . . . node module . . . . . . . . . . . . . . . path module . . . . . . . . . . . . . . . user module . . . . . . . . . . . . . . . system module . . . . . . . . . . . . . . . Access rules (email filters) . . . . . . . . . . . . . Managing access control with permissions and user roles . . . . . Assigning permissions and users to roles . . . . . . . . Taxonomy_access: Restrict user roles to access specific categories only . Adjusting permissions after adding modules . . . . . . . . User authentication . . . . . . . . . . . . . . Make a Drupal site use Basic Auth/ldap instead of the normal login block NTLM Authentication . . . . . . . . . . . . . User preferences and profiles . . . . . . . . . . . . Using distributed authentication . . . . . . . . . . . Distributed authentication . . . . . . . . . . . . Drupal . . . . . . . . . . . . . . . . . Watchdog: monitor your site . . . . . . . . . . . . . End user guide . . . . . . . . . . . . . . . . Registering as a user . . . . . . . . . . . . . . . Logging in . . . . . . . . . . . . . . . . . Changing your account settings . . . . . . . . . . . . Creating new content . . . . . . . . . . . . . . A step-by-step example . . . . . . . . . . . . . Controlling Teaser Location . . . . . . . . . . . . How to add a page to the Handbook . . . . . . . . . . Types of content . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

295 . 296 . 297 . 298 . 298 . 299 . 299 . 301 . 302 . 303 . 304 . 305 . 306 . 307 . 307 . 308 . 308 . 309 . 309 . 309 . 309 . 309 . 310 . 310 . 310 . 310 . 311 . 312 . 312 . 312 . 313 . 313 . 315 . 317 . 317 . 317 . 317 . 318 . 319 . 319 . 320 . 320 . 321 . 321 . 323 . 324 . 324 .

x

3 Aug 2007

Drupal Handbook

Topics, categories and terms . . . . . . . . . Permissions . . . . . . . . . . . . . Moderation and the submission queue . . . . . . . Creating comments . . . . . . . . . . . Alternative ways to enter content . . . . . . . . HOWTO: Posting and editing blog entries with TextMate . Posting and editing content with w.bloggar . . . . . Posting content with mailhandler . . . . . . . Preparing content offline . . . . . . . . . Editing and deleting content . . . . . . . . . . Search . . . . . . . . . . . . . . . Beyond the basics . . . . . . . . . . . . Sports . . . . . . . . . . . . . . . . football . . . . . . . . . . . . . . . Best practices guidelines . . . . . . . . . . . Back up your Drupal site . . . . . . . . . . Backing up the database . . . . . . . . . . Backing up the core files . . . . . . . . . . Backing up the non-core files . . . . . . . . . Test your backups . . . . . . . . . . . . Backup and restore using bash shell scripts . . . . . Functional Overview . . . . . . . . . . Usage notes and cautions . . . . . . . . . Site backup script . . . . . . . . . . . Usage notes and warnings: . . . . . . . . fullsitebackup.sh . . . . . . . . . . . Updated fullsitebackup.sh . . . . . . . . Site restore script . . . . . . . . . . . Usage notes and warnings: . . . . . . . . fullsiterestore.sh . . . . . . . . . . . Updated fullsiterestore.sh . . . . . . . . . Accounts and roles . . . . . . . . . . . . Configuring Apache and PHP for Drupal in a Shared Environment Creating a Test Site workflow . . . . . . . . . File and directory management . . . . . . . . . Other Tips . . . . . . . . . . . . . Test Sites . . . . . . . . . . . . . . Version update considerations . . . . . . . . . Do not modify core Drupal . . . . . . . . . . Security . . . . . . . . . . . . . . . Test php before putting it in blocks . . . . . . . . HowTo: The Advanced users guide . . . . . . . . HowTo: enable Imagemagick for the Image module . . . . Tips and Tricks . . . . . . . . . . . . . August 2005: Upgrade, Play B-I-N-G-O!, & E-commerce . . UPGRADE . . . . . . . . . . . . . PLAY B-I-N-G-O! . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

324 . 324 . 325 . 325 . 325 . 326 . 327 . 328 . 328 . 328 . 329 . 330 . 331 . 331 . 332 . 332 . 332 . 333 . 333 . 334 . 334 . 334 . 334 . 335 . 335 . 336 . 338 . 340 . 341 . 341 . 344 . 346 . 347 . 348 . 352 . 353 . 353 . 353 . 354 . 355 . 355 . 356 . 357 . 357 . 357 . 357 . 358 .

xi

Drupal Handbook

3 Aug 2007

E-COMMERCE . . . . . . . . . . . . . . . . . 358 . Commentator array . . . . . . . . . . . . . . . . 358 . June 2005: Custom Content Types, WYSIWIG Editors, Organize Your Content & Quick Support . . . . . . . . . . . . . . . . . . . 359 . September 2005: Newest modules, Change any string, Remote authentication, and tracking project issues . . . . . . . . . . . . . . . . 360 . Get the newest modules -- fast! . . . . . . . . . . . . . 360 . Change any string . . . . . . . . . . . . . . . . 360 . Remote authentication . . . . . . . . . . . . . . . 360 . Keep tabs on project issues . . . . . . . . . . . . . . 361 . Winter 2005/2006: Tracking projects with RSS and Module Linking . . . . . 361 . Planning a web site . . . . . . . . . . . . . . . . . 361 . Server tuning considerations . . . . . . . . . . . . . . . 365 . Identifying Drupal performance goals . . . . . . . . . . . . 365 . Analysing your sites traffic and resource consumption . . . . . . . . 365 . Understanding and configuring your stack for performance . . . . . . 365 . Enable default 404 handling for some file types . . . . . . . . . . 367 . Simple Decision Tree for Drupal Enterprise Scalability . . . . . . . . 368 . Slow contributed modules determined using the developer module . . . . . 369 . Squid Caching . . . . . . . . . . . . . . . . . 369 . Tools, tips, and links on optimizing mysql . . . . . . . . . . . 370 . Tuning MySQL for Drupal . . . . . . . . . . . . . . 372 . Tuning PHP . . . . . . . . . . . . . . . . . . 372 . Persistent database connections . . . . . . . . . . . . . 373 . PHP caches . . . . . . . . . . . . . . . . . . 373 . APC : Alternative PHP Cache . . . . . . . . . . . . . 374 . eAccelerator . . . . . . . . . . . . . . . . . 374 . Turck MMCache . . . . . . . . . . . . . . . . 374 . Useful article on optimizing PHP . . . . . . . . . . . . . 376 . Tuning Drupal on OS X Tiger . . . . . . . . . . . . . . 376 . Upgrading from previous versions . . . . . . . . . . . . . . 378 . Introduction to upgrading . . . . . . . . . . . . . . . 378 . Getting started: Choosing your method and preparing the site . . . . . . 378 . Preparing the site . . . . . . . . . . . . . . . . 379 . Do I need to upgrade my database? . . . . . . . . . . . . 379 . Important! : Backing up the database and existing files . . . . . . . . 379 . Backing up your site (GUI) . . . . . . . . . . . . . . 379 . Back up your site (command line) . . . . . . . . . . . . 380 . Create a test site first or upgrade your existing site? . . . . . . . . 381 . Copy your live site to a test site (GUI) . . . . . . . . . . . 381 . Copying your live site to a test site (command line) . . . . . . . . 382 . Downloading Drupal and installing the files . . . . . . . . . . 384 . Downloading Drupal and installing the files (GUI) . . . . . . . . 384 . Downloading Drupal and installing the files (command line) . . . . . . 385 . Running update.php . . . . . . . . . . . . . . . . 386 . Optional configuration steps . . . . . . . . . . . . . . 387 . Post-upgrade steps . . . . . . . . . . . . . . . . 388 .

xii

3 Aug 2007

Drupal Handbook

Testing Your Newly Upgraded Site . . . . . . . . Copy your test site to a live site . . . . . . . . . Copying your test site to your live site (command line) . . . Copy your test site to a live site (GUI) . . . . . . . Differences from 4.7 to 5.x . . . . . . . . . . . Important note on upgrading from 4.7 to 5.1 . . . . . . Important note on upgrading from 4.7 to 5.1 . . . . . . Version specific upgrades . . . . . . . . . . . Upgrading from Drupal 4.4 to 4.5 . . . . . . . . . Upgrading from Drupal 4.5 to 4.6.3 . . . . . . . . Before you Start . . . . . . . . . . . . . Step-by-step Upgrade from Drupal 4.5 to 4.6.3 . . . . . Finalising your upgrade . . . . . . . . . . . Rebuilding your Drupal Search Index. . . . . . . . Blocks . . . . . . . . . . . . . . . . Permissions . . . . . . . . . . . . . . Forums . . . . . . . . . . . . . . . Images . . . . . . . . . . . . . . . Events . . . . . . . . . . . . . . . Upgrading from Drupal 4.6.3 to 4.6.5 . . . . . . . . Before you Start . . . . . . . . . . . . . Step-by-step Upgrade from Drupal 4.6.3 to 4.6.5 . . . . . Upgrading from Drupal 4.6.4 to 4.6.5 . . . . . . . . Before you Start . . . . . . . . . . . . . Step-by-step Upgrade from Drupal 4.6.4 to 4.6.5 . . . . . Differences from 4.6 to 4.7 . . . . . . . . . . . Block visibility settings . . . . . . . . . . . Configure options centralized . . . . . . . . . . core module help text linked to the handbook now . . . . . Creating context sensitive menus with primary and secondary menus Dont turn off contributed modules that provide an .install file . . Module .install files . . . . . . . . . . . . Primary/secondary links now part of the menu system . . . . queue module removed from core . . . . . . . . . Removal of base href statement from header . . . . . . Some HTML Tags stripped from mission statement . . . . XTemplate engine removed from core . . . . . . . . Troubleshooting FAQ . . . . . . . . . . . . . How to troubleshoot (read this first) . . . . . . . . . Stop and think . . . . . . . . . . . . . Read the errors . . . . . . . . . . . . . Validate your page . . . . . . . . . . . . Read the README . . . . . . . . . . . . Search the right way . . . . . . . . . . . . Identify the source of the problem . . . . . . . . . Dump some diagnostics . . . . . . . . . . . Ask the right questions . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

388 . 389 . 390 . 390 . 391 . 391 . 392 . 392 . 392 . 393 . 394 . 394 . 396 . 396 . 396 . 396 . 397 . 397 . 397 . 397 . 398 . 398 . 398 . 398 . 399 . 399 . 399 . 399 . 400 . 400 . 400 . 401 . 401 . 401 . 402 . 403 . 403 . 404 . 404 . 404 . 404 . 405 . 405 . 405 . 406 . 406 . 407 .

xiii

Drupal Handbook

3 Aug 2007

Identify the module thats giving you problems . . . . . . . . My admin > modules page is blank . . . . . . . . . . . . How do I get the User Login block back . . . . . . . . . . . Client does not support authentication protocol requested by server... . . . . Webhosting issues for new Drupal users . . . . . . . . . . . Brief intro to Unix file permissions . . . . . . . . . . . . Host-specific error messages . . . . . . . . . . . . . SELinux may cause mysterious permission problems . . . . . . . Typical webhosting setups . . . . . . . . . . . . . Using PHP to change files on the webserver . . . . . . . . . What do all those Unix commands mean? . . . . . . . . . . Some Unix command youll see mentioned: . . . . . . . . . Special characters: . . . . . . . . . . . . . . . What permissions does Drupal need? . . . . . . . . . . . Why is this uploading stuff so difficult? . . . . . . . . . . "Headers already sent" error . . . . . . . . . . . . . . "LOCK TABLES sequences WRITE" error . . . . . . . . . . "Method POST is not allowed for the URL /index.htm" error (Error 405) . . . "Page Not Found" error when trying to access a subdirectory . . . . . . Block referrer spam . . . . . . . . . . . . . . . . .htaccess sample list plus domain blocking . . . . . . . . . . Color picker doesnt appear on theme configuration page . . . . . . . Drupal 4.7 Install inserts CGI-BIN in URL . . . . . . . . . . Duplicate entry error . . . . . . . . . . . . . . . E-Mail from Drupal is bouncing or not being sent . . . . . . . . Relay SMTP mail to external mail server using smtp.class . . . . . . Error 1364 upon importing database.mysql with MySQL 5.0+ . . . . . . Error on installation step 3: Warning: Table [database].access doesnt exist [...] . Fatal error: Allowed memory size of X bytes exhausted (tried to allocate Y bytes)... Fatal error: Call to undefined function . . . . . . . . . . . Fatal error: Call to undefined function: form_*() on Drupal 4.7 . . . . . Fatal error: Cannot redeclare blah_function() in ../modules/blah.module . . . Forgotten your Drupal account password . . . . . . . . . . Forum overview stopped working . . . . . . . . . . . . The Fix . . . . . . . . . . . . . . . . . . FTP uploads and file permissions using Transmit . . . . . . . . . Help! I enabled a buggy module and now I cant disable it! . . . . . . How can I adminstrate my navigation on my Drupal site? (version 4.5 or older) . How do I get rid of the "Welcome to your new Drupal website" on the front page? . How do I get the Navigation block back . . . . . . . . . . . How do I unset the clean URLs? . . . . . . . . . . . . . How to login once you have turned your site off-line for maintenance . . . . HOWTO: Download a fresh copy of a missing or corrupted module/image/file . Installation/configuration . . . . . . . . . . . . . . 406 Error when XMLRPC is used . . . . . . . . . . . . Junk {head} {styles} codes as output . . . . . . . . . . . . Login after disabling the User login block . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

407 . 407 . 408 . 408 . 409 . 409 . 411 . 411 . 412 . 413 . 413 . 413 . 414 . 414 . 416 . 416 . 417 . 417 . 418 . 418 . 419 . 420 . 420 . 421 . 423 . 423 . 424 . 425 . 426 . 426 . 426 . 427 . 427 . 428 . 428 . 429 . 429 . 429 . 431 . 432 . 432 . 432 . 433 . 434 . 434 . 434 . 435 .

xiv

3 Aug 2007

Drupal Handbook

Login doesnt work or must be done twice . . . . . . . . . . . Cookies . . . . . . . . . . . . . . . . . . . Cache Problems . . . . . . . . . . . . . . . . . Logging in at www on a site with no www in the baseurl . . . . . . . Login problems on PHP 5.2 . . . . . . . . . . . . . . . My layout collapses - content appears below left column (IE) or overflows over the right (FF) . . . . . . . . . . . . . . . . . . . . . The content is too wide for the space its been given . . . . . . . . Validation Woes . . . . . . . . . . . . . . . . . Mysterious 403, 404, 406 or 500 errors depending on submitted content . . . . Permission denied in includes/file.inc . . . . . . . . . . . . Persistent Welcome to Drupal for anonymous users . . . . . . . . . phpinfo . . . . . . . . . . . . . . . . . . . . Plain unstyled HTML output . . . . . . . . . . . . . . Setting up Clean URLs . . . . . . . . . . . . . . . . unblocking account through SQL . . . . . . . . . . . . . Weird behaviour - module-theme name collision . . . . . . . . . . Where is the taxonomy choice when adding content? . . . . . . . . . Miscellaneous . . . . . . . . . . . . . . . . . . How can I change Drupals character encoding? (UTF-8 and Unicode) . . . .

435 . 435 . 435 . 436 . 436 . 436 . 437 . 437 . 438 . 438 . 439 . 440 . 440 . 441 . 442 . 442 . 442 . 443 . 443 .

xv

3 Aug 2007

Drupal Handbook

Installation and configurationHere is a guide for installing and configuring a Drupal site. This guide includes extensive How-tos for using all core modules and installing themes. It also includes a guide for end users, the people who visit a Drupal site. Note: Feel free to add handbook pages relevant to this section.

1

Drupal Handbook

3 Aug 2007

System requirements1. A Web Server that can execute PHP scripts 2. Recommended: Apache. Drupal will work on Apache 1.3 or Apache 2.x hosted on Unices or Windows. The majority of Drupal development is done using Apache so there is more community experience and testing performed. Optional: You can use the Apache extension mod_rewrite to allow for clean urls. Optional: IIS Drupal core will work using IIS5 or IIS6 if PHP is configured correctly. You will need to use a third party solution to achieve Clean URLs. In view of Microsofts support life cycle it is suggested you use IIS6. To achieve clean_urls you will need to use a third party product. Drupal is being developed to be web server independent but we have limited or no reports of successful use on web servers not listed here. 3. PHP 4. Drupal 4.7 and above require PHP version 4.3.3 or higher. PHP 5.2 is a special case; only Drupal 4.7.5 (and greater) and 5.0 (and greater) run on PHP 5.2, older Drupal versions do not. We recommend using the latest version of PHP 4.x. or 5.x for security and future compatibility. PHP memory of approximately 8MB for a Drupal core installation. In reality you will probably need to use a higher setting depending on your site and contributed modules you are using. A good starting point is 16-24 MB. PHP XML extension (for blogapi, drupal, and ping modules). This extension is enabled by default in a standard PHP installation; the windows version of PHP has built-in support for this extension. PHP needs the following configuration directives for Drupal to work (only directives that differ from the default php.ini-dist / php.ini-recommended): session.save_handler: user error_reporting set to E_ALL & ~E_NOTICE. Work is ongoing to change this to E_ALL for Drupal 6. In addition, we recommend the following settings: session.cache_limiter: none Some of these settings are contained in the default .htaccess file that ships with Drupal, so you shouldnt need to set them explicitly. Note, however, that setting PHP configuration options from .htaccess only works: with Apache (or a compatible web server),

2

3 Aug 2007

Drupal Handbook

if the .htaccess file is actually read, i.e. AllowOverride is not None, if PHP is installed as an Apache module. See the PHP manual for how to change configuration settings for other interfaces to PHP. 5. A PHP-supported Database Server 6. Recommended: MySQL 4.1 or MySQL 5.0. Drupal will work on v3.23.17 and 4.0 but it is strongly suggested you use 4.1 or 5.0 for future compatibility with Drupal 6 which will drop support for older versions of MySQL. NOTE: Drupal makes use of some features not available on some inexpensive hosting plans so please check that your host allows database accounts with the following rights: SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES Note: If your system/host is running MySQL 4.1 or newer and you receive the error "Client does not support authentication protocol requested by server", address the problem by following the instructions provided by MySQL AB. There is a minor OS issue with some MySQL 5+ installations primarily on Windows but affecting some Unices as well. PostgreSQL, version 7.3 or newer. Note, some of the contributed modules are not as abstracted from MySQL specific code as everyone would like. If you are familiar with PostgreSQL please file issues with those contributed modules as you find them. Currently MS SQL and Oracle are not supported but various efforts are underway to supply schemas. Please see discussions in the Enterprise Group if you are interested in working on this.

Client System RequirementsDrupal aims to conform with internet standards and deviate where necessary to comply with popular clients that are not standards compliant.

JavascriptFor the Javascript, we currently test for all required API features (DOM APIs) and based on that, enabled or disable all JS functionality. That way, we dont care about particular browsers, only what they support.

3

Drupal Handbook

3 Aug 2007

CSSFor CSS, the situation is quite similar to Javascript. The only difference is that here there is a strong difference between the standard compliant browsers and Internet Explorer. We can use CSS2 where needed and provide IE6 workarounds if necessary.

RSSDrupal RSS feeds should work with any RSS feed reader. (note: could use more information).

Browser SpecificsIn practice, this means that IE6, FF1.0/1.5, Opera 8-9 and Safari 1.x/2.0 get the whole experience. Konqueror should work if its the latest version.

Browser PopularityThe general net usage is 85% IE, 10% Ffox, 3% Safari, 2% Opera or so. For Drupal.org, it is 50% Ffox/Moz, 30% IE, 20% other.

Known ProblemsIE5 and IE5.5 will experience some layout issues. IE5.0 will not do any Javascript. We can assume that for Firefox and Opera, the users have a high chance of running the latest version. IE4 and NS4, we no longer care about because they are no longer maintained and they are not in widespread use.

ValidationDrupal HTML and RSS should validate using the W3C Markup Validation Service.

CaveatsThese guidelines are the guide for Drupal core, modules, and themes but are not always completely accurate. In practice, Drupal Core is expected to follow these standards more closely than various contributed pieces of code. If you find a problem with client compatability that deviates from the above client support guidelines, please try to find the root of the problem and submit an issue ideally including a patch to fix the problem.

4

3 Aug 2007

Drupal Handbook

HOWTO: Server requirement recommendations for your consulting clientsWhen thinking about the server hardware for a Drupal site, there are two important questions to ask: 1. Which modules are you going to use? Certain modules require more server power than others, but generally speaking more modules means more server requirements. 2. How many users will you have and what will they be doing? More users means more of a demand on the server, but especially if these users login and make comments or nodes you will need a more powerful server. You need to consider these two answers together. For example, you could have a highly complex site with very few users and be able to use a shared hosting environment. You could also use very few modules, only have one editor, use the cache, and have reasonable traffic on a shared environment. If your project is a more interactive environment with more users logging in and posting to the site you will need to consider more powerful hardware. As you move out of a shared environment there are other options available to you like using the methods described in the handbook to Tune Your Server for optimal Drupal performance. Tuning the server may allow you to continue using the same hardware and not upgrade, but it comes at the cost of time which can be more expensive than simply buying new hardware. When deciding which parts of your server to upgrade, remember that "Apache is bandwidth limited, PHP is CPU limited, and MySQL is memory limited and disk I/O bound".

Message to the ClientIts probably best to give the message to the client of a "recommended" installation and a level below that in case their budget is limited and a level above that to provide for future growth with purchasing new hardware and services. If you are rolling out a new service (as opposed to installing Drupal in place of an existing solution) keep an eye towards a solid upgrade path. You can purchase a single server with the intent of upgrading as your site grows. For example, start with the web server and database on one server that is optimized for web serving. As the site grows in popularity and you need to handle more users you can then move the database to its own server separate from the web server. If your site grows beyond a two server "web server" and "database server" configuration then you can consider using a single web server and multiple database servers in a cluster.

5

Drupal Handbook

3 Aug 2007

BenchmarkOne benchmark of a server is MBR.org which required serious intervention for optimisation at roughly the 2m pages per month mark, on a server running Apache1.3 and MySQL 4.1 with 1GB of memory. MySQL indexing, database memory use tweaks and abandoning MyISAM for InnoDB brought it under control - the jurys out on using persistent connections. There is a need for more case studies like this to be documented on this handbook page

What Drupal.org runs onAs of April 2007 (and for a long time before that) Drupal.org has been running on a group of 3 servers. For details on those servers see Dries post about the "future" drupal.org hardware as it was being delivered.

Requirements - older versions1. A Web Server that can execute PHP scripts 2. Recommended: Apache. Development is done with version 1.3.x. Successfully tested with version 2.0.x. Optional: IIS. Drupal is being developed with IIS compatibility in mind, and IIS5 and IIS6 work with a correctly configured PHP setup. 3. PHP 4. As of Drupal 4.6, the CMS requires PHP version 4.3.3+ (PHP 5 is supported for the 4.6 release). Drupal 4.2 to 4.5.2 inclusive require PHP version 4.1+. Older versions of Drupal will run on PHP 4.0.6+. We recommend using the latest version of PHP 4.x. PHP XML extension (for blogapi, drupal, and ping modules). This extension is enabled by default in a standard PHP installation; the windows version of PHP has built-in support for this extension. PHP memory of 8MB for a Drupal core install. If you install additional contributed modules you may need to raise your php allowed memory. Prepackaged Drupal distributions such as CivicSpace may have higher PHP memory requirements then a Drupal core install. PHP needs the following configuration directives for drupal to work: session.save_handler: user In addition, we recommend the following settings: session.cache_limiter: none (We only mention directives that differ from the default php.ini-dist / php.ini-recommended starting with PHP 4.0.6) These settings are contained in the default .htaccess file that ships with Drupal, so you shouldnt need to set them explicitly. Note, however, that setting PHP configuration options from .htaccess only works:

6

3 Aug 2007

Drupal Handbook

with Apache (or a compatible web server), if the .htaccess file is actually read, i.e. AllowOverride is not None, if PHP is installed as an Apache module. See here for how to change configuration settings for other interfaces to PHP. Using a PEAR-supported Database (see below) requires (of course) PEAR to be installed. A PHP-supported Database Server Recommended: MySQL, v3.23.17 or newer (for our use of INNER JOINs with join_conditions). MySQL 4 is fine. Drupal makes use of features not available on some inexpensive hosting plans, like LOCK TABLE Working well since 4.7: PostgreSQL, version 7.3 or newer (7.2 will probably work too, but youll get some errors when updating from 4.6). Experiences with other databases are greatly welcome. Note: If your system/host is running MySQL 4.1 or newer, a link in the troubleshooting section (http://drupal.org/node/35226) points to this page, which has some helpful info on addressing this problem with PHP 4.x and PHP5. There is a minor OS issue with some MySQL 5+ installations primarily on Windows but affecting some *nix installs as well. Also, xTemplate (the default theme engine for Drupal 4.6.x and previous) is reported to have issues with PHP 5.0.5 and 5.1. Converting your themes to the phpTemplate engine (default in 4.7) will work around this issue.

7

Drupal Handbook

3 Aug 2007

Installing Drupal, modules and themesInstalling Drupal, new modules and themes uses roughly the same process so once you are familiar with it you can repeat as needed. After you successfully install Drupal, you will want to perform some basic site configuration starting with the settings menu. Installing and configuring your site is only part of your responsibilities. You must remember to backup, test and maintain it as well. Please stop by the Best Practices section for some important tips on this and sign up for the security newsletter

Installing DrupalThis page is autogenerated from the current development text in CVS. See the various other provided instructions linked in the menu on the left for additional environments. // $Id: INSTALL.txt,v 1.39 2007/01/08 11:59:16 dries Exp $ CONTENTS OF THIS FILE --------------------* Changes * Requirements * Optional requirements * Installation * Drupal administration * Customizing your theme(s) * Multisite Configuration * More Information CHANGES ------As of Drupal 5.0 installation has been automated by an install script. It is no longer necessary to manually edit the "settings.php" file, and database tables are created automatically. REQUIREMENTS -----------Drupal requires a web server, PHP4 (4.3.3 or greater) or PHP5 (http://www.php.net/) and either MySQL (http://www.mysql.com/) or PostgreSQL (http://www.postgresql.org/). The Apache web server and MySQL database are recommended; other web server and database combinations such as IIS and PostgreSQL have been tested to a lesser extent. When using MySQL, version 4.1 or greater is recommended to assure you can safely transfer the database.

8

3 Aug 2007

Drupal Handbook

For more detailed information about Drupal requirements, see "Requirements" (http://drupal.org/requirements) in the Drupal Handbook. Guidelines for setting up a server environment with a variety of operating systems and in special cases are available in the Drupal handbook (http://drupal.org/node/260) OPTIONAL REQUIREMENTS --------------------- To use XML-based services such as the Blogger API, Jabber, and RSS syndication, you will need PHPs XML extension. This extension is enabled by default. - If you want support for clean URLs, youll need mod_rewrite and the ability to use local .htaccess files. INSTALLATION -----------1. DOWNLOAD 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. On a typical Unix command line, use: wget http://drupal.org/files/projects/drupal-x.x.tar.gz tar -zxvf drupal-x.x.tar.gz This will create a new directory drupal-x.x/ containing all Drupal files and directories. Move the contents of that directory into a directory within your web servers document root or your public HTML directory: mv drupal-x.x/* drupal-x.x/.htaccess /var/www/html 2. CREATE THE DRUPAL DATABASE Drupal requires access to a database in order to be installed. Your database user will need sufficient privileges to run Drupal. Additional information about privileges, and instructions to create a database using the command line are available in INSTALL.mysql.txt (for MySQL) or INSTALL.pgsql.txt (for PostgreSQL). To create a database using PHPMyAdmin or a web-based control panel consult the documentation or ask your webhost service provider. Take note of the username, password, database name and hostname as you

9

Drupal Handbook

3 Aug 2007

create the database. You will enter these items in the install script. 3. RUN THE INSTALL SCRIPT The install script will set the base URL, connect Drupal to the database, and create tables in the database. To run the install script point your browser to the base url of your website (i.e. http://www.example.com). You will be presented with the "Database Configuration" page. The install script will attempt to write-protect the settings.php after updating it with the information you provide in the installation routine. If you make manual changes to that file later, be sure to protect it again after making your modifications. Failure to remove write permissions to that file is a security risk. The default location for the settings.php file is at sites/default/settings.php, but it may be in another location if you use the multi-site setup, as explained below. 4. CONFIGURE DRUPAL When the install script succeeds, you will be directed to the "Welcome" page. In "step one" click "create the first account" which will become the main administrator account with total control. Login as the administrator and complete the initial configuration steps on the "Welcome" page. Consider creating a "files" subdirectory in your Drupal installation directory. This subdirectory stores files such as custom logos, user avatars, and other media associated with your new site. The sub-directory requires "read and write" permission by the Drupal server process. You can change the name of this subdirectory at "administer > site configuration > file system". 5. CRON TASKS Many Drupal modules (such as the search functionality) have periodic tasks that must be triggered by a cron job. To activate these tasks, call the cron

10

3 Aug 2007

Drupal Handbook

page by visiting http://www.example.com/cron.php --this will pass control to the modules and the modules will decide if and what they must do. Most systems support the crontab utility for scheduling tasks like this. The following example crontab line will activate the cron tasks automatically on the hour: 0 * * * * wget -O - -q http://www.example.com/cron.php More information about the cron scripts are available in the admin help pages and in the Drupal handbook at drupal.org. Example scripts can be found in the scripts/ directory. DRUPAL ADMINISTRATION --------------------A new installation of Drupal defaults to a very basic configuration with only a few active modules and minimal user access rights. Use your administration panel to enable and configure services. For example: General Settings administer > site configuration > site information Enable Modules administer > site configuration > modules Set User Permissions administer > users management > access control Configure Themes administer > site building > themes For more information on configuration options, read the instructions which accompany the different configuration settings and consult the various help pages available in the administration panel. Community-contributed modules and themes are available at http://drupal.org/. CUSTOMIZING YOUR THEME(S) ------------------------Now that your installation is running, you will want to customize the look of your site. Several sample themes are included and more can be downloaded from drupal.org. Simple customization of your theme can be done using only CSS. Further changes require understanding the phptemplate engine that is now part of Drupal. See http://drupal.org/handbook/customization to find out more. MULTISITE CONFIGURATION -----------------------

11

Drupal Handbook

3 Aug 2007

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 sites 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

12

3 Aug 2007

Drupal Handbook

a real subdomain. Each site configuration can have its own site-specific modules and themes in addition to those installed in the standard modulesand 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. MORE INFORMATION ---------------For platform specific configuration issues and other installation and administration assistance, please consult the Drupal handbook at http://drupal.org/handbook. You can view the wide range of other support options available at http://drupal.org/support.

Formatted Drupal 5.x Installation instructions for better readabilityInstallation// $Id: INSTALL.txt,v 1.39 2007/01/08 11:59:16 dries Exp $ Table of Contents 1. 2. 3. 4. 5. 6. 7. 8. Changes Requirements Optional requirements Installation Drupal administration Customizing your theme(s) Multisite Configuration More Information

13

Drupal Handbook

3 Aug 2007

ChangesAs of Drupal 5.0 installation has been automated by an install script. It is no longer necessary to manually edit the "settings.php" file, and database tables are created automatically.

RequirementsDrupal requires a web server, PHP4 (4.3.3 or greater) or PHP5 (http://www.php.net/) and either MySQL (http://www.mysql.com/) or PostgreSQL (http://www.postgresql.org/). The Apache web server and MySQL database are recommended; other web server and database combinations such as IIS and PostgreSQL have been tested to a lesser extent. When using MySQL, version 4.1 or greater is recommended to assure you can safely transfer the database. For more detailed information about Drupal requirements, (http://drupal.org/requirements) in the Drupal Handbook. see "Requirements"

Guidelines for setting up a server environment with a variety of operating systems and in special cases are available in the Drupal handbook (http://drupal.org/node/260)

Optional Requirements- To use XML-based services such as the Blogger API, Jabber, and RSS syndication, you will need PHPs XML extension. This extension is enabled by default. - If you want support for clean URLs, youll need mod_rewrite and the ability to use local .htaccess files.

Installation1. Download 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. On a typical Unix command line, use: wget http://drupal.org/files/projects/drupal-x.x.tar.gz tar -zxvf drupal-x.x.tar.gz This will create a new directory drupal-x.x/ containing all Drupal files and directories. Move the contents of that directory into a directory within your web servers document root or your public HTML directory: mv drupal-x.x/* drupal-x.x/.htaccess /var/www/html 2. Create the Drupal database Drupal requires access to a database in order to be installed. Your database user will need sufficient privileges to run Drupal. Additional information about privileges, and instructions to create a database using the command line are available in INSTALL.mysql.txt (for MySQL) or

14

3 Aug 2007

Drupal Handbook

INSTALL.pgsql.txt (for PostgreSQL). To create a database using PHPMyAdmin or a web-based control panel consult the documentation or ask your webhost service provider. Take note of the username, password, database name and hostname as you create the database. You will enter these items in the install script. 3. Run the install script The install script will set the base URL, connect Drupal to the database, and create tables in the database. To run the install script point your browser to the base url of your website (i.e. http://www.example.com). You will be presented with the "Database Configuration" page. The install script will attempt to write-protect the settings.php after updating it with the information you provide in the installation routine. If you make manual changes to that file later, be sure to protect it again after making your modifications. Failure to remove write permissions to that file is a security risk. The default location for the settings.php file is at sites/default/settings.php, but it may be in another location if you use the multi-site setup, as explained below. 4. Configure Drupal When the install script succeeds, you will be directed to the "Welcome" page. In "step one" click "create the first account" which will become the main administrator account with total control. Login as the administrator and complete the initial configuration steps on the "Welcome" page. Consider creating a "files" subdirectory in your Drupal installation directory. This subdirectory stores files such as custom logos, user avatars, and other media associated with your new site. The sub-directory requires "read and write" permission by the Drupal server process. You can change the name of this subdirectory at "administer > site configuration > file system". 5. Cron Tasks Many Drupal modules (such as the search functionality) have periodic tasks that must be triggered by a cron job. To activate these tasks, call the cron page by visiting http://www.example.com/cron.php --this will pass control to the modules and the modules will decide if and what they must do. Most systems support the crontab utility for scheduling tasks like this. The following example crontab line will activate the cron tasks automatically on the hour: 0 * * * * wget -O - -q http://www.example.com/cron.php

More information about the cron scripts are available in the admin help pages and in the Drupal handbook at drupal.org. Example scripts can be found in the scripts/ directory.

15

Drupal Handbook

3 Aug 2007

Drupal AdministrationA new installation of Drupal defaults to a very basic configuration with only aw active modules and minimal user access rights. Use your administration panel to enable and configure services. For example: General Settings administer > site configuration > site information Enable Modules administer > site configuration > modules Set User Permissions administer > users management > access control Configure Themes administer > site building > themes For more information on configuration options, read the instructions which accompany the different configuration settings and consult the various help pages available in the administration panel. Community-contributed modules and themes are available at http://drupal.org/.

Customizing your theme(s)Now that your installation is running, you will want to customize the look of your site. Several sample themes are included and more can be downloaded from drupal.org. Simple customization of your theme can be done using only CSS. Further changes require understanding the phptemplate engine that is now part of Drupal. See http://drupal.org/handbook/customization to find out more.

Multi-site configurationA 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 sites 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

16

3 Aug 2007

Drupal Handbook

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 modulesand 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.

More InformationFor platform specific configuration issues and other installation and administration assistance, please consult the Drupal handbook at http://drupal.org/handbook. You can view the wide range of other support options available at http://drupal.org/support.

Formatted Drupal 4.7.x Installation instructions for better readabilityInstallation// $Id: INSTALL.txt,v 1.6 2004/11/27 11:28:55 dries Exp $ This document outlines the standard installation process.

17

Drupal Handbook

3 Aug 2007

1. 2. 3. 4. 5. 6. 7. 8.

REQUIREMENTS SERVER CONFIGURATION OPTIONAL COMPONENTS INSTALLATION DRUPAL ADMINISTRATION CUSTOMIZING YOUR THEME(S) UPGRADING MORE INFORMATION

REQUIREMENTS1. Drupal requires a web server, PHP4 (http://www.php.net/) and either MySQL, PostgreSQL or a database server supported by the PHP PEAR API (http://pear.php.net/). 2. To Install you will need an FTP program to upload files to the server, or shell access if you wish to install using the commands listed below; access to run database scripts directly or a tool such as PHPMyAdmin to manage a database; knowledge of how to use either FTP programs or shell access to set permissions on directories, and how to run database scripts. 3. NOTE: The Apache web server and MySQL database are strongly recommended; other web server and database combinations such as IIS and PostgreSQL are possible but tested to a lesser extent.

SERVER CONFIGURATIONYour PHP must have the following settings: session.save_handler user

In addition, we recommend the following settings: session.cache_limiter none

These values are set in php.ini and can be overwritten in a .htaccess file; you can print out your local PHP settings with PHPs phpinfo() function.

OPTIONAL COMPONENTSTo use XML-based services such as the Blogger API, Jabber, RSS syndication, you will need PHPs XML extension. This extension is enabled by default in standard PHP4 installations. If you want support for clean URLs, youll need mod_rewrite and the ability to use local .htaccess files. (More information can be found in the Drupal handbook on drupal.org.)

18

3 Aug 2007

Drupal Handbook

INSTALLATION1. DOWNLOAD DRUPALYou can obtain the latest Drupal release from http://drupal.org/. Download the current tar.gz format and extract the files: $ wget http://drupal.org/files/project/drupal-x.x.x.tgz $ tar -zxvf drupal-x.x.x.tgz This will create a new directory drupal-x.x.x/ containing all Drupal files and directories. Move the contents of that directory into a directory within your web servers document root or your public HTML directory: $ mv drupal-x.x.x/* drupal-x.x.x/.htaccess /var/www/html

2. CREATE THE DRUPAL DATABASEThese instructions are for MySQL. If you are using another database, check the database documentation. In the following examples, "dba_user" is an example MySQL user which has the CREATE and GRANT privileges. You will need to use the appropriate user name for your system. First, you must create a new database for your Drupal site: $ mysqladmin -u dba_user -p create drupal MySQL will prompt for the dba_user database password and then create the initial database files. Next you must login and set the access database rights: $ mysql -u dba_user -p Again, you will be asked for the dba_user database password. At the MySQL prompt, enter following command: GRANT ALL PRIVILEGES ON drupal.* TO nobody@localhost IDENTIFIED BY password; where drupal is the name of your database nobody@localhost is the userid of your webserver MySQL account password is the password required to log in as the MySQL user

19

Drupal Handbook

3 Aug 2007

If successful, MySQL will reply with Query OK, 0 rows affected to activate the new permissions you must enter the command flush privileges; and then enter \q to exit MySQL.

3. LOAD THE DRUPAL DATABASE SCHEMEOnce you have a database, you must load the required tables: $ mysql -u nobody -p drupal < database/database.mysql

4. CONNECTING DRUPALThe default configuration can be found in the sites/default/settings.php file within your Drupal installation. Before you can run Drupal, you must set the database URL and the base URL to the web site. Open the configuration file and edit the $db_url line to match the database defined in the previous steps: $db_url = "mysql://username:password@localhost/drupal"; Set $base_url to match the address to your web site: $base_url = "http://www.example.com"; In addition, a single Drupal installation can host several Drupal-powered sites, each with its own individual configuration. If you dont need to run multiple Drupal sites, you can skip to the next section. Additional site configurations are created in subdirectories within the sites directory. Each site 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 sites 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 each have to have a different domain. You can use subdomains and subdirectories for Drupal sites also. For example, example.com, sub.example.com, and sub.example.com/site3 can all be

20

3 Aug 2007

Drupal Handbook

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 file 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 Each site configuration can have its own site-specific modules and themes that will be made available 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.dom 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.

5. CONFIGURE DRUPALYou can now launch your browser and point it to your Drupal site. Create an account and login. The first account will automatically become the main administrator account.

21

Drupal Handbook

3 Aug 2007

6. CRON TASKSMany Drupal modules have periodic tasks that must be triggered by a cron job. To activate these tasks, you must call the cron page; this will pass control to the modules and the modules will decide if and what they must do. The following example crontab line will activate the cron script on the hour: 0 * * * * wget -O - -q http://HOSTNAME/cron.php

More information about the cron scripts are available in the admin help pages and in the Drupal handbook at drupal.org. Example scripts can be found in the scripts/ directory.

DRUPAL ADMINISTRATIONUpon a new installation, your Drupal website defaults to a very basic configuration with only a few active modules, one theme, and no user access rights. Use your administration panel to enable and configure services. For example, set some general settings for your site with "Administration configuration". Enable modules via "Administration - configuration modules". User permissions can be set with "Administration - accounts - permissions". For more information on configuration options, read through the instructions which accompany the different configuration settings and consult the various help pages available in the administration panel. Note that additional community-contributed modules and themes are available at http://drupal.org/.

CUSTOMIZING YOUR THEME(S)Now that your server is running, you will want to customize the look of your site. Several sample themes are included in the Drupal installation and more can be downloaded from drupal.org. Customizing each theme depends on the theme. In general, each theme contains a PHP file themename.theme which defines a function header() that can be changed to reference your own logos.

22

3 Aug 2007

Drupal Handbook

Most themes also contain stylesheets or PHP configuration files to tune the colors and layouts; check the themes/ directory for README files describing each alternate theme.

UPGRADING1. Backup your database and Drupal directory - especially your configuration file (www.example.com.conf or includes/conf.php). 2. Log on as the user with user ID 1. 3. Remove all the old Drupal files then unpack the new Drupal files into the directory that you run Drupal from. 4. Modify the new configuration file to make sure it has the correct information. 5. Run update.php by visiting http://www.example.com/update.php.

MORE INFORMATIONFor platform specific configuration issues and other installation and administration assistance, please consult the Drupal handbook at http://drupal.org/. You can also find support at the Drupal support forum or through the Drupal mailing lists.

10 minute install using PuTTY SSH/Telnet clientIve been developing best practices for my development company and wanted to share/collaborate on some of them. Development environment: Server: LAMP SSH/Telenet Client: PuTTY Server Interface: WHM Must have root access. 10 minute Install: [login root via PuTTY] # cd /home/youraccountname # wget http://ftp.osuosl.org/pub/drupal/files/projects/drupal-x.x.tar.gz [Note: the "x.x" should be replaced with the version of drupal youre installing, e.g. "5.1"] # tar -zxvf drupal-5.1.tar.gz # mv drupal-x.x/* drupal-x.x/.htaccess /home/youraccountname/public_html [Note: See the note above regarding "x.x"]

23

Drupal Handbook

3 Aug 2007

# rm drupal-x.x.tar.gz # cd public_html # mkdir files # chmod 777 files # cd sites/all # mkdir modules # mkdir themes # cd modules # mkdir custom # mkdir drupal-contrib # cd ../ # cd themes # mkdir custom # mkdir drupal-contrib # cd ../ # cd ../ # cd default # chmod 777 settings.php # mysql mysql> CREATE DATABASE youraccountname_drupal; mysql> GRANT ALL PRIVILEGES ON youraccountname_drupal.* TO your accountname_yourusername@localhost IDENTIFIED BY yourpassword; mysql> \q [open your browser. enter your sites URL, and enter database information] [go back to PuTTY to chmod on "settings.php"] # chmod 755 settings.php # logout [back to browser, refresh browser, and then "visit new site" (or whatever the link says to new website), create first "superuser" account, etc.]

How I installed Drupal: The Eightfold WayTry this for a supereasy install. This installation is for a test site. The aim is to have a test site: \http://drupal.yoursite.com\ When the test site is functioning, the drupal subdomain prefix will be deleted. Therefore the domain name in the root will be mysite.com The DNS servers will automatically point to this (hopefully!). This is what worked for me: 1) Downloaded Drupal 5.0 2) Created a subdomain ("drupal") via my webhosts control panel 3) Created a database ("dbname") via my webhosts control panel (note the user name and

24

3 Aug 2007

Drupal Handbook

password). Noted the hostname, e.g., testsite.yoursite.com 4) Using browser, pointed to URL \http://drupal.yoursite.com\ 5) The install.php script automatically installed Drupal 6) Entered information. Database name ("dbname"), username, password 7) Clicked "Advanced options" 8) Entered hostname (e.g., testsite.yoursite.com). Went to testsite.yoursite.com in browser.

Installing virtual hosts for Drupal sites and subsitesThe purpose of this guide is to concisely summarize how to implement apache vhost settings for each site or subsite. All steps for this tutorial were implemented with Debian using Apache version 2.0.54. 1. Gain entrance into your shell system, and su to root or another user that can edit apache2 configuration files. 2. Go to your apache configuration files: cd /etc/apache2/sites-available 3. Create a configuration file for your new site. For an example site, www.example.com, we make the site as such: nano example.com ServerAdmin me@myserver DocumentRoot /home/web/drupal/ ServerName www.example.com ServerAlias example.com *.example.com RewriteEngine On RewriteOptions inherit CustomLog /var/log/apache2/example.com.log combined ServerAdmin me@myserver DocumentRoot /home/web/drupal/ ServerName www.example.com ServerAlias example.com *.example.com RewriteEngine On RewriteOptions inherit CustomLog /var/log/apache2/example.com.log combined # SSL Specific options SSLEngine on SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL SSLCertificateFile /etc/ssl/apache/CA.crt SSLCertificateKeyFile /etc/ssl/apache/CA.key SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown

25

Drupal Handbook

3 Aug 2007

Activate the sites configuration: a2ensite www.example.com Reload Apaches configuration: /etc/init.d/apache2 force-reload Done! Please post any changes or concerns, Tarek : )

Mac OS X-specific guidelinesInstall and configure Mysql and PHP, if necessary. Server Logistics provides nice pre-compiled packages and instructions. PHP is also available from Marc Liyanage. PHP may already be installed on your system, so check first. The stock version of Apache should be fine (typically 1.33). Turn on "personal web sharing" in the sharing panel of System Preferences to start Apache. Now comes the more involved part- changing the webserver configuration. To make changes to the Apache configuration you should NOT edit /etc/httpd/httpd.conf but instead edit files in /private/etc/httpd/users/. Any file in the directory /private/etc/httpd/users/ ending with .conf will effectively be appended to /etc/httpd/httpd.conf. So any changes you want to make should be made in one or more configuration files of your own construction. System updates will leave these files untouched. You can create a file /private/etc/httpd/users/drupal.conf for all your Drupal-specific changes (even if you have no user named Drupal) and they will be loaded when Apache starts up. Note: for Mac OS X Server 10.4 (Tiger Server) and most likely previous versions as well, do not make changes to /etc/httpd/httpd.conf expecting the AllowOverride All directi