install on windows info needs work

[Jason Sachs <jm...@gmail.com>]

I have Windows XP and would like to install Couchdb 0.9.0. I reread
the "Installing on Windows" wiki
(http://wiki.apache.org/couchdb/Installing_on_Windows) and took a
whack at it, after realizing that it wasn't so daunting as it first
seemed (the javascript and couch_erl_driver had premade binaries; if
this weren't the case I wouldn't touch it as I find compiling C
source, especially Spidermonkey, a nearly-hopeless cause).

I made some progress but still hit a brick wall, and have several
comments to hopefully improve the wiki; not sure where/who to send
them to, so I'm posting here. Apologies if I sound irritated; it's
been a long day.

Dependencies:

Erlang/OTP: ok, this has an installer for windows.
ICU: ok, there are instructions later for where to install it.
OpenSSL: Where does this come in? It's not talked about at all later.
Everything else: not strictly necessary. *Please* don't scare away
reasonably knowledgeable users on Windows by bringing up gcc + make.
You later mention there are prebuilt Spidermonkey and couch_erl_driver
binaries. Add an appendix at the end telling users how to build these
binaries if they are in the mood to do so.


Install CouchDB as an Erlang Library Directory: ok.

Provide ICU to Erlang: ok.

Build SpiderMonkey: Again, put this somewhere in an appendix. If
you're providing Spidermonkey binaries it would be good to provide an
MD5 hash and/or PGP signature to verify download integrity.

Build couchdb/couch_erl_driver.c: same comments

Erlang Compilation: ok

Configuring:

   "Copy the default.ini.tpl.in file to {ERLANG_ROOT}/bin or
{COUCHDB_ROOT} " (you use explicit directories in instructions, I tend
to use templates, as you don't literally mean the exact directories
given, since they may be different on my computer, and that forces
users to do pattern-matching to try to figure out which parts of the
literal string should be taken literally and which should be altered
as necessary)
OK, there are two choices here, which one is it???? (more comments later)

   "Edit the file to look something like this: "
AAAARRRRRGGGGGHHH! Please don't use that phrase. Either you want the
file to be edited to the text you gave (which isn't the case), in
which case you don't need the file default.ini.tpl.in, or what you
really want is to use default.ini.tpl.in to be a template file with
the strings %some_identifier% to be replaced with appropriate values,
in which case you should *tell* people that's what they should do, and
give them guidance on what these strings should be. I had to really
put on my thinking cap to figure it out, which I think I finally did,
and I wrote a short Javascript script to use with JSDB (www.jsdb.org)
to do the substitutions. (see attached, I hereby release to public
domain)

   "Make sure that the database_dir exists and that the LogFile can be created."
Again, you mean that the directories mentioned in the default.ini for
the [couchdb]database_dir and [log]file entries should both exist
prior to running. Please state this more clearly.

Running:

1) Which directory should I launch "erl" in? I did it from
{ERLANG_ROOT}/bin which appears to work ok, but I'm not sure.
2) Running couch_server:start() bombs. If I put default.ini into
{COUCHDB_ROOT} -- which I'd rather do, since "default.ini" sounds
general enough that if I stick it in a common directory in Erlang's
binary directory I wonder if it might conflict with something else --
I get this message:

1> couch_server:start().
** exception exit: {bad_return_value,
                       {startup_error,
                           [67,111,117,108,100,110,39,116,32,102,105,110,100,
                            32,115,101,114,118,101,114,32,99,111,110,102|...]}}

Great. Now I have to put on my thinking cap and my magic ASCII secret
decoder ring to figure this says "Couldn't find server conf" which
doesn't help me.

If I put default.ini into {ERLANG_ROOT}/bin, and I change the log
level to debug (again, please state this more clearly, you mean the
property [log]level = debug in default.ini), I get a little bit
further, but I still don't know what to do:

1> couch_server:start().
Apache CouchDB 0.0.0 (LogLevel=debug) is starting.
Configuration Settings ["default.ini"]:
  [couchdb] database_dir="c:/data/couch/data"
  [couchdb] max_attachment_chunk_size="4294967296"
  [couchdb] max_dbs_open="100"
  [couchdb] max_document_size="4294967296"
  [couchdb] os_process_timeout="5000"
  [couchdb] util_driver_dir="c:/appl/erlang/OTP_R13B01/lib/apache-couchdb-0.9.0/
priv"
  [couchdb] view_index_dir="c:/data/couch/data"
  [daemons] db_update_notifier="{couch_db_update_notifier_sup, start_link, []}"
  [daemons] external_manager="{couch_external_manager, start_link, []}"
  [daemons] httpd="{couch_httpd, start_link, []}"
  [daemons] query_servers="{couch_query_servers, start_link, []}"
  [daemons] stats_aggregator="{couch_stats_aggregator, start, []}"
  [daemons] stats_collector="{couch_stats_collector, start, []}"
  [daemons] view_manager="{couch_view, start_link, []}"
  [httpd] WWW-Authenticate="Basic realm=\"administrator\""
  [httpd] authentication_handler="{couch_httpd, default_authentication_handler}"

  [httpd] bind_address="127.0.0.1"
  [httpd] port="5984"
  [httpd_db_handlers] _design="{couch_httpd_db, handle_design_req}"
  [httpd_db_handlers] _temp_view="{couch_httpd_view, handle_temp_view_req}"
  [httpd_design_handlers] _list="{couch_httpd_show, handle_view_list_req}"
  [httpd_design_handlers] _show="{couch_httpd_show, handle_doc_show_req}"
  [httpd_design_handlers] _view="{couch_httpd_view, handle_view_req}"
  [httpd_global_handlers] /="{couch_httpd_misc_handlers, handle_welcome_req, <<\
"Welcome\">>}"
  [httpd_global_handlers] _active_tasks="{couch_httpd_misc_handlers, handle_task
