[documentation] [Documentation task] Installing Drupal (using phpMyAdmin)

Sun Apr 9 23:50:17 UTC 2006

Issue status update for 
http://drupal.org/node/47163
Post a follow up: 
http://drupal.org/project/comments/add/47163

 Project:      Documentation
 Version:      <none>
 Component:    Installation
 Category:     tasks
 Priority:     normal
 Assigned to:  SpzToid
 Reported by:  SpzToid
 Updated by:   SpzToid
 Status:       patch (code needs review)
 Attachment:   http://drupal.org/files/issues/Drupal Install, single-site, phpMyAdmin.zip (169.13 KB)

Attached is the documentation for Drupal Install, single-site,
phpMyAdmin. It is 2 of a series of 4.

SpzToid

Previous comments:
------------------------------------------------------------------------

Tue, 31 Jan 2006 01:44:00 +0000 : SpzToid

As requested by Kieran, via the documentation list, here's a revision of
the installation instructions.

The original doc, written by Dries, details installation on Linux using
the shell. This is an update, with a separate version for installing
using phpmyadmin (based off this text) to follow.

As discussed on the list, the doc is wiki-formatted. The original
(formatted, easy-to-read version) is temporarily available for viewing
at:

http://www.amstercad.com/drupal_installation

I am still massaging the section on .htaccess for multi-site installs,
and have tried to make this clear within the text. While I work on
clarifying the text, others might find this version useful. Hope so.

Please note, this doc is 100% ascii on my system. I'm waiting for the
complete ajax spell-check, which means I haven't spell-checked this
document.

This doc is so long, maybe it could also be split into a single-site,
multi-site set of docs. I will present an idea to the doc list, for
conditional text, that might address such circumstance.

----

!CONTENTS OF THIS FILE
*Requirements
*Optional requirements
*Installation
**Drupal administration
**Customizing your theme(s)
*Upgrading
*More Information

!Conventions Used in This Guide
Single parentheses 'such as this example' are used within paragraphs to
indicate passages of code that may appear on the screen, or what the
user is instructed to enter.

!REQUIREMENTS
Drupal requires a web server, PHP4 (4.3.3 or greater) or PHP5
(www.php.net) and either MySQL (www.mysql.com) or PostgreSQL
(www.postgresql.org).

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 are tested to a lesser extent.

!OPTIONAL REQUIREMENTS
To use XML-based services such as the Blogger API, Jabber, RSS
syndication, you need PHP's XML extension. This extension is enabled by
default in standard PHP4 installations.

Clean URLs simiplify the address of web pages for both humans and
search engines. Clean URLs are optional, although implementation as
part of the Drupal installation process is suggested as a best
practice, for various technical and functional reasons. For example,
search engines will not follow an addressable path that appears
dynamically generated from a database. Clean URLs are also easier for
people to enter by hand.

For Drupal to generate clean URLs, mod_rewrite support is required in
your web server configuration, as well as the ability to use .htaccess
files placed within your Drupal directoy. (More information can be
found in the Drupal handbook on drupal.org.)

!!DETERMINE YOUR PREFERRED METHOD OF INSTALLATION
Drupal can be installed using several different tools and techniques.
Still, there are only two general methods people tend to use.

Most Drupal installations are hosted on Linux, running Apache web and
MySQL database servers, so both of the methods documented here involve
Drupal sites being hosted using this software. You may choose to use
other web or database servers, but they are not as well tested or
documented by the Drupal community as Apache and MySQL have been. 

The first set of installation instructions is for people who prefer to
use a command-line interface to complete the task. 

The second set of instructions, has been written for people using the
Windows operating system, and who are uploading files from their local
workstation to a hosted Linux server. 

The installation process should recocognizeable by anyone familiar with
similar tools, on similar platforms.

The logic and presentation instructions for your site are comprised of
a series of folders and ascii files on the host server. Images and
files available for downloading are also stored in the file system. All
data describing your website content is stored inside a database.
Website content is stored independantly of the website presentation and
logic, to the fullest extent possible.

----
!!DOWNLOADING DRUPAL

The latest Drupal release is always available at http://drupal.org/.

The files are in .tar.gz format and can be extracted using most
compression tools available on all platforms.

1. Download Drupal onto your server. From the Unix command line, enter:

 wget http://drupal.org/files/projects/drupal-x.x.x.tar.gz

 tar -zxvf drupal-x.x.x.tar.gz

