[wiki] Multi-Site Install Quirks

maverick · 2011-02-10 16:06:04

Introduction:

I’ve been thinking for a while that it would be helpful (to me at least) if there was a place that acted as a working repository for all things related to the challenges of Txp’s multi-site installation. Multi-site seems to be a bit of a murky proposition, but there’s more info out there than one may realize. It’s just scattered.

Ideally, in a polished form it belongs on the wiki, but I thought we’d get more traffic in the forum. I’m not sure if this part of the forum is the best place to post, but I thought it was a place to start.

Each of the first several posts of the thread can cover a specific area:

Post 2 – How Tos (Internal and External Links)
Post 3 – Normal Txp functions that do not work as expected and work arounds
Post 4 – Plugins that do not work with Multi-Site Installs, and/or need to be modified to work
Post 5 – Other Issues, Quirks, etc.
Post 6 – Feature/Fix Request

As people add to the collective wisdom I’ll try to update those posts accordingly. (Of course any of the moderators are welcome to do so as well). Hopefully we can take the most useful and copy it to the user docs.

Mike

maverick · 2011-02-10 16:08:08

How Tos (Internal and External Links)

Textpattern Multi-Site Howto by Sam Weiss

Multiple Sites with a Single Install @ Wiki/User Docs

Rationale for setting up a ssl-secured subdomain for the admin

Sites Outside Main Directory

Textpattern multisite setup by Jeff Soo

Multi-Sites Setup @ Txp Tips

Redirect /textpattern to /admin for multi-site installs @ Txp Tips

Textpattern Multi-Site Helper Script by Sam Weiss

Redirect /textpattern to the correct admin by Julián Landerreche

File Tree for Sites Outside of Main Txp Directory by Jeff Soo

Last edited by maverick (2011-02-10 16:48:15)

maverick · 2011-02-10 16:10:18

Normal Txp functions that do not work as expected and work-arounds

When using a unique admin domain – New user registration email will contain the wrong url in the login
Draft article preview doesn’t work
Diagnostics:
- Does not check for setup directory in sites/mysite/admin
- Warning message for textpattern/setup, even for setups where this is outside the public side
- Warning message for site_url preference

Last edited by jsoo (2011-02-10 16:51:53)

maverick · 2011-02-10 16:11:55

Plugins that do not work with Multi-Site Installs, and/or need to be modified to work

rvm_privileged – does not work if you use an alternate admin domain

arc_twitter requires a work around. Two options discussed here

smd_prognotstics requires a work around. Discussion begins here

lum_usermenu will render a blank page when used on a multi-site install that utilizes a separate/sub-domain admin. Update: This issue results from a combination of multi-site and the version of php being used. php 5.2.15 exhibited the issue. Multisites using php 5.3.2-2 and php 5.3.5 do not exhibit the issue.

Last edited by maverick (2011-03-22 17:24:17)

maverick · 2011-02-10 16:12:57

Other Issues, Quirks, etc.

The single Admin Themes folder makes all themes available to all installs.
- Plus – It’s fast and simple to deploy an admin theme across multiple sites
- Neg – If you are using smd_admin_themes you are able to edit the themes, thus you can affect users on other domains.
  - If privileged, a user on one site could edit their theme and mess up a user on another site using the same theme
  - That above ability “feels” like a possible security vulnerability
  - You may have to manage multiple variations of a theme if you customize one for a specific site

==

If you choose to secure Txp’s admin side using a ssl-secured subdomain, remember that the public side has a sym link to the admin folder that allows www.domain.com/admin to reach your subdomain.
- If you reach your domain using this url, your domain’s login cookie will work and likely resolves the issues with plugins.
- Your diagnostics may show a clean url fail but clean urls still work
- Is the security goal of using an admin subdomain frustrated?
- Can the sym link be removed without breaking anything?

==

symlink caution: symlinks are treated as if they are the actual directory. If you need to delete symlinks, or directories with symlinks, you may need to use the command line, and the proper command. Some ftp programs will delete the original file or directory.

==

Windows symlinks: the symlinks included in the Txp distribution may not be compatible with Windows. Obsidian has notes on this issue.

Last edited by jsoo (2011-04-13 11:40:19)

maverick · 2011-02-10 16:13:45

Feature/Fix Request

An Admin URL preference – This would be one possible fix for several issues where .hu is used

Last edited by maverick (2011-02-10 18:29:31)

maverick · 2011-03-19 04:01:33

Bug Report:

Issue: xml-rpc returns a 404 error in multi-install

Status: Pending Confirmation

Description:

Was setting up ScribeFire for a client. Websites with a stand-alone standard install work fine. Websites that are using a multi-site install are returning 404 errors.

