The following patches clear up a number of minor inconsistencies during a Drupal installation. Largely, this is related to internal documentation and "where things go", but should help organize, clearup, and ease the installation. These aren't features, so they're eligible for a 4.6 commit.

  • The INSTALL.txt no longer contains the SERVER CONFIGURATION block. These settings are now hardcoded into sites/default/settings.php, and are merely scary technical junk here.
     
  • The INSTALL.txt has been updated with the latest system requirements. A whole sentence was struck regarding differing versions of PHP for the OSs.
     
  • The INSTALL.txt contains URLs to MySQL and PostgreSQL. If we're including the URL for PHP in the same sentence, then there's no reason why we wouldn't include them for the database engines. What are the minimal requirements for the RDBMS? Those should be included here too.
     
  • The INSTALL.txt's OPTIONAL COMPONENTS has renamed to OPTIONAL REQUIREMENTS. The only difference between the meaning is the amount of user confusion.
     
  • The INSTALL.txt has a new CONTENTS OF THIS FILE, in hopes that people will more immediately notice that there are upgrade instructions at the bottom.
     
  • The INSTALL.txt had some potentially confusing lines adjusted, including further clarifications, standarding to "userid" (instead of using both userid and username interchangebly) and so on.
     
  • I've moved most of .htaccess php_value's to the ini_set system for /sites/. There are a few reasons for this, chiefly that it is centralizing all the PHP setting modifications to one place. But, this also clears up a few initial configuration issues: first, the user doesn't have to worry about whether they have Apache 1 or 2, and whether they need to change an IfModule line. Also, the running assumption is that these php_value's are /going to work by default anyways/, when the INSTALL.txt suggests otherwise (under OPTIONAL REQUIREMENTS, it talks about "the ability to use local .htaccess files", which suggests that "local .htaccess files" INCLUDING "mod_rewrite" are entirely optional.) Some variables, however, had to remain in .htaccess because they can't be overridden at runtime, but the amount was so small that duplicating them for both Apache 1 and Apache 2 possibilities is no longer a prohibitive concern.
     
  • There are two variables in .htaccess that I'm concerned about: track_vars, and allow_call_time_pass_reference. track_vars appears to be no longer necessary (as of 4.0.3, track_vars is always on, and my setting it here had no impact on the results of a phpinfo), and allow_call_time_pass_reference seems, at least here, to ONLY WORK if the .htaccess value is set to "1", and not "On" - meaning that Drupal installations are currently working correctly with its default value (off). According to the PHP docs, this feature is now deprecated. However, since both of these variables require further investigation, track_vars has been moved to settings.php, and allow_call_time_pass_reference has been "fixed" to a 1 (not 'On').
     
  • Along with the changes above for sites/default/settings.php, I've also removed the spacing indent in the documentation, as well as many a few grammatical/punctuation changes here and there. I don't think the leading spacing is "right" according to the style guidelines, but maybe there's a special need for it. Correct me if I'm wrong.
     

These patches were made during the exploration and customization of Drupal by NHPR.org. In loving support of open source software, NHPR.org will continue to contribute patches they feel the community will benefit from.

CommentFileSizeAuthor
#36 _18641_symlinks.patch1.68 KBMorbus Iff
#31 05_cleandocs3_0_0.patch2.27 KBkilles@www.drop.org
#23 05_cleandocs3_0.patch2.25 KBkilles@www.drop.org
#21 05_cleandocs3.patch2.26 KBMorbus Iff
#19 03_cleandocs2_2.patch5.33 KBMorbus Iff
#18 03_cleandocs2_1.patch3.9 KBMorbus Iff
#17 03_cleandocs2_0.patch3.69 KBMorbus Iff
#10 03_cleandocs2.patch3.33 KBAnonymous (not verified)
#4 patch01_INSTALL.txt_0.patch10.27 KBMorbus Iff
#3 patch01_settings.php.patch6.21 KBMorbus Iff
#2 patch01_INSTALL.txt.patch10.26 KBMorbus Iff
#1 patch01_.htaccess3.36 KBMorbus Iff
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Morbus Iff’s picture

Morbus Iff
they/them
CreditAttribution: Morbus Iff commented
FileSize
patch01_.htaccess3.36 KB
Morbus Iff’s picture

Morbus Iff
they/them
CreditAttribution: Morbus Iff commented
FileSize
patch01_INSTALL.txt.patch10.26 KB
Morbus Iff’s picture

Morbus Iff
they/them
CreditAttribution: Morbus Iff commented
FileSize
patch01_settings.php.patch6.21 KB
Morbus Iff’s picture

