[pmwiki-users] RFC: PITS 00701 -- WikiFarm confusion

[DaveG]

Summary:
  - The process is *much* easier than the WikiFarms instructions lead me 
to believe. 4 (maybe 5) basic steps was all that were needed -- KISS! I 
propose defining the *goal* of a farm, define a farm and a field, and 
then describing the 5 or so steps. Other info can follow in sections after.

  - There is a conceptual sticky in that adding a new field to an 
existing install means we now have two fields, one of which is in the 
pmwiki directory structure, and which uses a config.php in what is now 
the Farm local/ directory. I had actually thought that the farm 
local/config.php would provide settings across the fields -- this 
appears not to be the case?

  - Given that this is not the case, I now need to create a new 
config.php in my field directory. Minor point, but it's the last step.

  - What I suspect I ened to do is include $FarmD for all my cookbooks 
included in pmwiki/local/config.php. How do I also get markups inherited 
to the fields? Ah... Now I see "A farm administrator can use the 
local/farmconfig.php file for customizations to be applied to all fields 
within the farm." -- make this clearer up front, as one of the steps. 
"Configurations that you want to be global across sites, should be made 
in farmconfig.php. You may want to move some settings from your existing 
config.php into farmconfig.php"

------ Thoughts during conversion:

  - I'm converting an existing install to a Farm based install. What 
I'll end up with is a base install, and two fields. The fields consist 
of what directories? Just a wiki.d, or also Uploads, Pub, etc? Because 
what will happen is I'll have a field in a new location probably away 
from the pmwiki directory. My initial site will now become a field but 
will remain inside the base pmwiki directory. Conceptually this is 
confusing. But at the very least the install instructions should make 
this explicit. "Your initial pmwiki site will become a field, which 
resides in the base PmWiki directory", or something similar.

  - Step 1: I create farmconfig.php in the main pmwiki/local directory. 
At this point I'm a little confused. "$FarmPubDirUrl is used to provide 
fields with the URL location of the farm's pub/ directory." Suggests the 
skins for all fields are in this directory. For shared skins this makes 
sense. Where the user wants totally separate sites, it might not. Make 
this explicit in the instructions.

  -- Step 1b: Upload the farmconfig.php and check the existing site... 
it still works :) Nothing like working on a live site :)

  -- "This file would contain any local customizations that are to be 
performed for every field in the farm". A little confusing. "Local 
customizations" that are global across sites...?

  - Step 2: I created a new directory in public_html for my new 
wiki-field, and created a pmwiki directory.

  - Step 3: Uploaded index.php, with an include pointing to 
"../pmwiki/pmwiki.php"

  - Step 4: Pointed a browser to index.php... "Warning: 
main(../pmwiki/pmwiki.php): failed to open stream: No such file or 
directory in /home/nepherim/public_html/quiddity/pmwiki/index.php on 
line 1".

    Doesn't seem to like the relative path, so change index.php to use 
an absolute path "/home/nepherim/public_html/pmwiki/pmwiki.php". Browser 
now responds with a wiki page, and the wiki.d directory is created.

  - Step 5: I presume I need to change the attribs back... but to what?


  ~ ~ Dave