A new directory is created, named ‘drupal-x.x.x/’ containing all
Drupal files and directories.

2. Move the contents within ‘drupal-x.x.x/’ to a new location.
Place all of these files and folders inside of your web server's
document root directory.

>From the command line, enter:

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

!!CREATE A DATABASE FOR DRUPAL

In the examples that follow, 'dba_user' is an MySQL username which has
both CREATE and GRANT privileges. Substitute 'dba_user', with an
appropriate database user name for your installation.

3. Create a new database called ‘drupal’.

 mysqladmin -u dba_user -p create drupal

MySQL will prompt for the 'dba_user' database password, and then create
the initial database files. 

4. Login to the database and set permissions

 mysql -u dba_user -p

Again, you will be prompted to enter the 'dba_user' database password.

5. Once you are allowed access to the database, receiving a prompt
fromMySQL, enter following command:

 GRANT ALL PRIVILEGES ON drupal.*
 TO nobody at localhost IDENTIFIED BY 'password';

Substitute the quoted examples, using the details of your own site.

 'drupal' is the name of your database
 'nobody at localhost' is the username of your MySQL account
 'password' is that belonging to this MySQL username

 Query OK, 0 rows affected

6. To assign correct permissions to the database, enter the command:

 flush privileges;

7. To exit MySQL and return to the command line, enter:

 \q

LOAD THE DRUPAL DATABASE TABLES

8.  Once you have a new database, you must install tables into it.

>From a command line, enter: 

 mysql -u nobody -p drupal www.sub.example.com/site3---Drupal will
search for configuration files in the following sequence, using the
first settings.php it can find:

 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 your website address includes a non-standard port number, you must
substitute  the ':' character of your address, (indicating the port
number follows), with a '.' character. For example, the website address
‘http://www.example.com:8080/mysite/test/’ is read by the web server
from the file directory structure as:
‘sites/www.example.com.8080.mysite.test/’.

Each website configuration can have its own site-specific modules and  
 themes that will be made available, in addition to the modules and
themes that are initially installed via the codebase. 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 in-depth information about special configuration
settings, consult the Drupal handbook at drupal.org.

******

On a single Drupal site, the '.htaccess' file is used to conform URLs
as both Drupal and users expect URLs to be. On a multi-site server
installation, a single '.htaccess' file is required for each site, and
both the location and contents of this file are dependent upon both the
server configuration, and the permissions assigned to Drupal.

Instructions are provided for each common installation scenario.
Identify your own installation and/or your best option, and do as
instructed. Choose and act on a single instruction for step 10, and
then skip to step 11.

!Drupal base files installed in the root web directory, accessed as
root.

10.1 The advantage of this setup is that paths work and no alterations
to the .htaccess file are necessary. However some path information is
not available, and name conflicts are a real possibility.

Also, if a symbolic link is made, referring to the Drupal base
installation, scripts and directories outside of the base directory are
not available to any of the Drupal sites.

Multiple Drupal sites can be created anywhere on the Linux box, and
served from a central ly installed Drupal base. But this setup assumes
one actually owns the box, so to speak. Most server applications like
Drupal are professionally hosted, and it is rare for anyone to have
such permissions. However a clued-in home user or small business might
be running such a server setup on their own premises, for example.

!Drupal base files installed in a subdirectory of the web root, and
accessed from a browser as a subdirectory.

10.2 This is a straightforward setup, and might be useful if you have a
single site, but want to make it easy to switch between different
versions of Drupal base directories. 

Put drupal in htdocs/drupal (or make a symlink) and then have
"http://host/drupal" set as the base in "site/host/settings.php". The
drupal .htaccess file stays unchanged: since no Alias statement is
involved you do not need to change the RewriteBase statement. The
symlink version of this is easy for common codebase, but all Drupal
links need to include string '/drupal'. Not terrible, but makes
migrating to such a system difficult if one has an existing web-indexed
or outside-linked system.

!Installed in subdirectory, but accessed as root.

10.3 Starts to get more interesting. Put drupal in a subdirectory (or
more likely make a symlink), then add a .htaccess file in the root
directory that redirects non-existing URL's to '/drupal'. Easy to
upgrade, allows migration from existing installation.