Morbus Iff
they/them
CreditAttribution: Morbus Iff commented
FileSize
patch01_INSTALL.txt_0.patch10.27 KB

Slight revision of the previous INSTALL.txt patch. One of the added Contents was listed wrong.

Chris Johnson’s picture

Chris Johnson CreditAttribution: Chris Johnson commented

Well done. Cleaning up this kind of stuff is not as exciting as cutting code, but it really helps the over-all quality. My hat is off to you.

Dries’s picture

Dries CreditAttribution: Dries commented

Good stuff! Committed to HEAD. Thanks Morbus.

Morbus Iff’s picture

Morbus Iff
they/them
CreditAttribution: Morbus Iff commented

Dries - did you mean to remove the ".conf" extension from the .htaccess Deny?

Morbus Iff’s picture

Morbus Iff
they/them
CreditAttribution: Morbus Iff commented

Oh wait. Nevermind. We don't have any of those extensions anymore. My bad.

TDobes’s picture

TDobes CreditAttribution: TDobes commented

As for allow_call_time_pass_reference, I would tend to agree that we don't need it at all. See this drupal-devel topic from a while ago. Since then, I've been running with it in the "OFF" state and have experienced no problems with core or a variety of contrib modules and themes. See also: the php.net description of why it's deprecated.

One comment about the INSTALL.txt changes: I think you meant PHP 4.3.3 as the minimum version... not 4.33. :-)

With 4.3.3 as the minimum requirement, I'd also say it's safe to get rid of track_vars... I see no difference with it removed.

Also: Why do we have short_open_tag in there? I'm pretty sure we use the long form of the php open tag throughout Drupal and almost all contrib modules. (those that do not should be fixed, IMO)

Anonymous’s picture

(not verified) CreditAttribution: commented
FileSize
03_cleandocs2.patch3.33 KB

Per TDobes comments:

* INSTALL.txt corrected to use 4.3.3, not 4.33.

* .htaccess: removed allow_call_time_pass_reference. two confirmations that a) the setting was wrong in the first place, b) there were no adverse affects for the incorrect setting, c) the PHP docs say it is deprecated.

* .htaccess: removed short_open_tag. Running grep -r "<? " * across the entire directory tree of both core and contributions only brought up contributions and no core. I agree that the fuller form is better. The following contributions will need to be updated:

modules/edit_template/edit_template.module
sandbox/garym/themes/marvin_2k/templates/page.tpl.php
sandbox/killes/compare.php
sandbox/paolino/import/click.php
themes/spreadfirefox/block.tpl.php

For error's sake, I also did a manual verification for "<?" (no space) across core and came up against nothing in addition to the above contribs.

And my own further analities:

* .htaccess: cleaned up some whitespace valleys (i hate 'em, hate 'em!) and fixed a few stray colons.

* settings.php: minor whitespace error.

Morbus Iff’s picture

Morbus Iff
they/them
CreditAttribution: Morbus Iff commented

Comment #10 is mine.

TDobes’s picture

TDobes CreditAttribution: TDobes commented

Looks good to me. +1

Gábor Hojtsy’s picture

Gábor Hojtsy
he/him
Primary language Hungarian
Location Hungary
CreditAttribution: Gábor Hojtsy commented

Do not depend on PHP.ini defaults please. It would be essential to get back the session.auto_start 0 setting into .htaccess, or otherwise those, who have this turned on in their PHP will get ugly errors, since the database session handler will not be able to initialize and work at all...

Morbus Iff’s picture

Morbus Iff
they/them
CreditAttribution: Morbus Iff commented

Per the already-committed patch, session.auto_start 0 has been moved to sites/default/settings.php. Per the PHP documentation, session.auto_start is a runtime variable: http://us4.php.net/session.

Gábor Hojtsy’s picture

Gábor Hojtsy
he/him
Primary language Hungarian
Location Hungary
CreditAttribution: Gábor Hojtsy commented

Morbus, read this in the manual: session.auto_start specifies whether the session module starts a session automatically on request startup Request startup, you see? It might be possible to modify the setting later, but if session auto start is enabled on the server, it will start the session with the handler set in php.ini (the "files" handler by default) and you will not be able to use a different handle later on. Have you tried it? We just provided support to a clueless user at drupal.hu, who had this auto start turned on and then the ini_set() was unable to change the save handler. Although the linked comment is hungarian, all the PHP codes and PHP errors are English, and are easy to understand.

Gábor Hojtsy’s picture

Gábor Hojtsy
he/him
Primary language Hungarian
Location Hungary
CreditAttribution: Gábor Hojtsy commented

BTW track_vars would also be pointless to set from PHP, since it is also affecting request startup processing, but quoting from the manual: Note that as of PHP 4.0.3, track_vars is always turned on. – and given Drupal's PHP requirements, it is not needed anymore.