Can anyone else confirm this?

marjoleink · 2011-04-27 23:08:45

maverick wrote:

Introduction:

I’ve been thinking for a while that it would be helpful (to me at least) if there was a place that acted as a working repository for all things related to the challenges of Txp’s multi-site installation. Multi-site seems to be a bit of a murky proposition, but there’s more info out there than one may realize. It’s just scattered.

Mike, reading through this thread (after your invitation to contribute), the first thought that came up with me was that it would be good to make a clear distinction between setting up and directory structure and the installation process on the one hand, and operation and maintenance of a working multi-site installation on the other.

Since I’m a very new user with her fresh first-time multi-site installation (working installation, at least!), I have very little to contribute on the second part, but I described my first-time experiences and ideas that came up in the Textpattern 4.4.0 released thread. To avoid duplication, I’ll just link to my first post there – it goes on a bit from there with a few replies and further attempts at clarification from me.

Causes of problems

From my (admittedly inexperienced) point of view, there are several causes for the problems encountered (not just me, I see some of that in other reports, too):

the devised construction with directory structures, symlinks and virtual host definitions (as described in the README file in the sites directory) is sane, but the description of the installation process misses a few points
the main README (for a normal install) suggests installing in a webroot but does not mention (let alone refer to) the multi-site install where this actually should be avoided
the directory structure as provided misses a few files or the installer script is insufficiently aware of the multi-site construct to actually provide these files.

In summary: the ideas are sound, and most of the directory structure is there, but both documentation and the installer script are missing a few beats. The result is (unavoidably) an installation that gives errors as soon as the installer is finished – not a good out-of-the-box experience for a first-time user (I very nearly gave up at that point).

I jotted down some ideas today for possible improvements:

Documentation

Platform

document that the ‘standard’ multi-site setup will only work on Unix/Linux servers because it relies on Unix-style symlinks
- (newer) NTFS can do hard links and symlinks, too (on the file system level, but Vista has exposed these in the UI), but the technology is different, so the the symlinks in the installation image will not work as such on a Windows platform
- this also implies you should not unpack the installation image on Windows and then upload the resulting files (I haven’t tested this but it will probably destroy the provided symlinks; if you want to try, at least make sure you upload as binary)
- it is at least possible to re-create the symlinks on a server running an appropriate version of Windows (maybe Server 2003, certainly server 2008 should be capable). I have no access to such a server, so I can’t test this, it’s pure theory
make it clearer in the documentation that multi-site installation method as described is possible only on some hosts, because of the need to create/edit files outside the webroot and edit httpd.conf: you cannot create virtual hosts with only .htaccess so you’ll need at least partial root access

Missing

missing in the ‘sites’ README:
- install (unpack) the whole image to a directory outside any webroot (you’ll be creating webroots via the httpd.conf file(s))
- the ‘main’ README says: “Extract the files to your site (in the web root, or choose a subdirectory).” — this should include a reference to the ‘sites’ README for multi-site (or more secure!) install which in turn should mention to not place it in web directory but outside it (see above)
- so, to start with, you could even get the installation image via wget (document)
- it would be helpful for Linux beginners who do have (SSH) access, to outline the basic commands needed to download, unpack, and create new site directories in the sites tree (give complete syntax, and paths and cd commands needed)
the ‘sites’ README gives examples for virtual hosts, but should mention to replace :80 with :443 (ports) for a secured (SSL) admin area (if you have the option to use SSL)
- even if you don’t have a certificate of your own, a web host often supplies a ‘shared’ one you can use; this will require you to explicitly accept your host’s certificate in your browser, but will at least encrypt your login and thus secure your admin password

Errors

documentation errors/omissions in the ‘sites’ README:
- it tells you to secure the site by removing some files and symlinks; it should also tell you that the (current) warning in Diagnostics to remove the textpattern/setup directory should be ignored (at least if you want to retain the option to set up another site off the same code base); and there’s no harm keeping it where it is since in a mutli-site configuration it’s not web-accessible, and neither is the sample ‘site1’ subtree (with the symlink to this directory) which isn’t mapped to any webroot

Structure / readability

it would be helpful to include a small table of contents near the top of the ‘sites’ README so get an overview of what you must read or may skip
- rationale: I used the admin in separate subdomain method and thus stopped reading at the end of this section thinking I was done — with the result I completely missed the (important) ‘Additional Miscellany’ section at the end of the file… not a must-do but certainly a should-read section

Possible installer improvements

