installation and configuration - mulb.orgstuff.mulb.org/drupal/installation and upgrading.pdf · 10...

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

i

Drupal Handbook 6 Jun 2007

.......... 2310 minute install using PuTTY SSH/Telnet client

........... 24How I installed Drupal: The Eightfold Way

......... 25Installing virtual hosts for Drupal sites and subsites

............... 26Mac OS X-specific guidelines

............. 27Important notes for MySQL install:

..... 28HOWTO: Create a local server environment for drupal using MAMP

... 29HOWTO: Installing PostgreSQL and MySQL on the same Mac OS X machine

........... 30Installing Drupal on Mac OS X 10.4 Tiger

............ 30Installing and Configuring MySQL

.................. 32Sending mail

......... 32Creating the Drupal Database and Database User

............. 33Installing using CVS repository

........... 36Prefixed database.mysql for search and replace

........... 51Setup Drupal on Windows XP Pro using IIS

............... 52Basic /sites directory setup

................... 53Special cases

.53Compilation failed: this version of PCRE is not compiled with PCRE_UTF8 support

...... 54Configure .htaccess to allow awstats to work with clean URLs

......... 55Configuring .htaccess to ignore specific subfolders

........ 55Ignoring Subfolders that exist in the DocumentRoot

..... 55Ignoring subfolders that are included via Apache Alias directives

................ 56Create a custom php.ini

...... 60How to create a custom php.ini file when nothing else works

.......... 601. Get and modify your custom php.ini file

.............. 602. Creating your CGI script

............. 613. Modifying your .htaccess file

................. 614. Test your site

............. 61Create Drupal database using Plesk

......... 62Drupal with safe mode enabled and open basedir

............ 65Generic Mass SQL Import into Drupal

... 67How to degrade your Drupal db from MySQL 4.1.X/5.0.X to MySQL 4.0.X

............ 68How-To: Virtual Hosting with Drupal

.................. 68Introduction

.................. 68Environment

.................. 69Requirements

.................. 69Next pages

...... 69How-To: Virtual Hosting with Drupal :: Prepare environment

.................. 69Introduction

................. 70The drupal group

................ 70The temp directory

................ 70The reference location

.................. 70Navigation

...... 71How-To: Virtual Hosting with Drupal :: Solution Overview

.................. 71Introduction

.................. 71Safe mode

.................. 71Open Basedir

................. 72Plesk integration

ii

6 Jun 2007Drupal Handbook

................ 72Managed application

.................. 72eAccelerator

............ 73Each individual vhost requirements

.................. 73Navigation

........ 73HOWTO: copy a site to a local computer using XAMPP

......... 74HOWTO: Copy site to another directory for testing

........... 75HOWTO: Install Drupal 5.x using cPanel

............ 77HOWTO: Install Drupal using cPanel

..... 80HOWTO: Site to site transfer with phpMyAdmin and a FTP Client

........... 82Import a MySQL data dump with BigDump

................ 82What is BigDump?

................ 83Setting up BigDump

....... 83Uploading the sql file and bigdump.php to the webserver

................ 84Running BigDump

........ 84Installing Drupal behind an Actiontec GT701-WG router

............ 85Installing Drupal in a subdirectory in 4.6

........... 85More than one Drupal site on one machine

......... 86General rules for multiple Drupal deployments

......... 86Moving your Drupal installation to a new directory

.......... 87PCRE_UTF8 solution for VPS servers | FreeBSD

............ 88Known causes of PCRE server errors

...... 88Redirecting specific pages to new URLs (301 redirects in Drupal)

...... 89How to create 301 redirects in Drupal Apache mod_rewrite

................ 89The tolerant base URL

............. 90Using .htaccess to stop page caching

................ 90Linux specific guidelines

......... 90Installing PHP, MySQL and Apache under Linux

............... 91XAMPP for Linux Packages

.............. 91Installing XAMPP in Debian

....... 91Download XAMPP Latest version from the following link

................ 91Start XAMPP Server

............... 94Windows-specific guidelines

...... 95How to install Drupal for newbies using FTP and phpMyAdmin

............ 95Change "/tmp" on your drupal site.

................. 95Get Drupal ready

................ 96Upload the database

.... 96HOWTO: Create an apache sandbox using Windows and Apache2Triad

................. 97Before you begin

............... 97Installing Apache2Triad

................. 98Installing Drupal

... 100Importing and exporting Drupal databases updated with PHPMyAdmin

........... 100To export a database with PHPMyAdmin

........... 101To import a database with PHPMyAdmin

......... 102Using bigdump.php to deal with large databases

........... 102Installing Apache (with PHP) on Windows

.............. 104Installing MySQL on Windows

.............. 105Installing PHP4 on Windows

iii


....... 105Drupal 4.7 on Windows/IIS Requires PHP in ISAPI mode

............. 105Installing PostgreSQL on Windows

............ 106Multiple Drupal Sites under Windows106Running multiple sites on a local PC (localhost) from a single codebase, using Windows

.................... 108Untar

.............. 109Installing Drupal on Windows

.............. 109PostgreSQL specific guidelines

................ 109ERROR: DB connect failed

........... 110ERROR: language "plpgsql" does not exist

...... 110ERROR: null value in column "uid" violates not-null constraint

............. 110PostgreSQL support in Drupal 4.7.x

............ 110Drupal 4.5 and PGSQL 8 configuration

............... 111Installing contributed modules

.............. 113HOWTO: Install glossary module

................ 113Where is the Glossary?

..... 113What is the purpose of the Glossary Module, and what does it do?

.............. 114Installing the Glossary Module

............... 114Configuring the Glossary

.............. 115Adding Full Page Definitions

............... 115Adding Glossary To Menus

............. 116Leech - automating content addition

.............. 116Relationships between modules

........... 117Installing new modules (Drupal 4.6 or older)

............... 118Multi-site installation and set-up

........... 11910 Minute Multisite Install & Configuration

.......... 121Access all multisites with www. only [.htaccess]

................. 121Drupal as a library

............. 123Multi-site setup in 5.x using CPanel

...... 124Multi-Site, Single Codebase, Shared Database, Shared Sgin-on 5.x

............ 1241. Prepare database and database user

.............. 1241.1. create a database and user

............ 1242. create and modify site configuration

............... 1242.1. duplicate settings folder

................ 1252.2. Modify config files

............. 1252.2.1. provide DB connection detail

............. 1252.2.2. set prefixes for table names

................. 1263. create static links

.................. 1264. install drupal

