[ckan-dev] More package install vs source install consolidation

[Sean Hammond]

I think people are doing package installs, and then getting confused
when they go onto later pages in the docs that mention eg. paster
commands that are designed to work with source install and assume
knowledge that's taught in the source install instructions but not in
the package install (such as how to activate your virtualenv before
running a paster command).

Example: https://github.com/okfn/ckan/issues/908

There are at least 3 differences between package and source installs
that are potentially causing problems:

1. Package installs have the `ckan` command, source installs don't

2. Package install virtualenvs have global site packages on, source
install ones don't

3. Separate package and source install docs, for example the source
install ones teach you about activating your virtualenv and changing to
the ckan dir before using a paster command, the package install ones
don't

Suggestions for each:

1. For now we should be telling everyone to use `paster`, not `ckan`,
because `ckan` only works if you did a package install. So we need to
tell people to activate their virtualenv and change to the ckan dir
before running `paster` (or point them to the docs that explain this)

The `ckan` command is simpler to use so maybe it should replace `paster`
in future but it needs to be made available to source installs as well
and the docs need to be updated to use it wherever they currently mention
paster.

I'm not sure how the `ckan` command can work when there are multiple
CKAN codebases installed on one server.

@nibel Do you want to look into this? (Making the `ckan` command work
with source installs and multiple CKANs on a server)

2. I remember discussing it but I can't remember why we turned on global
site packages for the package install.

This potentially creates differences between source installs and package
installs such as whether commands like `sudo apt-get install foo` or
`sudo pip install foo` will have an effect on CKAN (eg. getting rid of
error messages etc) or not.

This is a problem for docs and support imho, people will post solutions
that worked for them but that won't work for people who have a source
install.

If at all possible, I'd like to turn off global site packages on the
package install's virtualenv, to make it the same as the source
install's one.

@nigel Another thing for you to look into?

3. I'm meaning to look into consolidating the different paths through
the docs for package install and source install as much as possible,
both to reduce duplication and so that people don't come out the other
end with different levels of knowledge about CKAN depending on what kind
of install they did.

This has long been a problem with the package install -- we get way more
support emails from people who did package installs, who then go onto
make mistakes that they're helpless to understand because they don't
know about things like virtualenv. And the docs everywhere basically
assume you did a source install and have all that knowledge.

There's lots of other docs stuff to do so I'm not sure how soon I'll be
able to look at this.