Thursday, June 13, 2013

Why I am not recommending GeoNode

For the past few weeks, I've been working for a professor on a project involving geographical data.  As part of this project, I was asked to evaluate GeoNode.  So I looked at the website, and after wandering around for a while trying to get past the usual marketing bullshit (side note: Can anyone explain to me why so many open source projects these days have such enormous quantities of marketing bullshit?), I eventually found some real documentation.  It was in the form of a developer "workshop," however, so I was a bit leery of it.

After some further exploration, I determined that GeoNode was probably too large and complex for our uses; we have existing code and would likely need to scrap most of it, and a lot of the features GeoNode touts just aren't important to us (e.g. social media integration).  However, on the off-chance I was being overly pessimistic, I was asked to demo it anyway.  While trying to figure out how to get started, I found more documentation, this time in Read the Docs format.  Since Read the Docs is quite common in the Python world, I decided the latter documentation was probably more authoritative and certainly better organized.

I began with the quick installation guide.  I use Ubuntu on my laptop, so I assumed it would be a simple matter of adding a PPA and sudo apt-get install geonode.  Oops, there's no Raring candidate yet, we'll have to use the Quantal version instead.  I moved on to the configuration instructions.  Now, I only wanted to set up a little demo, so "production" is probably inapplicable in my case, but onwards all the same.

kevin@odin:~$ geonode createsuperuser
/usr/sbin/geonode: line 3: django-admin.py: command not found

OK, that didn't work.  /usr/sbin/geonode is mercifully a really simple shell script, so I just change django-admin.py to django-admin and try again.

kevin@odin:~$ geonode createsuperuser
Unknown command: 'createsuperuser'
Type 'django-admin help' for usage.

Well, that's interesting on multiple levels.  createsuperuser is a perfectly valid django-admin subcommand, and even appears in its help.  But usually, it's executed in the context of an existing Django project via manage.py.  The instructions I was given never told me to change directories or anything, they just said to run this and it would work...

I look through the complete installation guide, but that's about installing from source.  I certainly hope I'm not going to have to install from source.

I assume the PPA created a Django project for me, and confirm this by pointing a browser at localhost; I'm serving what appears to be a full-blown GeoNode installation via WSGI on port 80, but it hasn't had its static files collected yet, so it looks ugly and broken.  If I want to do anything with this project, I'll need to first find it.  So I run a locate geonode and come up empty.  Well, duh, I need to do sudo updatedb first!  With that sorted, I try the locate again and find lots of interesting files and directories, none of which quite look like a Django project.  I do manage to find a settings.py and urls.py, but the overall structure of the containing directory is nothing like any Django app I've ever seen.  I can't find a manage.py and am basically flying blind.

At this point, I decide to see if the first set of documentation might be more user-friendly.  Blundering around, I find a page for creating custom GeoNode projects.  These instructions look nothing like the instructions I found earlier and tell me to create a Django project.  At this point I'm pretty desperate to get something, anything, working, so I just go ahead and do so.  That works (though not without creating a rather worrying error; I also had to steal settings.py from the other installation), but I've still got Apache/WSGI serving port 80.  It's around this time that I turn to actually getting our data into the application, never mind which application.

GeoNode may be a Django project, but it doesn't actually use Django's ORM, so far as I can tell.  Instead, it uses a system called GeoServer to manage various sources of data.  Since they need to support non-SQL data, I suppose this makes sense, but I'm not feeling very charitable right now and the involvement of yet another layer of abstraction irks me.  GeoServer has apparently been set up properly by the PPA, so I don't need to do very much.  The default username and password aren't working, though, apparently because the PPA was intended for a production deployment, and we all know you can't have a default admin password on a production system.  I try to interact with GeoServer's config files, but get nowhere because GeoServer wants you to use its web interface or RESTful API.  After fiddling with my GeoNode installation, I eventually manage to create a functional superuser and get into GeoServer.  Why does GeoNode auth affect GeoServer, seeing as they're independent?  Dunno.  From this point, things actually go well enough that I don't really feel compelled to finish the story, but I will say this: I still have that WSGI installation on port 80, and I'm going to keep it until I demo the custom installation because I don't want to break the latter.