...... 127Multi-Site, Single Codebase, Shared Database, Shared Sign-on 4.6

.............. 127Apache (http) Configuration

............... 127Download and Placement

................... 128SQL Setup

........... 129Individual Site Configuration & Theming

............ 130Some things which can be improved:

......... 130Multiple domains or vhosts using different databases

...... 131Sharing Drupal tables between databases using MySQL5 Views

............ 132Multiple domains using the same database

iv


......... 132Same codebase, completely different content and users

............. 135Setup of /sites directory for multi-site

................. 137Installing new themes

................. 139Basic site configuration

..................... 139Settings

.................. 140General settings

.................. 140Default front page

................... 141Examples

................... 141Clean URLs

.......... 143.htaccess for clean urls on specific shared hosts

............... 146403 Permission denied error

.......... 147Apache 2 configuration of clean URLs on Debian

................ 149Apache 2 on Ubuntu

................ 149Editing apache2.conf

............. 150Editing apache2/sites-available

.............. 151Clean URL Support in Abyss

.............. 153Clean URL support in XAMPP

.............. 153Clean URLs in Mac OS X Server

............ 153Clean URLs with different webservers

............. 153Microsoft Internet Services Server

................... 153Lighttpd

............... 154Clean URLs with Easyphp.

...... 155Example Clean URL configuration of httpd.conf for performance

.......... 156Existing URLs for server overwrite Drupal paths

........ 156IIS CleanURLs using some of the available ISAPI filters.

............ 156Translating Apaches rewrite rules

... 157Setting up clean URLs above web document root on virtual private servers

............. 157reboot vps after making change

............... 158Using Clean URLs with IIS

................. 159Alternate method

............. 159set your sites 403 and 404 Error pages

............. 160Configure your sites error reporting

.................. 160Cache support

............... 160Primary and secondary links

................ 160General Information:

.......... 161Setting Up Your Primary and Secondary Links:

............... 161Theming Your Link Menus

........ 161Set length of trimmed posts and # of posts on front page

................ 161URL Alias Optimization

................. 162File system settings

................. 162Download method

.................. 162Path settings

................. 163Date and time settings

................ 163Customizing the interface

................. 164Customizing user login

......... 165Beginners guide for Cron on a shared hosting provider

.................. 166Check your filters

v


................ 166Configure user registration

................ 167Creating a menu structure

.................. 167Creating a menu

................ 168Simplifying the workflow

............. 168Helping search engines and robots.txt

.......... 169Controlling what gets indexed -- the robots.txt file

...... 170Add Disallow: /node/ if your setup has aliases for all nodes

................ 170Selective Bot Crawling

.............. 174Increase upload size in your php.ini

............. 175Need images etc? - check Filtered HTML

..... 176Set default content options - Stop automatic promotion to the front page

.............. 176Show/hide Submitted by on posts

..................... 177Blocks

................. 177Block configuration

............. 178Restricting blocks to certain pages

.......... 179Preventing a block from appearing in Drupal 4.5

.................. 181Custom blocks

............... 181Increase memory in your php.ini

........ 182Database table prefix (and sharing tables across instances)

............... 183Share tables across instances

................ 184Setup tip for Drupal 5

............ 184Using schema prefixes with PostgreSQL

............. 186Define shared variables for all sites

............. 187Drupal Cookbook (for New Drupallers)

..................... 187Purpose

.................... 187Background

..................... 187Myths

................ 188Using the Drupal Web Site

.................. 188Typing Convention

................ 188Some Preliminary Advice

............... 189Drupal Is Supposed to be Easy?

.................. 190A. Getting Started

................. 191B. Basic Configuration

.......... 192C. Creating Multiple Sites On Your Local Computer

................... 195D. Error Pages

.................. 195Page Not Found

.................. 195Access Denied

............... 196E. Accessing Your Test Site(s)

............... 196F. Adding Modules and Themes

................... 197Installation

.................... 197Modules

................... 197Modules

................... 198This Site

.................... 198Themes

.................... 198Themes

................ 198Logo and Favorite Icon

.................. 199G. Creating Content

vi


.................. 200Content Types

..................... 200Page

..................... 200Story

................... 200Book Page

................... 201Blog Entry

................. 201G1. Creating a Page

................. 202G2. Creating a Story

................. 202Whats a Teaser?

................ 203G3. Creating a Book Page

................ 203G4. Creating a Blog entry

.................. 204H. Custom Blocks

.................... 204Address

................... 204Last Updated

................ 205I. Working with the Menu

................... 205Introduction

.................. 205How To Menu

................... 206Textual Menu

................... 206Tabbed Menu

..................... 206Books

..................... 207More

................. 207I2. The Contact Form

.................... 207Set Up

................. 207Make It Accessible

............... 208Add "Contact" to the Menu

................. 208Using It In Content

................... 208J. URL Aliases

............ 209K. Moving Entire Drupal Site with Databases

............. 211Backup Process with phpMyAdmin

.............. 211Backup Process with phpMyAdmin

.............. 214L. Moving Stuff to Your Web Site

.................. 214M. Setting Up Cron

................ 215N. Categories (Taxonomy)

................. 217O. Common Problems

.................. 217P. Links and IMG

............... 218Q. Additional Tips and Tricks

............... 218Q1. Tracking Module Status

.......... 218Q2. Making Multiple Site Maintenance a Bit Easier

............... 219Q3. Controlling User Log In

........... 219How do I disable "Create New Account?"

.... 219How do I disable User Log In entirely, and how would I get in if I do?

......... 220R. Keeping Your Local and Remote Sites Synchronized

................... 220S. More Reading

.................... 221T. Glossary

.................. 224Taking your site live

.............. 224Moving from a temporary location

................... 224Moving Drupal

................. 224Redirecting your server

vii


............... 225Excluding paths from Drupal

.................... 226Core modules

............ 226Aggregator: publishing syndicated content

.................... 227Old page

.......... 227Open aggregator links in new browser window

............. 227User Aggregator:user submitted feeds

............. 228What do I need to subscribe to a feed?

................ 228Configuring news feeds

........... 229Filter feeds by keyword, time, by summary

............. 229Creating categories in the aggregator

............ 229Tagging individual items in the aggregator

............... 229Using the news aggregator

.................. 230RSS feed blocks

............. 230Block: controlling content in the sidebars

.................. 230Module blocks

............... 231Administrator defined blocks

................ 231Blog: a blog for every user

.............. 231HOWTO: Configure user blogs

............... 232Most recent blog post block

