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

Tue May 21 10:08:39 UTC 2013

> >> 1. Package installs have the `ckan` command, source installs don't
> 
> >> 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)
> 
> This doesn't make sense to me. The ckan command is the right way of
> running commands on a package install. It is much simpler and you
> don't have to worry about virtualenvs or config files, simplifying
> things both for the users and for us when giving support. In my
> opinion that far outweighs using the same commands on both install
> types, so the ckan command should be the standard on a package
> install, and if we can make it work with a source install great (I
> don't think we will), if not perhaps we'll have to live with 2 ways of
> running paster commands.

The problem we're seeing currently is that the package install docs are
the only page of the docs that mention the ckan command. As soon as
someone moves beyond that page (eg. to the Post-Installation Setup page
that tells you what you have to do to create your first sysadmin user!)
they encounter instructions that tell you to run paster commands, and
when they try to run these commands they crash with unhelpful error
messages (because they haven't activated their virtualenv and changed to
the ckan dir, because the package install docs use the ckan command and
don't cover this). And using the paster command continues throughout the
rest of the docs.

(This also happens with example commands written on IRC, on mailing
lists, SO, the wiki, in README files of extensions...)

How can we fix this, as long as package install and source installs
have two different command-line interfaces?

We can't go through everything and change every example paster command
to a ckan command, because then they won't work for people who've done a
source install.

It seems crazy to go through everything and wherever an example command
is given, change it to say "If you did a package install run this
command ... And if you did a source install run this command" (and have
to say that to every support request as well).

So from the docs/support point of view, to me it seems the only sane
thing to do here is make it so that the package and source installs have
the same command line interface. This can be the ckan command, but only
if the ckan command also works on source installs, so currently it's the
paster command.

Then we can write good docs for that command-line interface, including a
good troubleshooting section with common errors when running commands,
and place those docs where people will come across them whether they did
a package install or a source install.