improvement tip:
- because the ‘site1’ tree contains the necessary symlinks (and some of the necessary files – see next point) it should not just be renamed to use for an installation: better to keep it as a model and use the cp -R site1 site2 method mentioned in the README to create the basis for a new site
- to make this clearer, ‘site1’ in the installation image could be renamed to something like ‘sitexmpl’ (with instructions in the README to match): not the ‘first site’ but an ‘example’ directory structure
- the documentation should of course be adapted to reflect not just the new name but to emphasize its (new) role as a template

the example ‘sitexmpl’ subtree in the ‘sites’ directory misses a few files (.htaccess in public, .htaccess-dist in public/files), leading to problems after the installation is finished; two possible solutions:
- provide these files (as copies from those in the base textpattern tree) in the ‘sitexmpl’ subtree (con: need to make sure these copies are kept up to date if the originals are updated in a new release)
- make the installer more ‘aware’ of multi-site so it can do the necessary copying unassisted (pro: making the installer ‘multi-site aware’ is necessary for other reasons anyway): with some user input, mainly for confirmation, the installer script should be able to deduce a multi-site install, and derive (and record!) separate paths and URLs for both the main site and the admin area (whether it’s in a subdirectory or a subdomain)
- if the installer correctly deduces the multi-site situation, it will be able to copy any necessary .htaccess and other files from the main tree to the current site tree, avoiding errors and problems after installation
- if the installer correctly records URLs and paths in the database (for main site as well as admin area), incorrect links to the admin area from the ‘Welcome’ document can be avoided, as well as a whole number of bogus errors reported by the Diagnostics function

if you have access to a server where this ‘standard’ multi-site setup is possible (SSH/shell access and at least partial root access) here’s another idea:
- it allows you to keep almost all of the source code out of your site’s webroot, so you could consider this for a single site, too: it’s simply more secure (I always try to keep as much as possible out of the web root, especially things like configuration files)

most web hosts (nearly all shared servers, certainly all VPSs) give access to at least one level up from your web root; it may be possible to create a variant of this multi-site ‘model’ that doesn’t require symlinks/root access but relies on PHP require/include statements (Jojo does this, for example): this would make a more secure installation possible even on fairly simple shared hosts, and even on Windows servers without the possibility for the user to create symlinks)

—

So far my ideas for how the installer and accompanying documentation could be improved to avoid technical problems as well as some human confusion.

I had some fun today installing some plugins – especially making one work on my multi-site installation: I’ll report that in a separate post.

Cheers,

marjoleink · 2011-04-28 00:57:53

maverick wrote:

Plugins that do not work with Multi-Site Installs, and/or need to be modified to work

Here’s another: atb_editarea, when installed according to instructions, does not work at all. The solution is not a tweak in the plugin itself, but an extension to the multi-site mechanism of using symlinks, as described here.

The problem is not a matter of plugin code, but the fact that the location of the EditArea JavaScript (which the plugin merely ‘makes available’) needs to be browser-accessible. By adding a symlink from inside the sites/[sitename]/admin directory to the edit_area directory placed in the main textpattern installation directory, the script becomes browser-accessible in exactly the same way it is for a normal single-site install, when following the exact same installation instructions for the plugin.

There’s another similar plugin soo_editarea (I haven’t tried that (yet)) which makes the location of the script configurable. But since the EditArea JavaScript needs to be browser-accessible, it’s likely the same symlnik mechanism would be needed anyway.

Takeaway: If EditArea ever gets included as part of the Textpattern distribution (which I hope), it should be provided in the same location in the tree as the installation instructions for the atb_editarea plugin now suggest, and there should be an extra symlink in the sample admin subdirectory (just like there is a theme subdirectory symlink there already): that way, with copying a ‘site’ subtree to set up a new site, the reference to the EditArea JavaScript would automatically work (without any need to configure the location).

Cheers,

Last edited by marjoleink (2011-04-28 01:18:34)

Textpattern CMS

Textpattern CMS support forum

#1 2011-02-10 16:06:04

[wiki] Multi-Site Install Quirks

#2 2011-02-10 16:08:08

Re: [wiki] Multi-Site Install Quirks

#3 2011-02-10 16:10:18

Re: [wiki] Multi-Site Install Quirks

#4 2011-02-10 16:11:55

Re: [wiki] Multi-Site Install Quirks

#5 2011-02-10 16:12:57

Re: [wiki] Multi-Site Install Quirks

#6 2011-02-10 16:13:45

Re: [wiki] Multi-Site Install Quirks

#7 2011-03-19 04:01:33

Re: [wiki] Multi-Site Install Quirks

#8 2011-04-27 23:08:45

Re: [wiki] Multi-Site Install Quirks

#9 2011-04-28 00:57:53

Re: [wiki] Multi-Site Install Quirks

Board footer