............ 232Navigate throught categories inside a blog

................ 232What is a blog or weblog?

.............. 233Making user blogs more accessible

................. 233Additional features

............... 234BlogApi: post from blog tools

............. 234Book: structured document publishing

............ 235Customising the book navigation menu

........... 236Maintaining a FAQ using a collaborative book

......... 237Categories (taxonomy): A way to organize your content

............. 240Modules that do more with categories

...... 242Content Management System comparison focused on Taxonomy

....... 242Taxonomy - some guidelines for effective design of taxonomies

............ 244Taxonomy Garden: Managing Categories

........... 245Taxonomy Garden: Navigation by category

.......... 252Taxonomy Garden: Organize content by category

............. 258The taxonomy module for Drupal 4.x

............ 259Understanding categories for new users

............. 260Using taxonomy to organize content

.............. 263Using vocabularies for navigation

................ 264Vocabularies and terms

................ 265Creating a vocabulary

.................. 265Creating terms

............ 266Advanced taxonomies: using hierarchies

................ 266More about Taxonomy

...... 268Creating a Block with links belonging to certain taxonomy terms

............... 269Taxonomy terms on a page

............. 270Comment: allow comments on content

.............. 270Detailed comment documentation

viii


............. 270User control of comment display

............. 271Additional comment configurations

.............. 271Notification of new comments

................ 272Comment moderation

................. 272Moderation votes

.............. 272Moderator vote/values matrix

.............. 272Creating comment thresholds

................ 273Initial comment scores

................ 273Aggregator comments

............. 273Contact: a way for users to get in touch

........... 274Make your site wide contact form look prettier

.............. 274Drupal: Drupal sites directory server

.................... 275Old page

.............. 275Filter: Input formats for user content

.............. 276Forum: create threaded discussions

................ 277HOWTO: Create a forum

.............. 277HOWTO: Create forum containers

............... 277Help: context-sensitive guidance

............... 278More about the help module

............. 278Legacy: remapping of old-style URLs

............... 278Locale: multi-language support

......... 279Adjusting your php.ini settings for importing .po files

................ 280Editing text for translation

.......... 280How to create Drupal site in Marathi (Devnagari)

............. 281How to install a different language

... 281HOWTO: Creating a customized language set to replace Drupal terminology

.. 282HOWTO: Use a customized language set to change Drupal text and terminology

................. 284Note for the curious

............... 284Menu: customize site navigation

.............. 284Using named anchors with menus

.................. 285Node: the content

................. 285Page: post static pages

.............. 286Difference between page and story

................. 286Specify page by title

.................. 286Path: readable URLs

................. 288Mass URL aliasing

............... 289Ping: notify services of changes

........... 289Write a custom module to ping a set of sites

................. 290Poll: community voting

............ 291Profile: extending user account information

.............. 292Enabling user pictures (avatars)

.............. 292HOWTO: Create new profile fields

......... 293HOWTO: Make a field part of the registration process

............... 293Form Validation in plugin

............ 293HOWTO: Create a country profile field

... 294CiviCRM: Tags, Profiles, Groups, advanced community member management

.............. 294Search: an internal site search system

ix


............. 296Add searching to your custom module

............ 296Statistics: tracking referrers, page hits, etc.

................. 297Story: post static pages

................ 297System: cron and caching

................. 298Configuring cron jobs

............ 300Configuring cron jobs on DreamHost

............. 301Cron Job configuration line by line

............. 301Cronjobs without wget/lynx or curl

............. 303Configuring cron jobs on Windows

................ 304Throttle: congestion control

.............. 304When to use the throttle module?

............ 305Tracker: viewing new and updated content

............... 305Upload: collaborate with files

............. 306User: access and management settings

............... 306Access Permissions reference

.................. 306block module

.................. 307filter module

.................. 307menu module

.................. 307node module

.................. 307path module

.................. 308user module

.................. 308system module

................ 308Access rules (email filters)

........ 308Managing access control with permissions and user roles

........... 309Assigning permissions and users to roles

.... 310Taxonomy_access: Restrict user roles to access specific categories only

........... 310Adjusting permissions after adding modules

................. 310User authentication

... 311Make a Drupal site use Basic Auth/ldap instead of the normal login block

................ 313NTLM Authentication

............... 314User preferences and profiles

.............. 315Using distributed authentication

............... 315Distributed authentication

.................... 315Drupal

................ 315Watchdog: monitor your site

................... 317End user guide

.................. 317Registering as a user

.................... 318Logging in

............... 318Changing your account settings

................. 319Creating new content

................ 319A step-by-step example

............... 321Controlling Teaser Location

............. 322How to add a page to the Handbook

.................. 322Types of content

............... 322Topics, categories and terms

................... 322Permissions

............. 323Moderation and the submission queue

x


................. 323Creating comments

.............. 323Alternative ways to enter content

....... 324HOWTO: Posting and editing blog entries with TextMate

........... 325Posting and editing content with w.bloggar

............. 326Posting content with mailhandler

............... 326Preparing content offline

................ 326Editing and deleting content

..................... 327Search

.................. 328Beyond the basics

................. 329Best practices guidelines

................ 329Back up your Drupal site

................ 329Backing up the database

................ 330Backing up the core files

............... 330Backing up the non-core files

.................. 331Test your backups

........... 331Backup and restore using bash shell scripts

................ 331Functional Overview

............... 331Usage notes and cautions

................. 332Site backup script

.............. 332Usage notes and warnings:

................. 333fullsitebackup.sh

.............. 335Updated fullsitebackup.sh

................. 337Site restore script

.............. 338Usage notes and warnings:

................. 338fullsiterestore.sh

............... 341Updated fullsiterestore.sh

.................. 343Accounts and roles

...... 344Configuring Apache and PHP for Drupal in a Shared Environment

............... 345Creating a Test Site workflow

............... 349File and directory management

................... 350Other Tips

.................... 350Test Sites

............... 350Version update considerations

................ 351Do not modify core Drupal

..................... 352Security

.............. 352Test php before putting it in blocks

.............. 353HowTo: The Advanced users guide

.......... 354HowTo: enable Imagemagick for the Image module

................... 354Tips and Tricks

........ 354August 2005: Upgrade, Play B-I-N-G-O!, & E-commerce

................... 354UPGRADE

................. 355PLAY B-I-N-G-O!

.................. 355E-COMMERCE

................. 355Commentator arrayJune 2005: Custom Content Types, WYSIWIG Editors, Organize Your Content & Quick