Morbus Iff’s picture

Morbus Iff
they/them
CreditAttribution: Morbus Iff commented
FileSize
03_cleandocs2_0.patch3.69 KB

Confirmed. Updated version of patch #10 attached.

Morbus Iff’s picture

Morbus Iff
they/them
CreditAttribution: Morbus Iff commented
FileSize
03_cleandocs2_1.patch3.9 KB

This patch removes track_vars entirely.

Morbus Iff’s picture

Morbus Iff
they/them
CreditAttribution: Morbus Iff commented
Priority: Normal » Critical
FileSize
03_cleandocs2_2.patch5.33 KB

Updating this to critical, as the previous patch broke the build (see Goba's comments).

Per TDobes' comments:

  • INSTALL.txt corrected to use 4.3.3, not 4.33.
  • .htaccess: removed allow_call_time_pass_reference. two confirmations that a) the setting was wrong in the first place, b) there were no adverse affects for the incorrect setting, c) the PHP docs say it is deprecated.
  • .htaccess: removed short_open_tag. Running grep -r "<? " * across the entire directory tree of both core and contributions only brought up contributions and no core. I agree that the fuller form is better. The following contributions will need to be updated: modules/edit_template/edit_template.module, sandbox/garym/themes/marvin_2k/templates/page.tpl.php, sandbox/killes/compare.php, sandbox/paolino/import/click.php, themes/spreadfirefox/block.tpl.php. For error's sake, I also did a manual verification for "<?" (no space) across core and came up against nothing in addition to the above contribs.

Per Goba's comments:

  • .htaccess: Moved session.auto_start back.
  • sites/default/settings.php: Removed track_vars.

Per mailing list comments:

  • INSTALL.txt: Added text about the files/ directory, creating it, and permissions.
  • INSTALL.txt: Added an example of why Drupal requires cron (the search.module) in an attempt to justify why a crontab is a good, nay, required step.

And my own further analities:

  • .htaccess: cleaned up some whitespace valleys (i hate 'em, hate 'em!) and fixed a few stray colons.
  • settings.php: minor whitespace error.
Dries’s picture

Dries CreditAttribution: Dries commented

Committed to HEAD.

Morbus Iff’s picture

Morbus Iff
they/them
CreditAttribution: Morbus Iff commented
Priority: Critical » Normal
FileSize
05_cleandocs3.patch2.26 KB

Adding a block per this thread regarding subdirectory vhosting.

Dries’s picture

Dries CreditAttribution: Dries commented

The problem mentioned in that report looks like a bug report to me. The sim-link stuff shouldn't be necessary, or am I wrong?

killes@www.drop.org’s picture

killes@www.drop.org CreditAttribution: killes@www.drop.org commented
FileSize
05_cleandocs3_0.patch2.25 KB

Updated the patch to use hard links instead. suggestion from: http://drupal.org/node/278#comment-30623

Morbus Iff’s picture

Morbus Iff
they/them
CreditAttribution: Morbus Iff commented

Dries - the symlink stuff is necessary when you consider a site without clean URLs enabled. In a normal old site without rewrite, http://www.example.com/subdir isn't going to be controlled by Drupal at all - Apache is going to happily look for and then serve something from that directory. The symlink is there to say "Apache, this location exists, but we want to send you back to the Drupal installation so that it can handle the request based on the URL".

Morbus Iff’s picture

Morbus Iff
they/them
CreditAttribution: Morbus Iff commented

Oh, and killes revision is +1.

killes@www.drop.org’s picture

killes@www.drop.org CreditAttribution: killes@www.drop.org commented

The patch should really be applied the problem is going to be popular:
http://drupal.org/node/19305

Dries’s picture

Dries CreditAttribution: Dries commented

Jim Riggs is looking into this as well. Let's wait a bit longer for his feedback.

Morbus Iff’s picture

Morbus Iff
they/them
CreditAttribution: Morbus Iff commented

Any word on this one? If there's no code fix in time for next week, then the docs should be amended with this.

jhriggs’s picture

jhriggs CreditAttribution: jhriggs commented

Currently, as has been noted, this does not work without creating a link. Personally, though, I strongly recommend against using hard links. I spend all day in various Unices, and I never have need to make a hard link. Hard links are Bad™. So if we update the docs, I recommend that is gives instructions for symlinks. Note that the latest patch is mix-and-match. It has one hard and one symlink example.

I do have some code that would allow one to have subdirectory-based sites without doing a symlink, but I am not sure how comfortable I am with it. I would like to discuss it with Dries.

Morbus Iff’s picture