_status_req}"
  [httpd_global_handlers] _all_dbs="{couch_httpd_misc_handlers, handle_all_dbs_r
eq}"
  [httpd_global_handlers] _config="{couch_httpd_misc_handlers, handle_config_req
}"
  [httpd_global_handlers] _replicate="{couch_httpd_misc_handlers, handle_replica
te_req}"
  [httpd_global_handlers] _restart="{couch_httpd_misc_handlers, handle_restart_r
eq}"
  [httpd_global_handlers] _stats="{couch_httpd_stats_handlers, handle_stats_req}
"
  [httpd_global_handlers] _utils="{couch_httpd_misc_handlers, handle_utils_dir_r
eq, \"c:/appl/erlang/OTP_R13B01/lib/apache-couchdb-0.9.0/share/www\"}"
  [httpd_global_handlers] _uuids="{couch_httpd_misc_handlers, handle_uuids_req}"

  [httpd_global_handlers] favicon.ico="{couch_httpd_misc_handlers, handle_favico
n_req, \"c:/appl/erlang/OTP_R13B01/lib/apache-couchdb-0.9.0/share/www\"}"
  [log] file="c:/data/couch/log/couch.log"
  [log] level="debug"
  [query_servers] javascript="c:/appl/erlang/OTP_R13B01/erts-5.7.2/bin/couch_js.
exe c:/appl/erlang/OTP_R13B01/lib/apache-couchdb-0.9.0/share/server/main.js"
** exception exit: "This application has failed to start because the application
 configuration is incorrect. Reinstalling the application may fix this problem."

     in function  couch_util:start_driver/1
     in call from couch_server_sup:start_server/1


Gee, that's a helpful error message.

I know this is "free" software and there are limited resources out
there to get things going, but it's rather frustrating to be unable to
install couchdb on my Windows machine. I have a Mac at home and it's
really easy to get couchdb started, thankfully. I don't mind doing
some manual install steps that are a bit more complex, but when those
steps don't work it's really a turnoff.

--Jason Sachs

/* autogen.js: run this in the same directory as default.ini.tpl.in,
AFTER substituting appropriate directories in the "settings" section,
and it will create a default.ini file if you run this file with JSDB
(http://www.jsdb.org). */
var settings =
  {
    dictionary:
    {
      erlangroot: 'c:/appl/erlang/OTP_R13B01',
      bindir: '%erlangroot%/erts-5.7.2/bin',

      couchroot: '%erlangroot%/lib/apache-couchdb-0.9.0',
      localstatelibdir: 'c:/data/couch/data',
      localstatelogdir: 'c:/data/couch/log',
      localdatadir: '%couchroot%/share',
      couchprivlibdir: '%couchroot%/priv',
      couchjs_command_name: 'couch_js.exe',
    },

    init: function()
    {
      var dict = this.dictionary;
      this.dictionary = {};
      var todo_q = [];
      for (var i in dict)
      {
        todo_q.push(i);
      }
      while (todo_q.length > 0)
      {
        var todo = todo_q.shift();
        result = this._match(dict[todo]);
        if (result.notfound > 0)
        {
          todo_q.push(todo);
        }
        else
        {
          delete dict[todo];
          this.dictionary[todo] = result.replacement;
        }
      }
    },
    _match: function(s)
    {
      var dict = this.dictionary;
      var retval = {found: 0, notfound: 0};
      retval.replacement = s.replace(/%([a-zA-Z0-9_]+)%/g,
         function(str,p1,offset,s)
         {
           if (p1 in dict)
           {
             ++retval.found;
             return dict[p1];
           }
           else
           {
             ++retval.notfound;
             return s;
           }
         }
       );
      return retval;
    },
    match: function(s)
    {
      return this._match(s).replacement;
    }
  };

settings.init();

var S = new Stream('default.ini','w');
var S_in = new Stream('default.ini.tpl.in');
S.write(settings.match(S_in.readFile()));
S_in.close();
S.close();

Re: install on windows info needs work

[Noah Slater <ns...@apache.org>]

Jason,

Thanks for your email, the information you have provided is very helpful.

However, I did just want to point out that:

  * CouchDB does not support Windows at this time.

    Any Windows documentation is community owned, so YMMV.

  * The documentation found is on a wiki, which means anyone can edit it. What
    you were working from has been distilled by other motivated users, such as
    yourself, who took the care to correct things and add more instructions.

    Along those lines, please edit the wiki to incorporate your own feedback.

Thank you for taking the time to feedback to the list!

Best,

-- 
Noah Slater, http://tumbolia.org/nslater