.................... 356SupportSeptember 2005: Newest modules, Change any string, Remote authentication, and

xi


................. 357tracking project issues

.............. 357Get the newest modules -- fast!

................. 357Change any string

................ 357Remote authentication

............... 358Keep tabs on project issues

...... 358Winter 2005/2006: Tracking projects with RSS and Module Linking

.................. 358Planning a web site

................ 362Server tuning considerations

............. 362Identifying Drupal performance goals

......... 362Analysing your sites traffic and resource consumption

....... 362Understanding and configuring your stack for performance

........... 364Enable default 404 handling for some file types

......... 365Simple Decision Tree for Drupal Enterprise Scalability

...... 366Slow contributed modules determined using the developer module

.................. 366Squid Caching

............ 367Tools, tips, and links on optimizing mysql

............... 369Tuning MySQL for Drupal

................... 369Tuning PHP

.............. 370Persistent database connections

................... 370PHP caches

.............. 371APC : Alternative PHP Cache

.................. 371eAccelerator

................. 371Turck MMCache

.............. 373Useful article on optimizing PHP

............... 373Tuning Drupal on OS X Tiger

............... 375Upgrading from previous versions

................ 375Introduction to upgrading

....... 375Getting started: Choosing your method and preparing the site

................. 376Preparing the site

............. 376Do I need to upgrade my database?

......... 376Important! : Backing up the database and existing files

............... 376Backing up your site (GUI)

............. 377Back up your site (command line)

......... 378Create a test site first or upgrade your existing site?

............ 378Copy your live site to a test site (GUI)

......... 379Copying your live site to a test site (command line)

........... 381Downloading Drupal and installing the files

......... 381Downloading Drupal and installing the files (GUI)

....... 382Downloading Drupal and installing the files (command line)

................. 383Running update.php

............... 384Optional configuration steps

................. 385Post-upgrade steps

............. 385Testing Your Newly Upgraded Site

.............. 386Copy your test site to a live site

........ 387Copying your test site to your live site (command line)

............ 387Copy your test site to a live site (GUI)

................ 388Version specific upgrades

xii


.............. 388Upgrading from Drupal 4.4 to 4.5

............. 390Upgrading from Drupal 4.5 to 4.6.3

.................. 390Before you Start

.......... 390Step-by-step Upgrade from Drupal 4.5 to 4.6.3

................ 392Finalising your upgrade

............ 392Rebuilding your Drupal Search Index.

..................... 392Blocks

................... 393Permissions

.................... 393Forums

.................... 393Images

.................... 393Events

............. 394Upgrading from Drupal 4.6.3 to 4.6.5

.................. 394Before you Start

.......... 394Step-by-step Upgrade from Drupal 4.6.3 to 4.6.5

............. 394Upgrading from Drupal 4.6.4 to 4.6.5

.................. 395Before you Start

.......... 395Step-by-step Upgrade from Drupal 4.6.4 to 4.6.5

................ 395Differences from 4.6 to 4.7

................ 395Block visibility settings

............... 396Configure options centralized

.......... 396core module help text linked to the handbook now

..... 396Creating context sensitive menus with primary and secondary menus

....... 397Dont turn off contributed modules that provide an .install file

................. 397Module .install files

......... 397Primary/secondary links now part of the menu system

.............. 397queue module removed from core

........... 398Removal of base href statement from header

......... 399Some HTML Tags stripped from mission statement

............. 399XTemplate engine removed from core

.................. 400Troubleshooting FAQ

.............. 400How to troubleshoot (read this first)

.................. 400Stop and think

.................. 400Read the errors

................. 401Validate your page

................. 401Read the README

................. 401Search the right way

.............. 402Identify the source of the problem

................ 402Dump some diagnostics

................ 403Ask the right questions

.......... 403Identify the module thats giving you problems

.............. 403My admin > modules page is blank

............. 404How do I get the User Login block back

...... 404Client does not support authentication protocol requested by server...

............. 405Webhosting issues for new Drupal users

.............. 405Brief intro to Unix file permissions

............... 407Host-specific error messages

......... 407SELinux may cause mysterious permission problems

xiii


............... 408Typical webhosting setups

........... 409Using PHP to change files on the webserver

............ 409What do all those Unix commands mean?

........... 409Some Unix command youll see mentioned:

................. 410Special characters:

............. 410What permissions does Drupal need?

............ 412Why is this uploading stuff so difficult?

................ 412"Headers already sent" error

............ 413"LOCK TABLES sequences WRITE" error

..... 413"Method POST is not allowed for the URL /index.htm" error (Error 405)

........ 414"Page Not Found" error when trying to access a subdirectory

.................. 414Block referrer spam

............ 415.htaccess sample list plus domain blocking

......... 416Color picker doesnt appear on theme configuration page

............ 416Drupal 4.7 Install inserts CGI-BIN in URL

................. 417Duplicate entry error

.......... 419E-Mail from Drupal is bouncing or not being sent

........ 419Relay SMTP mail to external mail server using smtp.class

........ 420Error 1364 upon importing database.mysql with MySQL 5.0+

... 421Error on installation step 3: Warning: Table [database].access doesnt exist [...]

.. 422Fatal error: Allowed memory size of X bytes exhausted (tried to allocate Y bytes)...

............. 422Fatal error: Call to undefined function

....... 422Fatal error: Call to undefined function: form_*() on Drupal 4.7

..... 423Fatal error: Cannot redeclare blah_function() in ../modules/blah.module

............ 423Forgotten your Drupal account password

.............. 424Forum overview stopped working

.................... 424The Fix

........... 425FTP uploads and file permissions using Transmit

........ 425Help! I enabled a buggy module and now I cant disable it!

... 425How can I adminstrate my navigation on my Drupal site? (version 4.5 or older)

... 427How do I get rid of the "Welcome to your new Drupal website" on the front page?

............. 428How do I get the Navigation block back

............... 428How do I unset the clean URLs?

...... 428How to login once you have turned your site off-line for maintenance

... 429HOWTO: Download a fresh copy of a missing or corrupted module/image/file

................ 430Installation/configuration

.............. 430406 Error when XMLRPC is used

.............. 430Junk {head} {styles} codes as output

............ 431Login after disabling the User login block

............ 431Login doesnt work or must be done twice

.................... 431Cookies

.................. 431Cache Problems

........ 432Logging in at www on a site with no www in the baseurl

................ 432Login problems on PHP 5.2My layout collapses - content appears below left column (IE) or overflows over the right

...................... 432(FF)

