[ckan-dev] Developer installation instructions

[David Read]

> The documentation's installation instructions are fairly imposing and
tell me to do a lot of things

Yes I would like to reduce the verbosity. People miss key instructions
because it is too wordy. But there every note, tip, explanation and warning
is in there because of differences between machines, misunderstandings,
time spent answering questions and time spent investigating problems. Of
course, if there genuinely is stuff that is not useful then we should
remove it.

> the documentation makes me use "pip install -e git+[github repo]" which
tucks the source code away inside the virtual environment

Personally I clone my dev repo to ckan rather than pyenv/src/ckan too. But
it is more difficult to explain because it involves an extra step - "git
clone git+..." and then "pip -e install ckan" rather than just "pip -e
install git+...". I believe most of the team have their source in the
virtual environment without bother, and it matches all the package and
source installs we've ever done. Also, these instructions are aimed more at
people installing CKAN to run, rather than developers like yourself, so is
difficult to justify the extra complexity of another command.

> None of those apt-get lines applied to me

Every OS has their way of installing the basic tools, and I think it is
worth spelling out all in one go. "apt-get" is an example syntax that most
people understand. I think these are essential to avoid reams of support
requests.

> Creation of the Postgres database could be a separate section before this
(currently it appears halfway through the installation instructions).

Actually some people just want to read the CKAN source, so I think that
should be first. The postgres setup is in step 6, nicely split up from
everything else. I don't think creating a db user and db for this CKAN
instance is a 'pre-requisite' to be hived away from the 'main' install of
the CKAN source.

> Solr could be split out into another pre-requisite stage.

Same thing - it's just another thing on the list to set-up that is crucial
and specific to CKAN.

> Create the data directory" can be dropped entirely because I didn't do
that and it somehow exists.

It looks like Beaker creates this when you first "paster serve". I think
this instruction was in there originally to ensure the correct file
permissions were set, which we don't do now, what with the data (cache)
directory being in home. Any objections to taking this step out?

> pip-requirements.txt seems useless: If I've got it, I have *already
cloned the repo*, but if I use them, pip will *clone the repo again* from
github.

It's used in the debian packaging system to specify dependencies for
different branches of CKAN.

> pip-requirements-prerelease.txt is out of date

Agreed, we don't need that file any more.

> pip-requirements-test.txt -- I don't know what that's for.

These are extra requirements (dependencies) for running the CKAN tests.

> Activate the environment::

This warrants an explanation as we've had countless people getting in knots
with this step.

> pip install --ignore-installed -r requires/lucid_conflict.txt -r
requires/lucid_present.txt -r requires/lucid_miss

This causes lots of problems for people with compiling lxml and other big
libraries.

> Create a development.ini launch configuration with your chosen extensions
etc.

Um I think this needs rather more explanation than just this sentence, this
step!!

I would like to remove the lines that tell you to: deactivate and then
activate the pyenv again (after installing the CKAN deps). I've never
needed this, with a range of old and new pip versions, but James thought it
fixed something once. Have you seen it since or can I remove it?

Dave

On 22 November 2011 18:27, Tom Rees <zephod at gmail.com> wrote:

> I've just had to reinstall from the github repo, and coming at it from
> scratch I tried to install CKAN neatly while logging my actions. I've tried
> to do it in a similar way to other OKFN projects (eg the webstore), where i
> clone the repo, create a virtualenv, and install the project (CKAN prefers
> to install from github, effectively cloning the repo again somewhere inside
> the virtualenv).
>
> So here's what I've written up. Let's discuss it here on the list rather
> than replying to the gist.
> https://gist.github.com/gists/1386391
>
> _______________________________________________
> ckan-dev mailing list
> ckan-dev at lists.okfn.org
> http://lists.okfn.org/mailman/listinfo/ckan-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.okfn.org/pipermail/ckan-dev/attachments/20111122/24cdba81/attachment-0001.html>