{{{RewriteEngine on
 # Redirect root page to drupal home (if desired)
 # NOTE: without trailing slash, external redirect to /drupal will
 # be used and it will show up in browser. With slash, hidden.
 RewriteRule ^$ drupal/ [L]
 # Rewrite non-file/directory URL's to be under drupal
 RewriteCond %{REQUEST_FILENAME} !-f
 RewriteCond %{REQUEST_FILENAME} !-d
 RewriteRule ^(.*)$ drupal/$1 [L]
}}}

The problem with this approach for a shared hosting setup is that it
requires symlinks that the user probably does not have the
permissions to create. But if you have control of the whole box,
this might not be a bad approach.

!Installed globally (no symlink), accessed as subdirectory.

or

!Installed globally (no symlink), accessed as root.

Finally we reach the case of having multiple sites with separate
document roots running from a common Drupal codebase. These two are
very similar. The rewrite rules in the common drupal .htaccess are
the same for both. 

10.4 Presuming a common Drupal codebase installed in
/var/www/shared/drupal and 'Alias /shared/ /var/www/shared/':

in the common 'drupal/.htaccess':

{{{
 RewriteEngine on
 RewriteBase /shared/drupal

 RewriteCond %{REQUEST_FILENAME} !-f
 RewriteCond %{REQUEST_FILENAME} !-d
 RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]
}}}