......... 433The content is too wide for the space its been given

xiv


.................. 433Validation Woes

..... 434Mysterious 403, 404, 406 or 500 errors depending on submitted content

............. 434Permission denied in includes/file.inc

.......... 435Persistent Welcome to Drupal for anonymous users

..................... 436phpinfo

............... 436Plain unstyled HTML output

................. 437Setting up Clean URLs

.............. 438unblocking account through SQL

........... 438Weird behaviour - module-theme name collision

.......... 438Where is the taxonomy choice when adding content?

................... 439Miscellaneous

..... 439How can I change Drupals character encoding? (UTF-8 and Unicode)

xv


Installation and configurationHere is a guide for installing and configuring a Drupal site. This guide includes extensiveHow-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


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. Themajority of Drupal development is done using Apache so there is more communityexperience and testing performed. Optional: You can use the Apache extensionmod_rewrite to allow for clean urls.

Optional: IIS

Drupal core will work using IIS5 or IIS6 if PHP is configured correctly. You will need touse a third party solution to achieve Clean URLs. In view of Microsofts support lifecycle 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 reportsof 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; onlyDrupal 4.7.5 (and greater) and 5.0 (and greater) run on PHP 5.2, older Drupal versions donot. 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 willprobably need to use a higher setting depending on your site and contributed modulesyou are using. A good starting point is 16-24 MB. PHP XML extension (for blogapi, drupal, and ping modules). This extension is enabledby default in a standard PHP installation; the windows version of PHP has built-insupport for this extension. PHP needs the following configuration directives for Drupal to work (only directivesthat 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 toE_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 PHPconfiguration options from .htaccess only works:

with Apache (or a compatible web server),

2


http://en.wikipedia.org/wiki/Webserverhttp://httpd.apache.org/http://www.microsoft.com/iishttp://www.php.net/http://www.php.net/manual/en/ref.xml.phphttp://www.php.net/manual/en/ref.xml.php#xml.installationhttp://www.php.net/manual/en/ref.xml.php#xml.installationhttp://www.php.net/manual/en/configuration.phphttp://www.php.net/manual/en/configuration.directives.phphttp://cvs.php.net/php-src/php.ini-disthttp://cvs.php.net/php-src/php.ini-recommendedhttp://www.php.net/manual/en/ref.session.php#ini.session.save-handlerhttp://www.php.net/manual/en/function.session-cache-limiter.php#22443

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

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 forfuture compatibility with Drupal 6 which will drop support for older versions ofMySQL. NOTE: Drupal makes use of some features not available on some inexpensive hostingplans so please check that your host allows database accounts with the following rights:

SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATETEMPORARY 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 theproblem by following the instructions provided by MySQL AB. There is a minor OSissue with some MySQL 5+ installations primarily on Windows but affecting someUnices as well.

PostgreSQL, version 7.3 or newer.

Note, some of the contributed modules are not as abstracted from MySQL specific codeas everyone would like. If you are familiar with PostgreSQL please file issues withthose contributed modules as you find them.

Currently MS SQL and Oracle are not supported but various efforts are underway to supplyschemas. Please see discussions in the Enterprise Group if you are interested in working on this.

Client System Requirements

Drupal aims to conform with internet standards and deviate where necessary to comply withpopular clients that are not standards compliant.

Javascript

For 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, onlywhat they support.

3


http://www.php.net/manual/en/configuration.changes.php#configuration.changes.otherhttp://www.mysql.com/http://downloads.mysql.com/archives.php?p=mysql-3.23http://dev.mysql.com/doc/refman/4.1/en/old-client.htmlhttp://drupal.org/node/43316http://www.postgresql.org/http://groups.drupal.org/enterprise

CSS

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

RSS

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

Browser Specifics

In 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 Popularity

The 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 Problems

IE5 and IE5.5 will experience some layout issues. IE5.0 will not do any Javascript. We canassume 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 inwidespread use.

Validation

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

Caveats

These guidelines are the guide for Drupal core, modules, and themes but are not alwayscompletely accurate. In practice, Drupal Core is expected to follow these standards more closelythan various contributed pieces of code. If you find a problem with client compatability thatdeviates 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


http://validator.w3.org/http://drupal.org/node/add/project_issue

HOWTO: Server requirement recommendations foryour consulting clients

When 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 thanothers, 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 ademand on the server, but especially if these users login and make comments or nodes you willneed a more powerful server.

You need to consider these two answers together. For example, you could have a highlycomplex site with very few users and be able to use a shared hosting environment. You couldalso use very few modules, only have one editor, use the cache, and have reasonable traffic on ashared environment.

If your project is a more interactive environment with more users logging in and posting to thesite you will need to consider more powerful hardware. As you move out of a sharedenvironment there are other options available to you like using the methods described in thehandbook to Tune Your Server for optimal Drupal performance. Tuning the server may allowyou to continue using the same hardware and not upgrade, but it comes at the cost of timewhich can be more expensive than simply buying new hardware.

When deciding which parts of your server to upgrade, remember that "Apache is bandwidthlimited, PHP is CPU limited, and MySQL is memory limited and disk I/O bound".

Message to the Client

Its probably best to give the message to the client of a "recommended" installation and a levelbelow that in case their budget is limited and a level above that to provide for future growthwith purchasing new hardware and services.

If you are rolling out a new service (as opposed to installing Drupal in place of an existingsolution) keep an eye towards a solid upgrade path. You can purchase a single server with theintent of upgrading as your site grows. For example, start with the web server and database onone server that is optimized for web serving. As the site grows in popularity and you need tohandle more users you can then move the database to its own server separate from the webserver. If your site grows beyond a two server "web server" and "database server" configurationthen you can consider using a single web server and multiple database servers in a cluster.

5


http://drupal.org/node/2601http://drupal.org/node/2601http://drupal.org/node/2601

Benchmark

One benchmark of a server is MBR.org which required serious intervention for optimisation atroughly the 2m pages per month mark, on a server running Apache1.3 and MySQL 4.1 with 1GBof memory. MySQL indexing, database memory use tweaks and abandoning MyISAM forInnoDB 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 on

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

Requirements - older versions

1. A Web Server that can execute PHP scripts 2.

Recommended: Apache. Development is done with version 1.3.x. Successfully testedwith version 2.0.x. Optional: IIS. Drupal is being developed with IIS compatibility in mind, and IIS5 andIIS6 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.6release). Drupal 4.2 to 4.5.2 inclusive require PHP version 4.1+. Older versions ofDrupal 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 enabledby default in a standard PHP installation; the windows version of PHP has built-insupport for this extension. PHP memory of 8MB for a Drupal core install. If you install additional contributedmodules you may need to raise your php allowed memory. Prepackaged Drupaldistributions such as CivicSpace may have higher PHP memory requirements then aDrupal 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 youshouldnt need to set them explicitly. Note, however, that setting PHP configuration optionsfrom .htaccess only works:

6


http://www.mbr.org/http://drupal.org/node/44740http://drupal.org/node/26707http://drupal.org/node/26707http://en.wikipedia.org/wiki/Webserverhttp://httpd.apache.org/http://www.microsoft.com/iishttp://www.php.net/http://www.php.net/manual/en/ref.xml.phphttp://www.php.net/manual/en/ref.xml.php#xml.installationhttp://www.php.net/manual/en/ref.xml.php#xml.installationhttp://drupal.org/node/31819http://www.php.net/manual/en/configuration.phphttp://www.php.net/manual/en/configuration.directives.phphttp://www.php.net/manual/en/ref.session.php#ini.session.save-handlerhttp://www.php.net/manual/en/function.session-cache-limiter.php#22443http://cvs.php.net/php-src/php.ini-disthttp://cvs.php.net/php-src/php.ini-recommended

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, likeLOCK 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 databasesare greatly welcome.

Note: If your system/host is running MySQL 4.1 or newer, a link in the troubleshootingsection (http://drupal.org/node/35226) points to this page, which has some helpful info onaddressing 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 tohave 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


http://www.php.net/manual/en/configuration.changes.php#configuration.changes.otherhttp://pear.php.net/manual/en/installation.phphttp://www.mysql.com/http://dev.mysql.com/doc/mysql/en/JOIN.html#IDX1578http://dev.mysql.com/doc/mysql/en/JOIN.html#IDX1578http://www.postgresql.org/http://drupal.org/node/35226http://dev.mysql.com/doc/refman/4.1/en/old-client.htmlhttp://drupal.org/node/43316http://drupal.org/node/42080

Installing Drupal, modules and themesInstalling Drupal, new modules and themes uses roughly the same process so once you arefamiliar with it you can repeat as needed.

After you successfully install Drupal, you will want to perform some basic site configurationstarting with the settings menu.

Installing and configuring your site is only part of your responsibilities. You must remember tobackup, test and maintain it as well. Please stop by the Best Practices section for some importanttips on this and sign up for the security newsletter

Installing Drupal

This page is autogenerated from the current development text in CVS. See the various otherprovided 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 InformationCHANGES-------As of Drupal 5.0 installation has been automated by an install script.It is nolonger necessary to manually edit the "settings.php" file, and database tablesare 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 arerecommended; other web server and database combinations such as IIS andPostgreSQL have been tested to a lesser extent. When using MySQL,version 4.1or greater is recommended to assure you can safely transfer the database.

8


http://drupal.org/node/363http://drupal.org/node/15362http://drupal.org/best-practiceshttp://drupal.org/securityhttp://www.php.net/http://www.mysql.com/http://www.postgresql.org/

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 operatingsystems 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 RSSsyndication, you will need PHPs XML extension. This extension isenabled bydefault.- If you want support for clean URLs, youll need mod_rewrite and the abilityto 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 compressiontools. 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 adirectory within your web servers document root or your public HTML directory: mv drupal-x.x/* drupal-x.x/.htaccess /var/www/html2. 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


http://drupal.org/requirementshttp://drupal.org/node/260http://drupal.org/http://drupal.org/files/projects/drupal-x.x.tar.gz%3Cbr%20/%3E

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 thedatabase, 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, callthe cron

10


http://www.example.com/

page by visiting http://www.example.com/cron.php --this will passcontrol to the modules and the modules will decide if and what they must do. Most systems support the crontab utility for scheduling tasks likethis. The following example crontab line will activate the cron tasksautomatically on the hour: 0 * * * * wget -O - -q http://www.example.com/cron.php More information about the cron scripts are available in the adminhelp pages and in the Drupal handbook at drupal.org. Example scripts can befound in the scripts/ directory.DRUPAL ADMINISTRATION---------------------A new installation of Drupal defaults to a very basic configurationwith only afew active modules and minimal user access rights.Use your administration panel to enable and configure services. For example:General Settings administer > site configuration > site informationEnable Modules administer > site configuration > modulesSet User Permissions administer > users management > access controlConfigure Themes administer > site building > themesFor more information on configuration options, read the instructions whichaccompany the different configuration settings and consult the various helppages 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 thelook ofyour site. Several sample themes are included and more can bedownloaded fromdrupal.org.Simple customization of your theme can be done using only CSS. Further changesrequire understanding the phptemplate engine that is now part ofDrupal. Seehttp://drupal.org/handbook/customization to find out more.MULTISITE CONFIGURATION-----------------------

11


http://www.example.com/cron.phphttp://www.example.com/cron.php%3Cbr%20/%3Ehttp://drupal.org/.%3Cbr%20/%3ECUSTOMIZINGhttp://drupal.org/.%3Cbr%20/%3ECUSTOMIZING

A single Drupal installation can host several Drupal-powered sites,each withits own individual configuration.Additional site configurations are created in subdirectories within the sitesdirectory. Each subdirectory must have a settings.php file whichspecifies theconfiguration settings. The easiest way to create additional sites isto copythe default directory and modify the settings.php file asappropriate. Thenew directory name is constructed from the sites URL. Theconfiguration forwww.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 usesubdomains andsubdirectories for Drupal sites. For example, example.com, sub.example.com,and sub.example.com/site3 can all be defined as independent Drupalsites. Thesetup 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.phpWhen searching for a site configuration (for example www.sub.example.com/site3),Drupal will search for configuration files in the following order,using thefirst 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.phpIf you are installing on a non-standard port, the port number istreated as thedeepest subdomain. For example: http://www.example.com:8080/ could be loadedfrom sites/8080.www.example.com/. The port number will be removedaccording tothe pattern above if no port-specific configuration is found, just like

12


http://example.com/http://www.sub.example.com/site3http://www.example.com:8080/

a realsubdomain.Each site configuration can have its own site-specific modules andthemes inaddition to those installed in the standard modulesand themes directories.To use site-specific modules or themes, simply create a modules or themesdirectory within the site configuration directory. For example, ifsub.example.com has a custom theme and a custom module that should not beaccessible to other sites, the setup would look like this: sites/sub.example.com/: settings.php themes/custom_theme modules/custom_moduleNOTE: for more information about multiple virtual hosts or the configurationsettings, consult the Drupal handbook at drupal.org.MORE INFORMATION----------------For platform specific configuration issues and other installation andadministration assistance, please consult the Drupal handbook athttp://drupal.org/handbook. You can view the wide range of othersupport optionsavailable at http://drupal.org/support.

Formatted Drupal 5.x Installation instructions for better readability

Installation

// $Id: INSTALL.txt,v 1.39 2007/01/08 11:59:16 dries Exp $

Table of Contents

1. Changes 2. Requirements 3. Optional requirements 4. Installation 5. Drupal administration 6. Customizing your theme(s) 7. Multisite Configuration 8. More Information

13


Changes

As of Drupal 5.0 installation has been automated by an install script. It is no longer necessary tomanually 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/) andeither MySQL (http://www.mysql.com/) or PostgreSQL (http://www.postgresql.org/). TheApache web server and MySQL database are recommended; other web server and databasecombinations such as IIS and PostgreSQL have been tested to a lesser extent. When usingMySQL, version 4.1 or greater is recommended to assure you can safely transfer the database.

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 inspecial 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 needPHPs 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 formatand 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 thecontents of that directory into a directory within your web servers document root or your publicHTML 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 needsufficient privileges to run Drupal. Additional information about privileges, and instructions tocreate a database using the command line are available in INSTALL.mysql.txt (for MySQL) or

14


http://www.php.net/http://www.mysql.com/http://www.postgresql.org/http://drupal.org/requirementshttp://drupal.org/node/260http://drupal.org/http://drupal.org/files/projects/drupal-x.x.tar.gz%3Cbr%20/%3E

INSTALL.pgsql.txt (for PostgreSQL).

To create a database using PHPMyAdmin or a web-based control panel consult thedocumentation 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 theinformation you provide in the installation routine. If you make manual changes to that filelater, be sure to protect it again after making your modifications. Failure to remove writepermissions to that file is a security risk. The default location for the settings.php file is atsites/default/settings.php, but it may be in another location if you use the multi-site setup, asexplained 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 subdirectorystores 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 canchange 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 betriggered 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 moduleswill decide if and what they must do.

Most systems support the crontab utility for scheduling tasks like this. The following examplecrontab 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 Drupalhandbook at drupal.org. Example scripts can be found in the scripts/ directory.

15


http://www.example.com/http://www.example.com/cron.phphttp://www.example.com/cron.php

Drupal Administration

A new installation of Drupal defaults to a very basic configuration with only aw active modulesand minimal user access rights.

Use your administration panel to enable and configure services. For example:

General Settings administer > site configuration > site informationEnable Modules administer > site configuration > modulesSet User Permissions administer > users management > access controlConfigure Themes administer > site building > themes

For more information on configuration options, read the instructions which accompany thedifferent configuration settings and consult the various help pages available in theadministration 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. Severalsample themes are included and more can be downloaded from drupal.org.

Simple customization of your theme can be done using only CSS. Further changes requireunderstanding the phptemplate engine that is now part of Drupal. See http://drupal.org/handbook/customization to find out more.

Multi-site 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. Eachsubdirectory must have a settings.php file which specifies the configuration settings. Theeasiest way to create additional sites is to copy the default directory and modify thesettings.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 (notethat 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 subdirectoriesfor Drupal sites. For example, example.com, sub.example.com, and sub.example.com/site3 canall be defined as independent Drupal sites. The setup for a configuration such as this would looklike the following:

sites/default/settings.phpsites/example.com/settings.phpsites/sub.example.com/settings.phpsites/sub.example.com.site3/settings.php

16


http://drupal.org/http://drupal.org/handbook/customizationhttp://www.example.com/http://example.com/

When searching for a site configuration (for example www.sub.example.com/site3), Drupal willsearch for configuration files in the following order, using the first configuration it finds:

sites/www.sub.example.com.site3/settings.phpsites/sub.example.com.site3/settings.phpsites/example.com.site3/settings.phpsites/www.sub.example.com/settings.phpsites/sub.example.com/settings.phpsites/example.com/settings.phpsites/default/settings.php

If you are installing on a non-standard port, the port number is treated as the deepestsubdomain. For example: http://www.example.com:8080/ could be loaded fromsites/8080.www.example.com/. The port number will be removed according to the patternabove 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 thoseinstalled in the standard modulesand themes directories. To use site-specific modules orthemes, 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 beaccessible to other sites, the setup would look like this:

sites/sub.example.com/:settings.phpthemes/custom_thememodules/custom_module

NOTE: for more information about multiple virtual hosts or the configuration settings, consultthe 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 widerange of other support options available at http://drupal.org/support.

Formatted Drupal 4.7.x Installation instructions for better readability

Installation

// $Id: INSTALL.txt,v 1.6 2004/11/27 11:28:55 dries Exp $

This document outlines the standard installation process.

17


http://www.sub.example.com/site3http://www.example.com:8080/http://drupal.org/handbookhttp://drupal.org/support

1. REQUIREMENTS 2. SERVER CONFIGURATION 3. OPTIONAL COMPONENTS 4. INSTALLATION 5. DRUPAL ADMINISTRATION 6. CUSTOMIZING YOUR THEME(S) 7. UPGRADING 8. MORE INFORMATION

REQUIREMENTS

1. Drupal requires a web server, PHP4 (http://www.php.net/) and eitherMySQL, 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 youwish to install using the commands listed below; access to run database scripts directly or atool such as PHPMyAdmin to manage a database; knowledge of how to use either FTPprograms 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 PostgreSQLare possible but tested to a lesser extent.

SERVER CONFIGURATION

Your 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 .htaccessfile; you can print out your local PHP settings with PHPs phpinfo()function.

OPTIONAL COMPONENTS

To use XML-based services such as the Blogger API, Jabber, RSSsyndication, you will need PHPs XML extension. This extension isenabled by default in standard PHP4 installations. If you want support for clean URLs, youll need mod_rewrite andthe ability to use local .htaccess files. (More information canbe found in the Drupal handbook on drupal.org.)

18


http://www.php.net/http://pear.php.net/

INSTALLATION

1. DOWNLOAD DRUPAL

You 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 allDrupal files and directories. Move the contents of that directoryinto a directory within your web servers document root or yourpublic HTML directory:

$ mv drupal-x.x.x/* drupal-x.x.x/.htaccess /var/www/html

2. CREATE THE DRUPAL DATABASE

These 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 GRANTprivileges. You will need to use the appropriate user name for yoursystem.

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 createthe initial database files. Next you must login and set the accessdatabase rights:

$ mysql -u dba_user -p

Again, you will be asked for the dba_user database password. At theMySQL 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


http://drupal.org/http://drupal.org/files/project/drupal-x.x.x.tgz%3Cbr%20/%3E

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 SCHEME

Once you have a database, you must load the required tables:

$ mysql -u nobody -p drupal < database/database.mysql

4. CONNECTING DRUPAL

The default configuration can be found in thesites/default/settings.php file within your Drupal installation.Before you can run Drupal, you must set the database URL and thebase 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 severalDrupal-powered sites, each with its own individual configuration.If you dont need to run multiple Drupal sites, you can skip to thenext section.

Additional site configurations are created in subdirectories withinthe sites directory. Each site subdirectory must have asettings.php file which specifies the configuration settings. Theeasiest way to create additional sites is to copy the defaultdirectory and modify the settings.php file as appropriate. The newdirectory name is constructed from the sites URL. Theconfiguration for www.example.com could be insites/example.com/settings.php (note that www. should be omittedif users can access your site at http://example.com/).

Sites do not each have to have a different domain. You can usesubdomains and subdirectories for Drupal sites also. For example,example.com, sub.example.com, and sub.example.com/site3 can all be

20


http://www.example.com/http://example.com/

defined as independent Drupal sites. The setup for a configurationsuch 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 examplewww.sub.example.com/site3), Drupal will search for configurationfiles in the following order, using the first configuration file itfinds: 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 andthemes that will be made available in addition to those installedin the standard modules and themes directories. To usesite-specific modules or themes, simply create a modules orthemes directory within the site configuration directory. Forexample, if sub.example.dom has a custom theme and a custom modulethat should not be accessible to other sites, the setup would looklike this:

sites/sub.example.com/: settings.php themes/: custom_theme modules/: custom_module

NOTE: for more information about multiple virtual hosts or theconfiguration settings, consult the Drupal handbook at drupal.org.

5. CONFIGURE DRUPAL

You can now launch your browser and point it to your Drupal site.

Create an account and login. The first account will automaticallybecome the main administrator account.

21


http://www.sub.example.com/site3

6. CRON TASKS

Many Drupal modules have periodic tasks that must be triggered by acron job. To activate these tasks, you must call the cron page;this will pass control to the modules and the modules will decideif and what they must do.

The following example crontab line will activate the cron scripton the hour:

0 * * * * wget -O - -q http://HOSTNAME/cron.php

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

DRUPAL ADMINISTRATION

Upon a new installation, your Drupal website defaults to a very basicconfiguration with only a few active modules, one theme, and no useraccess rights.

Use your administration panel to enable and configure services. Forexample, 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 theinstructions which accompany the different configuration settings andconsult the various help pages available in the administration panel.

Note that additional community-contributed modules and themes areavailable at http://drupal.org/.

CUSTOMIZING YOUR THEME(S)

Now that your server is running, you will want to customize the lookof your site. Several sample themes are included in the Drupalinstallation and more can be downloaded from drupal.org.

Customizing each theme depends on the theme. In general, each themecontains a PHP file themename.theme which defines a function header()that can be changed to reference your own logos.

22


http://drupal.org/

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

UPGRADING

1. Backup your database and Drupal directory - especially yourconfiguration 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 INFORMATION

For platform specific configuration issues and other installation andadministration assistance, please consult the Drupal handbook athttp://drupal.org/. You can also find support at the Drupal support forum or through theDrupal mailing lists.

10 minute install using PuTTY SSH/Telnet client

Ive been developing best practices for my development company and wanted toshare/collaborate on some of them.

Development environment:

Server: LAMPSSH/Telenet Client: PuTTYServer Interface: WHMMust 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 youreinstalling, 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


http://www.example.com.conf/http://www.example.com/update.phphttp://drupal.org/

# 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# mysqlmysql> CREATE DATABASE youraccountname_drupal;mysql> GRANT ALL PRIVILEGES ON youraccountname_drupal.* TO youraccountname_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" (orwhatever the link says to new website), create first "superuser"account, etc.]

How I installed Drupal: The Eightfold Way

Try 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 thedomain 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.02) Created a subdomain ("drupal") via my webhosts control panel3) Created a database ("dbname") via my webhosts control panel (note the user name and

24


password). Noted the hostname, e.g., testsite.yoursite.com4) Using browser, pointed to URL \http://drupal.yoursite.com\5) The install.php script automatically installed Drupal6) Entered information. Database name ("dbname"), username, password7) 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 subsites

The purpose of this guide is to concisely summarize how to implement apache vhost settings foreach 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 apache2configuration 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, wemake 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


http://www.example.com/http://www.example.com%3Cbr%20/%3Ehttp://www.example.com%3Cbr%20/%3E

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 guidelines

Install and configure Mysql and PHP, if necessary. Server Logistics provides nice pre-compiledpackages and instructions. PHP is also available from Marc Liyanage. PHP may already beinstalled 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. Nowcomes the more involved part- changing the webserver configuration.

To make changes to the Apache configuration you should NOT edit /etc/httpd/httpd.conf butinstead 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 moreconfiguration 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 notmake changes to /etc/httpd/httpd.conf expecting the AllowOverride All directive towork. The correct file to add the AllowOverride All directive is in the directory /etc/httpd/sites/. In that directory are the virtual host configuration files. Each virtualserver has a configuration file in that directory so it is in those files that you must enable AllowOverride All. If you only have one web server on your server configured, then the fileyou want to modify is /etc/httpd/sites/0000_any_80_.conf.

To enable clean URLs you will need the following code in your conf file. Youll need to be root(or sudo) to do this. Dont forget to restart apache after modifying httpd.conf (turn personal websharing off, then back on again, or use /usr/sbin/apachectl restart).

# # This controls which options the .htaccess files in directories can# override. Can also be "All", or any combination of "Options", "FileInfo",# "AuthConfig", and "Limit"#

26


http://www.serverlogistics.com/http://www.entropy.ch/software/macosx/php/

# AllowOverride None AllowOverride All

You may also need to edit this file to enable the PHP module for Apache. You have touncomment two lines. First in this section:

## Dynamic Shared Object (DSO) Support#

Uncomment this line (around line 235) by remov

installation and configuration - mulb.orgstuff.mulb.org/drupal/installation and upgrading.pdf · 10...

Documents