Simplifying and improving reliability of the TXP install procedure

[gomedia-adi]

Upgrading Textpattern is currently a relatively simple procedure – as detailed here:

Copy the contents of the textpattern folder to the server’s textpattern folder. You may exclude the setup directory, since it is only used for first-time installations.

The instructions are clear, i.e. “Copy the contents” of the Textpattern folder.

Now that life is getting more complicated:

• TXP 4.6 admin themes (& maybe it always was with multi-site installs)
• Different operating systems and FTP clients implementing "merge" in varying degrees of functionality

... the "copy" bit of the instructions really means "merge with care & cognisance".

Can we improve the situation by:

1. Moving all non-standard (i.e. not included in the distribution) files/folders somewhere else, so there's little danger of overwriting them by mistake during upgrades. Perhaps config.php is the place to contain paths to user templates, css, js etc etc; or just have a set directory structure where TXP always looks for "additional stuff".
2. Providing a install script that does all the hard work (this is probably not even possible for all scenarios - FTP, Linux, Windows etc)
3. If all else fails, flesh out the installation procedure to highlight the dangers.

Discussion open to the floor ...

[Bloke]

Fleshing out the instructions is the path of least resistance for now, so we should do that anyway. Presumably they're editable on Github or Crowdin somewhere and will become the de facto docs over the wiki you linked above.

The install script doing more things itself is something we've considered in the past. But the technical barriers such as ensuring the apache user has the ability to write to the textpattern folder that we normally recommend remains read-only, or to open up user permissions to be able to create files and directories outside docroot, normally mean we shelve the idea in favour of just getting the user to write the file and upload it themselves.

[EDIT: that's the reason the tmp directory is inside the textpattern dir. It's not ideal -- far from it -- and I always move mine outside docroot, but we have to have somewhere to stash temp files and can't rely on the ecosystem outside a Textpattern installation to be consistent, so we choose to put it inside by default, even though it could cause problems, and give the user the ability to move it via a pref. We don't have that luxury with config.php because it is fundamental to the database connection.]

Regarding moving all user-centric files out of the package, as I touched upon in the forum thread, the problem with having a fixed location is that, to satisfy the "do not clobber" functionality of some file managers, the fixed location must be outside docroot.

Imagine I house many installations on a host (which I know a lot of people do). We then have:

/var/www/example.org/index.php
/var/www/example.org/textpattern/...
/var/www/example.com/index.php
/var/www/example.com/textpattern/...
/var/www/well-known-txp-dir/...

Now, example.org looks in well-known-txp-dir for config.php. As does example.com. Uh-oh, they can't both have the same config file. Same with theme-specific customisations. Besides the hurdle of asking users to create this folder manually during installation and putting files in it, we have the added complication that we'd have to change the file's internal structure so each installation could have its own 'section' within the file.

That, in turn, complicates backup procedures as everything's not self-contained any more. You need to also back up the well-known-dir, which means that its restoration impacts other installations. And you can't just use a different file name for each installation because, well, where do you define the file name? In another file inside docroot? Which would then be trashed by over-zelaous OSX-based FTP clients on upgrade....argh!

I'm not saying it'll never happen, I'm saying there a re a lot of barriers to doing it well without introducing a tonne of other issues that make life more complicated elsewhere.

imo, educating users through better documentation to ensure they're doing a merge not replace is the most effective solution, so let's start there and work up.

[gomedia-adi]

Thanks Stef. I appreciate your analysis on the subject.

"Educating users through better documentation" is a fine goal to aim for.

[philwareham]

Hi. yes the documentation is in GitHub - the page you want is here: https://github.com/textpattern/textpattern.github.io/blob/master/installation/upgrading-downgrading-txp.textile

All the pages need to be converted to Markdown as Jekyll has dropped support for Textile now (I've done all the tags pages and a few others but not had time to recode all pages yet).

[Bloke]

Haven't converted it to Markdown yet but I've made a few amendments. Could probably do with being a bit tighter overall.

The whole section about downgrading is misleading at best. It's not as simple as reversing the process because we don't have the concept of undoing the DB changes. The only way to go back cleanly is to revert to a backup. To downgrade you need to replace all the files with the ones from the earlier version and then undo every DB and filesystem change that takes place in the upgrade script(s) between the version you're rolling back to and the one you have. Once you've done that, you have to then roll back the version string in the txp_prefs table.

It's non-trivial at best. And if the column widths have changed, data loss would likely occur.

I propose axing that entire section (which means changing the doc title to remove reference to downgrading) or flesh it out with a more truthful procedure.

[philwareham]

Agreed, let's remove the downgrade section - I will do that today (and make it Markdown).

[philwareham]

I've removed all references to downgrading in the new documentation site, as suggested.

[philwareham]

Closing this as we have documented the info. New issue created specifically to address showing the diagnostics panel after an upgrade/install.