[ckan-dev] Source install/deployment docs

Fri Apr 26 08:52:42 UTC 2013

> All, I'm having trouble with what we agreed on Skype this morning. If I
> change the source install docs to document a single-instance-on-a-server
> setup but add popouts explaining how people could modify it to do
> multiple instances, then it's gonna be spaghetti docs with loads of
> popouts on several pages:

Having slept on this, I think a possible solution might be: all three
installs (package install, source install, and OKFN's internal install
process) use the multi-instance layout that we use internally, **but**
use a default site ID (e.g. "default"):

/usr/lib/ckan/default
/etc/ckan/default
Database and database user names: ckan_default
and so on

David/Adria, I _think_ this still gives what you wanted for the package
install:

- Installing the package can both install CKAN and boot a default CKAN
  site, you don't have to run a command after installing the package to
  boot the site
- Everyone who does a package install has all their files in the same
  locations, they're not in subdirs with different site names
- But they are in a subdir named default, that's the difference

The source install instructions will also use this default subdir. On
our own servers, we can use the same layout except of course our sites
won't be called default.

There are just a lot of advantages to having the package install, source
install and OKFN's own internal processes (including Ansible scripts
that Joel and Nigel are working on) use the same filesystem layout and
naming conventions for databases, users, etc.

We can dogfood our own docs and not duplicate them. Throughout the docs,
and in support requests, whenever we want to give an example command or
file path we can use the default site ID. No more examples commands that
say things like --config=/path/to/your/production.ini. No more having to
ask people whether they did a package install or a source install.

If possible, I think it would be good to do this for the 2.0 package
install and source installs. The reason is, that introducing this in 2.1
will be a pain, when you consider people trying to upgrade.

Let me know what you think of this idea, and we can decide next week.

P.S. If we can't agree on this, my second option is for the package and
source install to be single-instance in /usr/lib/ckan and /etc/ckan and
not mention multi-instance at all, and then for us to follow different
docs internally.