Re: [GMG-Devel] docs: Debian / rpm-based distros and sudo / root

[Christopher Allan Webber]

ayleph writes:

> On 03/06/2015 09:03 AM, Christopher Allan Webber wrote:
>> Jim Campbell writes:
>> 
>>> As things are now, our docs start out by saying, "If you're on a
>>> Debian-based system, do this . . . but if you're on a RPM-based system
>>> do that . . . " but those types of distinctions end after the mention of
>>> specific python packages (i.e., there are no Fedora/RHEL/CentOS
>>> instructions for which postgres packages to install). Based on this,
>>> should we include instructions for the Fedora/RHEL/CentOS family in the
>>> official docs, or should we focus just on Debian in the official docs?
>>> Right now, the instructions are 1/4-baked on the Fedora/RHEL/CentOS
>>> side.  
>> 
>> I think we should support them.
>
> My personal opinion, I'd suggest making the published docs more generic
> and putting more specific details that are subject to change (eg, the
> exact package to install on a certain distro) on the wiki. In the
> published docs, give the basic dependencies and their versions. Link to
> a page on the wiki that gives details about specific packages for
> specific distributions.
>
> The advantage of keeping the specifics on the wiki is that it can be
> updated between releases of the published docs (if a package changes for
> a distro), and people who use $OBSCUREDISTRO can add details about their
> distro to the wiki as they like.
>
>>> Personally, I would like to include that family of distros as an
>>> alternate, but don't want to muck-up the docs. It would be better to
>>> have a documentation set that people can follow-along w/o having to
>>> constantly "do this" for one platform or "do that" for another platform
>>> [0].  For now, I think it would be better to provide top-notch
>>> instructions for Debian, though. What do folks think?  This would mean
>>> removing the notes about RPM-based distros in the start, and moving
>>> those docs elsewhere. If folks would like to include Fedora/RHEL/CentOS
>>> in the official docs, I could add-in my Fedora/RHEL/CentOS stuff.  I’m
>>> not sure if it’s ready, though.
>> 
>> What do other projects do?  I wonder sometimes why things seem so much
>> harder for our docs than for other projects... maybe it's just because
>> end-user web applications are rare and all of them would be this hard
>> for ours, but maybe there is something clearer we could do better.
>
> We do some stuff other webapps don't. `./configure && make` is an oddity
> for a webapp, for sure. Using multiple package managers is an oddity.
> Not bundling extlibs is an oddity.

Installing external libraries with bower is becoming more common.

./configure && make is common of course with non-webapp applications,
but most webapp applications are also notoriously hard to package for
distros.  See below though...

> Most of the other webapps I've installed have been from tarballs with
> everything included. The docs give general instructions on dependencies
> and configuration, but you end up figuring out a lot on your own. Lots
> of them don't bother telling the end user about setting up user/group
> accounts, permissions, working directories, etc. because their target
> audience is someone who's used to doing this kind of stuff as an admin.

So this is part of the thing that I'd like to change.  We currently tell
users to install from git, and part of what I'm trying to work towards
is *that shouldn't happen* anymore, unless you're a developer or you
just really want to get the git checkout.

Our tarballs currently aren't, as far as I know, actually used by anyone.

We're not there yet.  I am not sure if we can get there by the next
release, but I want to be closer.

We're in a weird limbo state, at present, between a very webapp style
deployment system (which actually I think most web applications,
including us at present, do a lot of unsanitary things, which is why
getting ourselves packaged in debian/fedora/etc is taking forever, and
why it usually doesn't happen), and a more "normal" package...

> When installing a new webapp, I generally go through a lot of pain
> trying to set it up. If I get it right, I might document it on a wiki or
> blog post. The process is usually something like this:
>
> Download package. Extract. Configure. Attempt to run. Check log for
> failure. Install undocumented missing package x. Attempt to run. Check
> log for failure. Search interwebs for error y. Find a fix or workaround.
> Take notes. Nuke the install, which at this point is a complete mess.
> Create sensible user, group, and data directories. Reinstall the app
> following previous notes.
>
> And yes, this is the process I've gone through (numerous times) with
> MediaGoblin as well. I should compare my notes against the deployment
> instructions and see if I can offer anything. But the fact is,
> MediaGoblin with all of its dependencies is a lot more complicated than
> most webapps I've used.

I agree it's more complicated, and actually in this release, with
adding ./configure and make, *more* complicated than average.

It's with the aim of getting somewhere simpler, but...