Or if you have Drupal aliased directly ('Alias /drupal/
/var/www/drupal/'), set 'RewriteBase /drupal/'.

The rewrite rules in the root of the site will be slightly different:

(in site root .htaccess for Drupal access at root)

{{{
 RewriteEngine on
 RewriteRule ^$ /shared/drupal/ [L]

 RewriteCond %{REQUEST_FILENAME} !-f
 RewriteCond %{REQUEST_FILENAME} !-d
 RewriteRule ^(.*)$ /shared/drupal/$1 [L]
}}}

(in site root .htaccess for Drupal access as subdir /drupal)
{{{
 RewriteEngine on
 RewriteRule ^drupal/(.*)$ /shared/drupal/$1 [L]
}}}

If you want access to look like a subdirectory, you'll want to set
$base_url in 'settings.php' to be equal to whatever your locally
aliased subdirectory is (http://host/drupal in this case). Possibly
usefully, these two rulesets can be combined if necessary to allow for
legacy links if you move from one style to another.

Stray notes:

The checks for -f and -d uses full path information when checking: so
if you have a subdir node but are looking for /node/1, -d is false.
But a search for /node/index.html will match and will be served (if
that file indeed exists). But this might cause a problem when using
other programs that require path_info.

Seems like symlinks are matched by check for "-f file". For example,
if 'file.html' is a symlink to 'real.html', "-f file.html" will be
true, contrary to what the manual says about 'regular files'.

Note that you will need to have "AllowOverride FileInfo" (or greater)
turned of for some directory above where your symlink or alias exists.
Otherwise, the symlink will be followed and the root page will be
accessible, but the RewriteRule's in the .htaccess file in the symlink
will be ignored so the rewrite rules won't work. If you are getting
'page not found' errors, you might put an intentional error in your
.htaccess file just to check that it is actualy being read.

RewriteBase is really hard to understand. When per-directory
(.htaccess) rewrite rules are used, the per-directory portion of the
URL is stripped off before the rule is applied, and then put back
after the rule. When RewriteBase is used, the per-directory portion
is still stripped, but then RewriteBase is put back afterwards.
When does one need this? Whenever one is is running out of an
Alias'ed directory, where the file path no longer matches the URL
path. It's not needed when in a subdirectory (or symlinked
subdirectory), only when dealing with aliases. In this case, one
needs to set RewriteBase to be equal to the current subdirectory but
treating the alias as root. For example, if you have 'Alias /shared/
/var/www/shared', and have Drupal installed under
'/var/www/shared/drupal', the .htaccess in that directory would need
to have 'RewriteBase /shared/drupal' to work correctly.

Moving the site-specific configuration files to live in the
virtual-hosts directory instead of in the common Drupal source base is
a separate matter. It should be easy to solve with some judicious
symlinks, though, or with a very simple patch to change where the
site-specific settings.php files are searched for.

******

!!CONFIGURE DRUPAL

11. Create 2 new subdirectories in your Drupal root directory. Name one
‘files’ and the other ‘tmp’ to adopt the Drupal standard,
however you can choose different directories by adjusting the
appropriate settings at Admin > Settings.

12. Ensure the directory used to store temporary files has correct
permissions with the server.

At the command line enter:

 chmod /tmp 777

13.  Enter the address of your new site in a web browser window.

A login screen is displayed.

14. Click the ‘Register’ tab, enter both a username and E-mail
address, and click ‘Create new account’. Drupal assigns you a
default, random password, AND the user/edit node is displayed,
providing you with an opportunity to change the password to your own
preference. 

The first account created is also known as UID1 (User ID #1), and is
the super-user for this website. This super-user account should only be
used for the site setup, major configuration changes, and upgrades. UID1
has special use and purpose. Do not come to use the first super-user
account for day-to-day administration on your site; create adminstrator
roles later for that purpose.

****

Drupal is now fully-powered and operational.

!!CRON TASKS

Many Drupal modules, such as the Search module, have periodic tasks
that must be triggered by scheduling a cron job to occur at specified
intervals. Search requires regularly scheduled indexing to occur, for
example.

15. To activate these tasks, type the website URL of the cron page in a
web browser address bar, and press Enter, as in this example:

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

Entering this address in a browser’s address bar initiates a script
called cron.php, which permissions all modules that are loaded and
stand to benefit, allowing the modules to operate as they are intended,
with scheduling patterns derived from the modules directly.

Most systems also support the crontab utility for scheduling tasks. The
following crontab example instructs cron to initiate automatically, at
the top of each hour:

 0   *   *   *   *   wget -O - -q http://www.example.com/cron.php

Example scripts are in the ‘scripts’ directory. More information
about the cron scripts are available in the admin help pages and in the
Drupal handbook at drupal.org. 

!!DRUPAL ADMINISTRATION

Upon 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 options to enable and configure services. For
example, set some general settings for your site with ‘Administer >
Settings’. Enable modules via ‘Administer > Modules’. Users can
be set with ‘Administer > Users’.

For more information on configuration options, read through the
instructions accompanying each setting, and consult the various help
pages available at ‘Administer > Help’.

!!CUSTOMIZING YOUR INSTALLATION

The default installation of Drupal includes 4 themes, and are available
at ‘Administer > Themes’. Changing the appearance for an entire site
is as simple as selecting a theme and clicking ‘submit’.

Many more open source themes can be previewed and downloaded for your
own site, at http://themes.drupal.org.

Similarly Drupal is extended by the wealth of modules contributed by
the community, and made available at
http://drupal.org/projects/modules. 

----
!FOR MORE DETAILED INFORMATION

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

------------------------------------------------------------------------

Tue, 31 Jan 2006 05:34:03 +0000 : Amazon

Thanks for doing this: Here is some feedback.

In Drupal we don't use ALL CAPs so change your section titles.

Spelling: URLs simiplify
Spelling: Directory: files placed within your Drupal directoy. (More
information can be found in the Drupal handbook on drupal.org.)
ASCII should be ALL CAPS
fromMySQL
Please put on one line: GRANT ALL PRIVILEGES ON drupal.*
 TO nobody at localhost IDENTIFIED BY 'password';

This seems like a wordy sentence : The glue that connects the logic and
presentation stored in the file system, to your unique database content,
is a text file that is always named settings.php. Edit this file with
specifics to your installation, in order to connect the directory of
files to the database.

CAPITALIZE: www address should be WWW.

I think that Multi-site is sufficiently complex that it should go into
Multi-Site.INSTALL.txt

internet should be Internet

We might want to link to the Multi database, table prefix in the
handbook

Drupal should be capitalized in all cases

Two Words: rulesets

Stray notes needs to be cleaned up

Seems like we should add a files and tmp directory to the Drupal tar
ball.

E-mail should be e-mail.

Seems like we should add a picture of Drupal register account page.

Drupal handbook is at http://drupal.org/handbooks

------------------------------------------------------------------------

Sun, 09 Apr 2006 23:47:49 +0000 : SpzToid

Attachment: http://drupal.org/files/issues/Drupal Install, single-site, Linux.zip (169.44 KB)

Attached is the documentation for Drupal Install, single-site, Linux
(shell). It is 1 of a series of 4.

Drupal Install, multi-site, Linux.zip
Drupal Install, multi-site, phpMyAdmin.zip
Drupal Install, single-site, Linux.zip
Drupal Install, single-site, phpMyAdmin.zip

The docs can be edited directly at www.amstercad.com, a drupal.org ID
should work. Use the contact form to reach me directly.