[ckan-dev] Source install/deployment docs

Thu Apr 25 15:58:33 UTC 2013

(See: https://github.com/okfn/ckan/pull/821)

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:

- But if you want to do multiple sites you would create subdirs here
- But if you wanted to do multiple sites you would make a db and user
  named after each site here, not a "ckan" one
- etc (datastore setup, apache setup, filestore setup...)

I also think that _just_ documenting the single-instance setup (no
popouts) is bad, because that's not the setup we actually use, so we
will need to duplicate the docs to document our own internal procedures.

So I'm again drawn towards the solution (currently implemented in the
pull request above) where the install-from-source docs describe the
multiple-instances-on-a-server setup that we use on our own servers.

One process that we both use ourselves and recommend to others, no
spaghetti docs, no duplication.

The thing is, the single-instance package install is going to be the
quickest and easiest. You would only be doing a source install if you
can't do a package install for some reason:

- You're installing on an unsupported OS that we don't have a package for
- You want multiple instances on one server
- You want separate postgres and ckan servers
- Some other setup customisation that the package install doesn't provide
- You're a dev

All these people could benefit from education about what all the moving
parts are and how they fit together and that, rather than simplicity,
may be the role of the source-install docs.

If we want to automate it then we have one documented procedure that we
can automate, and both OKFN and our users can benefit from the same
automation.

If some client or partner _does_ end up wanting multiple instances on a
server one day, they will not get bitten in the butt by a
single-instance layout.

I'll think about it some more over the weekend