Morbus Iff
they/them
CreditAttribution: Morbus Iff commented

This patch contains the softlink instructions, before the hardlink modification. It's still commitable. I'm having problems contemplating how your (proposed, unseen) patch would work on a non-mod_rewrite site though.

killes@www.drop.org’s picture

killes@www.drop.org CreditAttribution: killes@www.drop.org commented
FileSize
05_cleandocs3_0_0.patch2.27 KB

patch with symlinks not hard links.

Dries’s picture

Dries CreditAttribution: Dries commented

Can't we use 'subsite' instead of 'site3'. The name 'site3' seems pretty random and is not very descriptive IMO.

(Does everybody think this kind of information is a good thing? Sometimes I fear that this is going to scare or confuse the heck out of people who don't need all this 'mambo jambo'. Maybe stuff like this belongs in an 'advanced setups' section.)

Morbus Iff’s picture

Morbus Iff
they/them
CreditAttribution: Morbus Iff commented

I still stand behind the (identical) patches in #30 and #31.
I don't see how a non-symlink solution will work with mod_rewrite.

Regarding Dries' comments:

* I don't like "subsite" - it presumes too much (that it is some "subset" of a greater whole)
* The information is a "good thing" because otherwise, people will wonder why it doesn't work.
* Multiple files and vhosting is ALREADY an advanced topic; there is no other place for it, IMO.

tag-1’s picture

tag-1 CreditAttribution: tag-1 commented

Regarding site terminology:

I may be tainted from different langs/environments, but the idea of multiple sites off of the same codebase seems more like "instances" than subsites or alternate sites. Basically OO terminology (and Oracle FWIW).

I'm not sure if that more precise/technical naming might be more confusing to newcomers -- but even if it is, it might be less confusing than "sub" or "alternate" sites which have different (often non-applicable) connotations.

Re: symlink instructions - a quasi-patch, I'm not properly setup here:

- as www.example.com/site3), it's important that the subdirectory exists
- and refers back to the primary location of your Drupal install. For

+ as www.example.com/site3), it's important that you create a symlink
+ that refers back to the primary location of your Drupal install. For

I would think the original version here will lead to 9/10 users getting "Can't create link: directory already exists" errors because they'll create 'site3' before running `ln`.

I'm personally in the middle of working on a "many instances" setup so I just recently ran into the haziness of the docs here... will try to help out once I've run though the actual process some more.

Crell’s picture

Crell CreditAttribution: Crell commented
Status: Needs review » Needs work

Patch no longer applies. Given the changes to settings.php and INSTALL.txt in recent weeks, is this still needed?

Morbus Iff’s picture

Morbus Iff
they/them
CreditAttribution: Morbus Iff commented
Title: Usability tweaks: INSTALL.txt, .htaccess, settings.php. » INSTALL.txt: Include notes about Drupal subdirectories
Status: Needs work » Reviewed & tested by the community
FileSize
_18641_symlinks.patch1.68 KB

Still needed - helped two #drupal-support users in two weeks with this exact problem.
Setting to commit, updated for HEAD.

oadaeh’s picture

oadaeh CreditAttribution: oadaeh commented

This is a big +1 for me. I spent quite a bit of time looking for the reason my multi-site installation wasn't working. I found a lot of irrelevant topics, but never found this issue. I could have had the whole thing working yesterday if it had been in the INSTALL.txt file earlier. Thanks again, Morbus.

sepeck’s picture

sepeck CreditAttribution: sepeck commented

NOTE: If you want a separate Drupal installation under a subdirectory
(such as www.example.com/site3), it's important that you create a symlink
that refers back to the primary location of your Drupal install. For
example, if your primary installation is located in the directory
www.example.com, then the following shell command run in the
www.example.com directory would create a symlink for site3:

This is a little unclear to me and it's probably just me but... Is this for multisite on the same code base for when you want the settings directory in some users home dir?

drumm’s picture

drumm
he/him
Location NY, US
CreditAttribution: drumm commented
Status: Reviewed & tested by the community » Needs work
Jaza’s picture

Jaza CreditAttribution: Jaza commented
Version: x.y.z » 6.x-dev

This is still very much needed. Perhaps you should also add a note that the shell command in question needs to be run in a *nix environment, and that it's not possible to create symlinks (and hence to have a proper multi-site setup) in Windows (at least, not without the help of third-party tools, such as Junction Link Magic - and only when using NTFS volumes).

babbage’s picture

babbage CreditAttribution: babbage commented
Status: Needs work » Closed (duplicate)

Marking this as duplicate of current issue #285053: Improve INSTALL.txt description of multi-site installation with subdirectories as that has an up-to-date patch.