So why won't I be recommending this?  Well, aside from it not actually serving our needs (we already have some Django code, HTML, and other nice things that we'd have to rebuild or scrap), it has two entirely separate sets of documentation.  They don't really 100% agree with each other, and I wasn't able to get a simple installation done without hacking shell scripts, running locate commands, and generally making a lot of guesses.  Oh yeah, and I also had to install a Quantal PPA when Raring has been out for over a month and a half.

Yes, I could've just asked on a mailing list about this.  But that's not good enough: I was asked to have a report on this ready within the day, and mailing lists can take days to respond at all and weeks to resolve issues.  More abstractly, if I need to run to a mailing list just to install the damn thing, we're in trouble.  Under the circumstances, how can I recommend this in good faith?  If something goes wrong next week and I'm asked to fix it, how can I do so when I don't know the first thing about the installation?  If I was asked to roll my custom installation out to production right now, I wouldn't have the first clue where to start, particularly since the PPA already created and configured a production setup entirely by itself.  I suppose I'd need to graft the custom installation onto that.  How should I?  No idea.

Documentation isn't just for clueless end users; we saw this way back in 2006 when ESR played with CUPS.  A fancy landing page may be very nice and professional-looking, but it doesn't matter if you don't have usable instructions.

This is not a case of not having enough documentation, either.  This is a problem of never testing the documentation.  At some point, someone who knows little or nothing about the project should be given the installation instructions and asked to follow them.  Instead, this documentation assumes the end user knows where the packages will put the installation.

Of course, other packages might have put the installation somewhere else, so maybe the documentation can't have the installation location.  That's no excuse.  If the packages were capable of customizing the installation, they should have prompted for it with Debconf (and included a sane default).  If they're weren't, they should all harmonize on a particular sane default and document it.

One last thing: I'm sure GeoNode is a great product.  This isn't intended to imply otherwise.  But right now, its crappy documentation is tarnishing its brand.

3 comments:

  1. Hi Kevin

    GeoNode is a fast developing project. My sense is that the 2.0 or 2.1 release is the one you need to revisit. The dev team is also very responsive to feedback on docs or such like as they go. The docs have also undergone some revision in the last 2 months (though no one is saying they are complete yet).

    A couple of points:

    1 .The updated install guide is here:
    http://docs.geonode.org/en/latest/tutorials/admin/install/quick_install.html#quick-installation
    I am sure feedback on that would be welcome.

    2. GeoNode is very much a Django project
    (a) the manage.py is located in the root geonode directory
    (b) it has a link to the normal Django admin (after you login, click on the login name to see a drop-down menu)
    (c) the spatial data is managed by GeoServer, that is true, and the metadata is managed via GeoNode via pyCWS.

    ReplyDelete
    Replies
    1. Pleased to hear the situation has improved. Unfortunately, I am no longer on that project, so I will not be able to further investigate at this time.

      I would like to emphasize that I did not intend to single out GeoNode in particular. An enormous number of open source projects have extremely poor documentation, and for people like me, that is a deal-breaker. It is what causes developers to choose closed source solutions over open source solutions in numerous cases. This is a serious problem for the open source community as a whole, not just GeoNode.

      Delete
    2. I agree on the documentation aspect in general. My experience the GeoNode documentation is quite reasonable; and its not really that complex of a project in the first place. The documentation for Django, the underlying platform, is some of the best I have read. Anyway, my primary keys in choosing OS software over proprietary are (a) the community and (b) access to code.

      Delete

This is pretty much a free-for-all. If your comment is very hard to read (e.g. txtspk, l33t, ALL CAPS, etc.) I may fix it for you or remove it. If your comment brings absolutely nothing to the discussion (e.g. pointless flaming, spam, etc.), it is subject to removal, unless I find it sufficiently amusing. If you don't like my judgment, tough shit, it's my blog. If the blog post itself is old enough, your comment is subject to moderation, so don't panic if it's not visible immediately.