Drupal

= Introduction =

According to most sources, Drupal is one of the more powerful CMS's available. Drupal installations can be tricky, and the error messages can be very misleading.

As of this writing, I am using


 * apache-2.2.16
 * mysql-5.1.51
 * php-5.3.5

= Acquire the Source = Get the Drupal source (drupal.org) either directly from drupal.org, or install it from the portage tree.

Directly from drupal.org
wget http://ftp.drupal.org/files/projects/drupal-5.20.tar.gz
 * 1) download the source with wget, or fetch from your favorite browser

tar -xzf drupal-5.20.tar.gz
 * 1) Unpack it somewhere appropriate

From portage
Currently (and I think this is often the case) Drupal is marked as unstable/testing. So you'll have to add to your package.keywords file.

echo "www-apps/drupal ~x86" >> /etc/portage/package.keywords # add drupal keyword

Install from portage

= Database =

Drupal works with a number of databases. There seems to be a lot of support for PostGresQL and MySQL. It is assumed that you already have MySQL installed with a 'root' user and the root user's password.

First, we'll need to create the database itself:

Next, we'll need o set up the MySQL user and make the appropriate privilege grants. First, log into mysql:

Next, the commands:

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, LOCK TABLES, CREATE TEMPORARY TABLES ON databasename.* TO 'username'@'localhost' IDENTIFIED BY 'password'; FLUSH PRIVILEGES; show grants for 'username'@'localhost';

The last command, show grants, is for piece of mind. Once you are done and satisfied all went well, just:

quit;

You should be all set with the database.

= Webserver =

Choose a webserver. I used Apache, it is very well supported. There are others too. See the Apache documentation or the Lighttpd documentation for more details.

I have my Drupal site running in a vhost environment. Drupal does support multi-site installations.

= Multiple vhosts = If, like me, you're running more than one vhost on your Apache [insert httpd name here] server, Portage will install Drupal to /usr/share/webapps, not /var/www. You have to perform another step to copy the new Drupal install to your chosen vhost:

where -I means install, -h tells webadpp-config what directory and server-name to install to (under /var/www), -d drupal means install in a subdirectory drupal (/var/www/example.com/htdocs/drupal), drupal means, of course, the application to install and 7.0 is the version to install. Simple.

Periodically you'll also need to update your Drupal installation - best keep up to date with security fixes. You can do so through webapp-config of course:

Of course, if you've installed Drupal to multiple vhosts, you should do the above for each. If you don't use vhosts, of course Portage will do the update for you.

Don't forget to use Drupal's own scripts to update for any database changes etc. afterwards - you will be prompted next time you log on to your Drupal site.

''Make sure you read the upgrade documentation first. It seems that Drupal configs can get wiped out with incredible ease.''

= PHP =

As of this writing, webapp-config makes a note that for a secure installation, enable session.cookie_secure in php.ini files. Don't take the bait unless you understand the consequences. For the initial configuration, you should make sure that this is not enabled. If you enable it and the site isn't properly configured for SSL, Drupal installation will fail miserably, and just for fun, it will give you error messages that will send you off on many wild goose chases.

You also will need to make sure that all the appropriate PHP use flags are set. Here are mine. I have no ieda which ones will break Drupal, but after much tribulation I came up with these: emerge -pv php

[ebuild  R   ] dev-lang/php-5.3.5  USE="apache2 berkdb bzip2 cli crypt ctype curl fileinfo filter ftp gd gdbm hash iconv imap ipv6 json mhash mysql mysqli nls odbc pdo phar posix readline session simplexml sqlite sqlite3 ssl tokenizer truetype unicode xml xmlreader xmlrpc xmlwriter xsl zip zlib -adabas -bcmath -birdstep -calendar -cdb  -cgi -cjk -curlwrappers -db2 -dbmaker -debug -doc -embed -empress -empress-bcs -enchant -esoob -exif -firebird -flatfile -fpm -frontbase -gd-external -gmp -inifile  -interbase -intl -iodbc -kerberos -kolab -ldap -ldap-sasl -libedit -mssql -mysqlnd -oci8 -oci8-instant-client -pcntl -pic -postgres -qdbm -recode -sapdb -sharedext  -sharedmem -snmp -soap -sockets -solid -spell -suhosin -sybase-ct -sysvipc -threads -tidy -wddx -xpm" 0 kB

For sure, you'll need session, simplexml, filter, mysql, mysqli, pdo, and json. Your mileage may vary.

Note: for <= dev-lang/php-5.2, you will need to enable the spl USE flag as well. otherwise, you will get a "undefined function class_implements" during the Drupal install.

= Getting Things Going =

It is advisable that you install Drupal, configure the database, and then run webapp-config. Remember, if webapp-config suggests setting session.cookie_secure in your php.ini files, don't do it -- don't even think about it -- unless you are absolutely sure that secure cookies will work (if you're wondering, then assume that they won't). I did a locate on php.ini and then grep'd for session.cookie_secure and made sure that they all were commented out. on my installation they were not, so I fixed them and restarted apache (make sure you restart apache).

As soon as you have done all that work, click on the link that says "visit your site".

If you get an error message that says something about a PDO error, well, uh-oh. Check you have the pdo USE flag set, re-emerge php and restart apache. Check the secure cookie thing, it is the number one issue. If that doesn't fix it, it's going to be a long night. First thing to do is count the tables created. If it the count is in the low-30's, you'll most likely need to delete drop the drupal schema, and delete the site files from /var/www/my/drupal/directory and re-run the database installation part and the webapp-config part again.

When you go through the installer, there is a place for advanced options. You can add a table prefix name, such as drupal_ or site01_ or whatever.

Post Installation Clean-up
Once you're all done and your Drupal site isup and running, there is an important security-related cleanup matter you'll need to look after... Don't skip this step.

In your site installation directory (e.g., /var/www/www.mydrupalsite.com/htdocs/ ) you will need to remove write permissions to sites/default and sites/default/settings.php

If you are unsure how to do so, consult the Drupal online handbook.

Finally
Read the Drupal site docs if you haven't already. The options are dizzying.

Enjoy.

= See also = PHP Apache Lighttpd Drupal