DaveG wrote:
> Here's my thoughts as I read the WikiFarm page in order to setup a 
> field. All I'm doing here is reading, and taking notes in preparation 
> for setting up the farm. Comments on the actual process will follow.
> 
> ------ Main Introduction
>   - The first paragraph attempts to define a farm, and then set some 
> standard terms. Make the farm explanation one paragraph, and the 
> definitions a bulleted list, so it can be referred to as the read 
> progresses down the page.
> 
>   - "Each field must have its own URL" -- that's confusing. The 
> significant part of this is that each field lives in it's own directory, 
> and each field is accessed by a slightly different URL. An example would 
> help. But I'm not really sure it's that relevant, not at this stage.
> 
>   - For a description of what goes where, the reader has to head off to 
> QuickFarms... QuickFarms isn't terribly useful -- however the idea of a 
> sample directory structure is, and should be on the WikiFarm page.
> 
>   - I like the idea of splitting the doc into farm and field 
> administrator sections. I would suggest making the header style stand 
> out more to visually break the page up a little.
> 
> ------ "Setting up a WikiFarm (farm administrator)"
>   - When converting an existing installation to a field based 
> installation, does the existing directory structure remain? Is it 
> necessary (or desirable) to move the existing wiki.d, skins, uploads, etc?
> 
>   - "Usually, this will mean setting $FarmPubDirUrl to reasonable 
> settings for the new field." Too vague. What are reasonable settings? 
> What other directory variables need to be set? Seems odd that it's only 
> this one, and not Uploads, Script, Img, etc. At this point I start 
> getting cold feet, and wonder at the affect on my existing install. This 
> brings to light a point: it's good practice to be doing this level of 
> change on a local PmWiki install before hitting the live site... but how 
> many admins (particularly of smaller sites) actually follow this 
> practice, and thus may hit some unclarity in the instructions, and 
> simply stop with the thought "Yoikes"?
> 
>   - The field admin steps are pretty good. Clear, and presise. Step 3 
> however changes permissions to 777, and at no point do we change them 
> back. Is this desirable?
> 
>   - Step 4 (field admin) is the kicker. All directory structure creation 
> is automatic! This should be stated up front, on the very first paragraph!
> 
>   - ?One significant omission is that if CleanURLs are in use, changes 
> will need to be made when
> 
> ------ "Local customizations in fields and farms"
>   - My first thought is what typically *needs* to be set locally? 
> Specifically directory paths?
> 
>   - This is the first mention of $FarmD. It immediately occurs to me 
> that this variable should probably be used for all Cookbook includes on 
> in the main config.php. (Note I used the work "main" not Farm -- seems 
> more understandable! Actually even Parent sounds better.) At this point 
> I have no idea if I want to proceed....
> 
>   - The override stuff is good, but should be separated with a header 
> (don't split it on a separate page).
> 
>   - "If extension scripts are used farm-wide": What is an "extension 
> script"? Term is not used anywhere else. I think it refers to Cookbooks.
> 
>   - "used farm-wide and they are located in the farm's cookbook 
> directory they should be loaded through entries in local/farmconfig.php 
> like": Means that if $FarmD is not used in the main config.php then it 
> will not be used site-wide? Will it be used for the "base" wiki.d field 
> (if converting an existing site)?
> 
> ------ "Notes"
>   - No comments on here yet.
> 
> 
> Next step, to attempt farming :)
> 
>   ~ ~ Dave
> 
> Patrick R. Michaud wrote:
>> The following message was just posted to PITS (#00701), and I need
>> help coming up with good answers.
>>
>> >From PITS 00701:
>>> I've read and reread the Wiki Farms installation, all of them, 
>>> i've been trying to figure it out to no avail. i understand how 
>>> they are suppose to work, but the explanation of how to install 
>>> one, seems like it misses huge chunks out. or uses alot of 
>>> jargon, if anyone can point me to a easier explanation, or 
>>> even a zipped install farm structure i'd be very greatful.
>> Personally, I find the PmWiki.WikiFarms instructions to be
>> just about as straightforward as they can be, but I totally
>> admit that I'm not representative in this respect.
>>
>> On the other hand, I've read some of the other farm setup
>> instructions that others have posted on the mailing list and
>> in the Cookbook, and they often seem to me to be confusing and
>> possibly needlessly complex.
>>
>> Thus I fear WikiFarms may be in a somewhat similar situation as the
>> CleanUrls recipe, where people can envision many different ways
>> to solve a similar problem, and PmWiki happens to be flexible
>> enough to support most or all of them, and so we don't have
>> a clear set of instructions for it.
>>
>> So, I could use some help here from people who have set up
>> WikiFarms and struggled with it -- what is it about WikiFarms
>> (and the associated documentation) that is confusing?
>>
>> Or, if you aren't running a wiki farm but have been curious to
>> try, now would be a great time to do it --  whenever you run across
>> something that is confusing or doesn't make sense, post the
>> question to the list and we'll see if we can explain it (and
>> improve the docs so that the question doesn't arise in the future).
>>
>> Comments?
>>
>> Pm
>>
>> _______________________________________________
>> pmwiki-users mailing list
>> pmwiki-users at pmichaud.com
>> http://host.pmichaud.com/mailman/listinfo/pmwiki-users
>>
> 
> _______________________________________________
> pmwiki-users mailing list
> pmwiki-users at pmichaud.com
> http://host.pmichaud.com/mailman/listinfo/pmwiki-users
>